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 in 20 seconds:
Current version: 0.57.1. Full history — see the Changelog tab on this page.
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.
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. Eager mode (default) processes a finished turn right after a short debounce (viway.autoProcessDelaySeconds, default 5s) instead of waiting out the settle window — no manual clicks; turn off via viway.autoProcessEager. Non-Claude agents (Codex / Gemini / Copilot / Kilo) auto-process the same way via file-watch. |
| 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 (oscilloscope) |
Turns render as a warm-amber radio oscilloscope wave on the dashboard dial — one node per turn, signal height = turn activity, dot colour = status (processed / no_changes / partial / error / skipped / aborted), the in-progress turn pulses. Adapts to the panel width; node count always matches the turn count. |
| 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-fella, viway-mission-brief, viway-marathon, viway-coordinator, viway-playbook, viway-imagegen — installed into ~/.claude/skills/ with one button. |
| Partner (0.56.0+) |
A working partner for the main agent: one Codex CLI session that takes one concrete task at a time and answers with a schema-constrained report — status (done/blocked/failed), summary, files touched, verify command. Runs headless (codex exec --json), so nothing is typed into a terminal and there is no TUI to fight. Context accumulates: the first task opens a Codex session, every later one resumes it, so the partner works sequentially and keeps everything it has learned. Hand over as many tasks as you like — they queue and run in order while the main agent carries on with its own work (the queue survives a VSCode reload). A blocked status means it stopped to ask instead of guessing — answer it from the dialogue or the dashboard and it continues in the same session. Every file it claims to have touched is checked with fs.stat, so a "done, tests added" that never happened is flagged, not believed. The main agent drives it via the viway-fella skill / POST /fellas/{task,answer,inbox,read,stop,reset}; reports land in .viway/03_process/fellas/ and survive a /compact. Its own dashboard cabinet «Напарник» streams the work live (commands, files, messages) and keeps the task history. Off by default (viway.fellas.enabled); needs the codex CLI installed + logged in. The same cabinet's «Напарники» mode holds the two-Claude pair below. |
| 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). Lives as the «Напарники» mode of the Partner cabinet (0.56.0); the Orchestrator cabinet itself is now a 3-tab observe surface — Coordinator · Marathon · Vizo. |
| Marathon (0.40.0+) |
A secretary-owned, living plan + execution tracker. For a non-trivial multi-step task the main agent authors the plan into a marathon (viway-marathon skill / POST /marathon/{create,next,report,refine,set-status,verify,list}) instead of a throwaway plan file that gets forgotten after a /compact. The agent drives it step-by-step; the secretary reconciles each reported step against the actual project (does the cited evidence file exist?) AND amends the plan to match reality — inserting newly-discovered steps, retiring obsolete ones, journalled to amend-log.md. A «Доп. проверка плана» button (0.46.0) / POST /marathon/verify re-audits the still-open steps against project evidence (daily log + git) and closes the ones already done — the safety net for when the agent shipped the work but forgot to report the last steps. Optional interception mode (a PreToolUse gate + dashboard toggle, viway.marathon.interceptPlanFiles) redirects plan/spec-file writes into a marathon so plans never go stale. Plans live in .viway/05_plans/marathons/; observe progress, % done, amendment history, and open the plan/spec files in the dashboard's «Марафон» tab. |
| Coordinator (0.41.0+) |
A parallel QA agent driven by the Gemini CLI. The main agent hands it a browser-testing task (viway-coordinator skill / POST /coordinator/{run,result,list,test}); viway spawns gemini with a browser MCP (Playwright by default, provisioned into .gemini/settings.json), the agent drives a real browser to exercise your running code, and returns a structured JSON report — verdict (pass/fail/partial/error), findings, console errors, steps. Sync (blocks for the report) or async (poll). An approval gate guards each spawn; for safety only the trusted browser MCP auto-runs (no blanket --yolo) unless you opt into viway.coordinator.unattendedMode. Off by default (viway.coordinator.enabled); needs the gemini CLI installed + logged in. Reports persist in .viway/05_plans/coordinator/; observe runs in the dashboard's «Координатор» tab. |
| Archivarius (0.49.0+) |
A user-triggered reviser that audits the .viway/ wiki against the real code + git and produces a report-only list of discrepancies — nothing changes until you apply a finding. Three independently-toggleable checks: Reconcile — closed-but-still-open questions, wiki docs citing files that exist nowhere in the project (basename-resolved, so module-relative/moved citations aren't false-flagged), and marathons that are fully done but still active; Stack conflicts (0.50) — a wiki-recorded decision the dependencies contradict (wiki says Tauri while every package.json has electron); File audit (0.51) — broken relative links across the project's markdown ([text](https://github.com/moiseenkovv-sketch/viway/blob/HEAD/path) pointing at a moved/deleted file). Findings live in the radio-styled «Архив» cabinet with per-finding Apply/Скрыть and a multi-select + bulk bar (Apply selected / Apply all / Clear list). Apply either annotates the wiki file with a ⚠ mark or archives it into 00_archive/ (reversible); every action is journalled to 00_archive/archivarius/apply-log.md. Snapshot management (list / restore / delete) moved into this cabinet too. POST /archivarius/{run,apply}, GET /archivarius/{list,result}; config viway.archivarius.{enabled,checks.*,maxFindingsPerRun}. Off by default. |
| 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 turnviway.maxTokens — output budget per LLM callviway.reasoning (off / low / medium / high) — thinking budgetviway.transcriptSource (all / claude / codex)viway.processScope (lastSession / lastTurn / last5Turns) — scope for the manual ▶ Runviway.autoProcess — auto-processing on the Stop hook (default true)viway.autoProcessEager — process a finished turn right after a short debounce instead of the full settle window (default true)viway.autoProcessDelaySeconds — debounce after the assistant stops before auto-processing (default 5)viway.modelCatalog.minContextTokens — only show models with ≥ this context in the provider pickers; 0 = all (default 1000000)viway.preClassifierEnabled — deterministic SKIP of trivial turns (default true)viway.skipTrivialContinuations — skip "continue"-style chunks even in manual modeviway.excludedSessions — list of session UUIDs excluded from the auto-triggerviway.legacyWorkspacePaths — old project paths after a folder moveviway.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
License
MIT
| |
