viway — Project Knowledge Base Secretary

A VSCode extension that automatically maintains a structured project knowledge base in the .viway/ folder. It reads Claude Code and Codex CLI transcripts, runs a per-turn loop with workspace tools after every agent reply, and writes atomic ops through the OpenRouter, Anthropic, or Alibaba Cloud Model Studio API.

viway dashboard + settings

Current version: 0.38.0. Full history — CHANGELOG.md and GitHub Releases.

viway ships English-first; the in-product UI also offers Russian.

🌐 Website: vimoi.online/viway — overview & screenshots. viway is free (MIT) — if it's useful, 💜 support the project / donate (or use the Sponsor button on this page).

Why

Long conversations with coding agents blur quickly: decisions get lost in the scroll, new sessions don't remember what was discussed yesterday, facts get duplicated. viway turns the flow of conversation into a living wiki — with no manual work.

Memory survives /compact, VSCode restarts, and folder moves.
Multiple parallel Claude/Codex instances share one base and stop duplicating the same thing.
Decisions, open questions, and mission briefs are organized into folders with clear semantics.

What the extension does

Capability	How it works
Per-turn secretary	After every Claude/Codex `end_turn`, an agent loop runs (up to 50 iterations) with 9 workspace tools: `read_file`, `search_workspace`, `list_directory`, `read_git_log`, `read_viway`, `read_processed_history`, `check_existing`, `read_open_questions`, `query_viway`. It applies 1–5 ops per folder.
Harvest agent (✨ Harvest)	Full re-synthesis of a chosen folder. Up to 30 iterations of recon → write.
Stop hook auto-process	Claude Code hooks (`Stop` / `PreCompact` / `SessionEnd`) launch the agent automatically with a 5s debounce + 90s settle window.
Multi-source ingestion (0.27.0+)	Opt-in adapters beyond Claude/Codex: GitHub Copilot Chat (workspaceStorage delta-logs), Kilo Code / Cline-family (globalStorage tasks, cwd-bound), Gemini CLI (`~/.gemini/tmp/<sha256(ws)>/chats`), Antigravity IDE (plaintext brain artifacts; encrypted dialogs are never read). Exact-workspace privacy matching, per-source secretary hints (`viway.sources.<id>.analysisHint`), watch-based auto-trigger with the same 90s settle window.
Snapshot + restore	Snapshots `.viway/` before each run; roll back via QuickPick.
Live timeline	A turn feed with auto-scroll, edge-fade, and status color coding (processed / no_changes / partial / error / skipped / aborted).
Turn detail	A clickable block opens a webview with the tool-calls log, applied ops, and errors.
Settings webview	~40 settings: provider, model, depth, tools whitelist, prompts, sampling, routing.
Communicator endpoint	A local HTTP server on 127.0.0.1: `POST /query` (grep + LLM-summarize + semantic search via embeddings — over the `.viway/` wiki or the whole project, `viway.semanticSearch.indexScope`), `POST /recall` (deterministic ranking of closed T-questions with symptom/cause/fix), `POST /note` (a write channel for agents), `POST /imagegen` (image generation). Bearer auth, timing-safe compare.
Bundled skills	`viway-query`, `viway-recall`, `viway-catchup`, `viway-note`, `viway-mission-brief`, `viway-imagegen` — installed into `~/.claude/skills/` with one button.
Orchestrator	Coordinates two CLI instances (roles O = architect, D = implementer) through an approve gate. Mission state, anti-loop guards (max handoffs, cost cap), handoff verifier (`fs.stat` on the claims).
Skill Box	Project playbooks under `.viway/05_plans/playbooks/`: skills + human-verified scripts. Author via the `viway-playbook` skill or the panel; run, verify, and get suggestions mined from transcripts; opt-in enforcement gate (`viway.skillbox.enforceGate`) + SessionStart awareness (`viway.skillbox.sessionContext`).
Image generation (0.38.0 route)	Generate project images — icon / og / hero / mockup / illustration — via Codex's built-in `image_gen` tool (gpt-image-2), driven through `codex mcp-server` and billed to your Codex subscription (no API key). viway captures the image inline over MCP and writes the PNG to the output directory itself. Agents call the `viway-imagegen` skill or `POST /imagegen`; you can also generate from the dashboard Orchestrator → «🖼 Image gen» tab (prompt/preset, live status, results gallery). Off by default; safe-by-default staging in `.viway/`, opt-in project writes; settings section + a «Test Codex» button.
Multi-provider	OpenRouter (dozens of models), Anthropic (with prompt caching), Alibaba Cloud (Qwen). One API key each. Image generation runs on Codex (built-in `image_gen` / gpt-image-2) under your subscription.
Audit	A Markdown report: cumulative cost, status histogram, anomalies, last 20 turns, Stop hook boundaries.
Bundled fonts	PT Sans (Latin + Cyrillic) + JetBrains Mono in the VSIX — works offline / behind a corporate proxy.

Installation

code --install-extension viway.viway-v3

After installing:

Cmd+Shift+P → viway: Create .viway/ → pick a workspace.
Cmd+Shift+P → viway: Settings → set an OpenRouter / Anthropic / Alibaba key.
Cmd+Shift+P → viway: Install hook → auto-processing after every reply.
(Optional) viway: Install skills → bundled skills into ~/.claude/skills/.

Requirements

VSCode 1.90+
An API key for at least one provider: OpenRouter (has a free tier), Anthropic, or Alibaba DashScope.
Claude Code or Codex CLI to generate transcripts (~/.claude/projects/ and ~/.codex/).

The `.viway/` structure

Folder	Purpose
`00_archive/`	Snapshots for rollback (managed by the extension, do not edit)
`01_intent/`	Why the project exists — `about.md`, mission, scope
`02_inputs/`	External material — articles, RFCs, links
`03_process/`	Work journal — `daily/YYYY-MM-DD.md`, append-only
`04_relations/`	Relationship graph + architectural decisions
`05_plans/`	Active plans, specs, mission briefs
`06_open/`	Open questions (one file = one question); `_closed/` — closed ones with YAML frontmatter for `/recall`
`07_visualization/`	Themes, diagrams, visual artifacts

Key settings

API keys are stored in VSCode SecretStorage:

viway.openRouterApiKey, viway.anthropicApiKey, viway.alibabaApiKey

Active provider: viway.provider (openrouter | anthropic | alibaba).

Frequently changed settings (Settings webview):

viway.agentDepth (quick / standard / deep / unlimited) — max iterations per turn (5 / 15 / 25 / 50)
viway.maxOpsPerFolder (1–5) — op limit per folder per turn
viway.maxTokens — output budget per LLM call
viway.reasoning (off / low / medium / high) — thinking budget
viway.transcriptSource (all / claude / codex)
viway.processScope (lastSession / lastTurn / last5Turns) — scope for the manual ▶ Run
viway.autoProcess — auto-processing on the Stop hook (default true)
viway.preClassifierEnabled — deterministic SKIP of trivial turns (default true)
viway.skipTrivialContinuations — skip "continue"-style chunks even in manual mode
viway.excludedSessions — list of session UUIDs excluded from the auto-trigger
viway.legacyWorkspacePaths — old project paths after a folder move
viway.llmHttpTimeoutSeconds (default 120) — hard timeout on the LLM HTTP fetch

State persistence

.viway/.state/ (mode 0600 for endpoint.json):

File	Purpose
`processed.json`	Processing cursors per session + per-turn records
`harvest-history.json`, `harvest-logs/`	✨ Harvest history + detailed traces
`turn-logs/<session>.<endUuid>.json`	Detailed trace of each per-turn run
`cumulative-metrics.json`	Cumulative metrics (calls / tokens / cost / conflicts)
`processing-history.json`	Last 50 runs (for the dashboard)
`queries.json`	Log of `POST /query` requests (FIFO 100)
`snapshots.json`	Snapshot registry
`endpoint.json`	Communicator endpoint URLs + Bearer token
`mission.json`	Active orchestrator mission + history (last 20)
`note_inbox/`	Inbox for `POST /note` records until the secretary consumes them
`session-roles.json`	Session labels (`implementer` / `reviewer` / `O` / `D`)
`last-call.md`	Markdown diagnostics of the last LLM call

Workspace migration

When you move the folder, add the old path to viway.legacyWorkspacePaths — the secretary will find the old Claude Code transcripts in ~/.claude/projects/<encoded-path>/*.jsonl. Codex sessions aren't recovered (the cwd is baked into session_meta).

Diagnostics

Odd spend / too many iterations → viway: Audit secretary work (a Markdown report with anomalies and the last call inline).
The per-turn run writes nothing → click a block in the timeline → Turn detail → the Tool calls + Errors sections.
Harvest produced 0 ops → cat .viway/.state/harvest-logs/<folder>.<iso>.json | python3 -m json.tool (the finalAssistantText often explains why it skipped).
Transcripts not found after a move → ⚙ → Workspace alias paths.
VSCode doesn't see the new VSIX version → ⚙ → Maintenance → 🔄 Update extension (Reload Window).
"Hook not installed" after installing (Windows) → fixed in 0.9.23; if it recurs, open an issue.

Build from source

cd v3/extension
npm install
npx tsc --noEmit              # type check
npm test                      # vitest (640+ tests)
npm run verify:webview        # bundle + vm.Script for the dashboard inline JS
npm run package               # → viway-v3-<version>.vsix

Documentation

CHANGELOG.md — full release history
AGENTS.md — instructions for third-party code agents working with this repo
docs/ui-smoke-checklist.md — manual UI check before a release

License

MIT

viway — Project Knowledge Base Secretary

viway

viway — Project Knowledge Base Secretary

Why

What the extension does

Installation

Requirements

The .viway/ structure

Key settings

State persistence

Workspace migration

Diagnostics

Build from source

Documentation

License

The `.viway/` structure