agentwiki

Architecture docs that stay honest. agentwiki generates C4-style architecture documentation for any repository — then double-checks the generated dependency claims against the real import graph, so drift between docs and code gets caught instead of shipped.

Every LLM call uses an already-authenticated agent CLI through agent-core. A CLI-agent-native rewrite of deepwiki-rs.

cd your-repo
agentwiki              # generate the doc set  → ./agentwiki.docs/
agentwiki drift        # verify claims vs code → .agentwiki/drift.json

What it is for

• Onboarding & handover — hand contributors a generated C4-style doc set instead of a wiki nobody maintains.
• Docs freshness in CI — commit the docs, then gate PRs with agentwiki drift --strict: new phantom/reversed claims fail the build, everything else stays a warning.
• Architecture review — undocumented findings surface real import edges the docs never mention; phantom/reversed expose claims the code contradicts.
• Any stack, any language of prose — static import extraction for Rust, Python, and JS/TS; docs render in en zh ja ko de fr ru vi.
• Local CLI backends — Claude, Codex, Devin, or OpenCode v2 on your PATH; billing environment variables are stripped so it uses saved authentication.

What it produces

agentwiki.docs/
├── 1.Overview.md
├── 2.Architecture.md
├── 3.Workflow.md
├── 4.Deep-Exploration/<Domain>.md   # one doc per detected domain module
├── 5.Boundary-Interfaces.md
├── 6.Database-Overview.md
├── agentwiki.claims.json            # the dependency claims, for drift/CI
└── __AgentWiki_Summary__.md         # timings, calls, cache hits

State, cache, and audit logs live in .agentwiki/ (gitignored).

Features

Documentation pipeline

• DAG pipeline — research agents (dir summaries, system context, domain modules, relationships, boundary, database) feed compose agents that write the docs.
• Two context modes — embedded (deterministic excerpts in the prompt) vs agentic (the agent explores the repo itself). See below.
• Multilingual output — --target-language en zh ja ko de fr ru vi.

Correctness guard — agentwiki drift

• Claims vs reality — compares relationships.core_dependencies against a statically-extracted import graph (Rust / Python / JS-TS): confirmed, structural, unverifiable, undocumented, reversed, phantom.
• Deterministic + read-only — no LLM calls; the only write is <internal>/drift.json. Exit codes are CI-friendly (0 warn-only, 1 strict gate, 2 claims missing).
• Noise-filtered — named filters (hub fan-in, thin edges, containment, test-only evidence…) keep the report small; a committed baseline turns --strict into "fail only on new problems".
• Coverage metric — the coverage: line separates "docs match the code" from "couldn't check", so uncheckable data_flow claims don't inflate the score.

Operations

• Content-hash cache — each call is cached by sha256(prompt‖model‖backend‖inputs) under .agentwiki/cache/. Interrupt any time; a rerun reuses everything that already succeeded.
• Incremental updates — --incremental fingerprints the tree each run (.agentwiki/manifest-*.json): cosmetic-only diffs become a 0-call no-op, structural diffs run the cache-accelerated pipeline. Per-domain agents only see their own domain's research slice, so unrelated edits don't churn their cache keys (embedded mode only — see note below).
• agentwiki status — freshness report: what changed since the last run, whether the next run is incremental or full, per-doc age.
• Safe to interrupt — Ctrl-C cancels cooperatively, kills in-flight CLI children, exits 130. A second Ctrl-C force-quits.
• Live progress — spinner bar shows [done/total] and running agents (auto-hidden when output is piped).
• Quota + audit — daily call cap (300/day default) and a .agentwiki/calls.jsonl audit log.
• Retries + fallback — schema validation failures retry with feedback; efficient-tier agents fall back to the powerful model.
• Run lock — a second concurrent run on the same repo fails fast (.agentwiki/run.lock, stale locks auto-reclaimed).
• agentwiki doctor — health check: CLI availability, agent processes, lock/quota/cache state, config sanity (--fix cleans up).

Examples

agentwiki documents itself — the committed docs/en/ (docs/vi/ in Vietnamese) is real pipeline output, and the committed claims file makes it verifiable even on a bare checkout:

$ agentwiki drift -o docs/en -v
claims: docs/en/agentwiki.claims.json (17 edges)
coverage: 11/17 claims checked (65%) — 6 unverifiable
  ok   10 confirmed (3 containment, 7 direct_evidence)
 warn  1 phantom
        src/output -> src/agent/reports [import, importance 3]
result: 1 finding(s) would fail under --strict

Yes — drift flags a phantom edge in agentwiki's own generated claims: the model wrote that src/output imports src/agent/reports, but the import graph says otherwise. That is exactly the failure mode drift exists to catch.

Two more verified walkthroughs live under examples/:

Example	Language	Story
taskman-py	Python	Real devin claims include a genuine hallucinated edge — drift flags it phantom. A curated claims file exercises all six finding classes.
notes-api-ts	TypeScript	The full generated doc set + claims, 14/15 confirmed, 93% coverage — what a green project looks like.

Prerequisites

Install and authenticate at least one CLI: Claude, Codex, Devin, or OpenCode v2. OpenCode major version 1 is not supported. The default backend is OpenCode v2; select another with a profile or model string.

Billing-related env vars (ANTHROPIC_*, OPENAI_*, DEVIN_API*, …) are stripped from spawned children. Authenticate the CLI you want before running agentwiki. For OpenCode, pending headless permissions follow its default; agentwiki does not enable automatic approval.

Use the CLI name to inherit its configured model, or provide a model. For example, opencode:<provider/model#variant>, claude:sonnet@high, codex:gpt-5.6-sol@high, or devin:swe-2-medium.

[models]
efficient = "opencode:openai/gpt-5#low"
powerful  = "opencode:openai/gpt-5#high"

Install

Prebuilt binary (no source checkout needed)

curl -fsSL https://raw.githubusercontent.com/tidusvn05/agentwiki/main/install.sh | sh

downloads the latest release binary straight to ~/.local/bin/agentwiki (Linux x86_64, macOS Intel & Apple Silicon; Windows binaries are on the Releases page).

cargo install

cargo install --git https://github.com/tidusvn05/agentwiki

From source

git clone https://github.com/tidusvn05/agentwiki
cd agentwiki && cargo build --release
./target/release/agentwiki --help

Quickstart

cd your-repo
agentwiki                            # OpenCode v2, configured default model
agentwiki opencode --target-language vi
agentwiki claude --target-language vi
agentwiki codex --target-language ja
agentwiki devin
agentwiki --model-powerful opencode:openai/gpt-5#high

Docs land in ./agentwiki.docs/; cache and run state in ./.agentwiki/. Watch the progress bar; interrupt any time — rerunning resumes from the cache for free.

Useful flags:

Flag	Effect
-p, --project-path	repo to document (default .)
-o, --output-path	docs output dir (default ./agentwiki.docs)
--agentic	let the agent read the repo itself instead of embedding code
--target-language	en zh ja ko de fr ru vi
--model-efficient / --model-powerful	<backend> or <backend>:<model> per tier
--max-parallels	concurrent CLI calls (default 2)
--dry-run	print resolved config + task DAG, exit
--skip-research	reuse .agentwiki/research.json, only recompose
--skip-documentation	stop after research
--incremental	no-op (0 calls) when only file contents changed since the last run
--full	force a full run, overriding incremental from config
--force-regenerate / --no-cache	cache controls
-v … -vvv	log verbosity (warn default)

agentwiki status

Read-only freshness report — the counterpart to doctor (environment) and drift (correctness). It diffs the recorded manifest of the last run against a fresh scan and tells you before spending calls whether the next run would be incremental or full:

agentwiki status           # human report, exit 0
agentwiki status --json    # machine-readable report
agentwiki status -o docs/en   # inspect a specific output tree

manifest: .agentwiki/manifest-9f2c… .json (2026-09-21T08:12Z)
git: documented at d4e11b7, 3 commit(s) since
research.json: 2d ago

classification: cosmetic
files: +0 −0 ~2 · dirs: +0 −0 · import edges: +0 −0
cosmetic-only edits pending in: src/drift
→ `agentwiki --incremental` would no-op (0 calls); a plain run rewrites from cache

docs:
  1.Overview.md — fresh (2d ago)
  4.Deep-Exploration/… .md — fresh (2d ago)

Classification is fail-open: new/removed files or dirs, import-graph edge changes, or a changed generation environment (language, models, prompts, scan config) all count as structural → the next --incremental run does a real (cache-accelerated) pipeline run. Pure content edits count as cosmetic → --incremental becomes a 0-call no-op and status shows the edited dirs as pending until the next structural run. Enable the mode with --incremental or incremental = true in agentwiki.toml; without it, behavior is unchanged.

Two scope notes: per-domain cache-key narrowing applies to embedded mode only — in agentic mode every global agent can read the whole repo, so any file change busts their cache keys (fail-open on purpose). And a 0-call no-op is taken only while every doc the previous run wrote is still on disk and research.json hasn't been touched since — deleted or interrupted output falls back to a real run.

agentwiki doctor

Read-only environment check — run it before (or instead of debugging) a failed pipeline:

agentwiki doctor          # report only
agentwiki doctor --fix    # also remove a stale run.lock + leftover tempfiles

It reports: agent CLIs on PATH (with versions, and which ones the configured models require), running/orphaned agent processes, the .agentwiki/ state (run lock, quota usage, cache size, research.json, last call), and project/output writability. Exit code is 1 when any check fails, so it is usable in scripts.

agentwiki drift

Read-only drift check: compares the generated core_dependencies claims against a statically-extracted import graph (Rust / Python / JS-TS) and reports confirmed / structural / unverifiable / undocumented / reversed / phantom edges. No LLM calls, no writes to your tree except <internal>/drift.json.

agentwiki drift                      # report only, exit 0
agentwiki drift -v                   # also list info-level edges
agentwiki drift --json               # machine-readable report on stdout
agentwiki drift --strict             # exit 1 on NEW phantom/reversed
agentwiki drift --update-baseline    # record current findings, exit 0
agentwiki drift --baseline ci-baseline.json   # override baseline path
agentwiki drift --max-depth 2        # tighter transitive check
agentwiki drift -o docs              # docs dir, for the claims search below
agentwiki drift --export-claims claims.json   # commit-able claims copy

The coverage: line shows how many claims were actually checked against code (confirmed/phantom/reversed) versus skipped as structural/ unverifiable — it separates "docs match the code" from "couldn't check".

.agentwiki/ is gitignored, so CI needs the claims committed: the pipeline already writes <output>/agentwiki.claims.json next to the docs, so committing the doc tree is enough. drift looks for claims in this order: --claims → [drift].claims_path → <internal>/research.json → <output>/agentwiki.claims.json. --export-claims remains for keeping the file somewhere else. Relative --claims, --baseline, and --export-claims paths resolve against the project root (-p), not the working directory — so drift -p repo --claims repo/docs/c.json looks for repo/repo/docs/c.json.

Suggested CI rollout:

# 1. observe — learn the noise level, never fail
- run: agentwiki drift
  continue-on-error: true
# 2. locally: `agentwiki drift --update-baseline`, commit the baseline
#    (claims ride along with the committed docs)
# 3. gate — fail only on NEW phantom/reversed findings
- run: agentwiki drift --strict

Configuration

agentwiki.toml in the project (or ~/.config/agentwiki/config.toml for global defaults) — all keys optional:

target_language = "vi"        # en zh ja ko de fr ru vi
mode = "agentic"              # embedded | agentic
max_parallels = 4
incremental = true            # cosmetic diffs → 0-call no-op (see `status`)

[models]
efficient = "opencode"
powerful  = "opencode"

[limits]
daily_cap       = 300
call_timeout_s  = 600
retry_attempts  = 3

[scan]
git_tracked_only = true       # only files in `git ls-files`
include_hidden   = false
include_tests    = false
excluded_dirs    = ["target", "node_modules", "vendor", "dist", ...]
excluded_files   = ["*.lock", ".env", "Cargo.lock", ...]

# `agentwiki drift` — all keys optional, the interesting ones:
[drift]
claims_path    = "claims.json"       # default: <internal>/research.json, else <output>/agentwiki.claims.json
baseline_path  = ".drift-baseline.json"   # default: .agentwiki-drift-baseline.json
ignore_nodes   = ["src/generated"]   # never flag undocumented edges here
max_transitive_depth = 3             # hops for `confirmed transitive`

# Named profiles — `agentwiki <profile>` applies them:
[profiles.research]
skip_documentation = true

agentwiki and agentwiki default use OpenCode v2 with its configured model. Built-in profiles opencode, claude, codex, and devin select their respective CLI. Defining [profiles.<name>] overrides a built-in profile.

embedded vs agentic mode

	embedded (default)	agentic
Context	scanner embeds code + materials into the prompt	agent reads the repo itself with its own tools
Agent cwd	empty dir (.agentwiki/empty-cwd) — repo invisible	the project root
Prompt size	capped by limits.materials_char_cap (192 KB)	no cap — agent explores as needed
Speed/cost	predictable, faster	slower — agents spend turns reading files
Requirements	one supported CLI	a supported CLI with file tools enabled

Use embedded for routine runs — deterministic context, no wandering. Use agentic (--agentic or mode = "agentic") for large or tangled codebases where the embedded excerpts feel too shallow and the agent should chase references itself.

How it works

Preprocess → Research → Compose → Write → Verify

• Preprocess: deterministic walk (git-tracked filter, exclusions, importance scoring) — no LLM.
• Research: dir_summary fans out per directory, then typed agents (system context, domain modules, relationships, boundary, database, architecture, workflow, key-module) with lenient-JSON validation.
• Compose: LLM editors + deterministic renderers → the doc tree.
• Verify: file integrity + mermaid checks + summary report.

Design notes: docs/plans/ — active plans and the shipped design history.

Development

cargo build          # build
cargo test           # offline tests (MockBackend — no real CLI needed)
cargo clippy --all-targets
AGENTWIKI_E2E=1 cargo test --test e2e_real_cli   # real CLI calls

Contributing

See CONTRIBUTING.md. Bug reports and PRs welcome.

License

Licensed under either of Apache License 2.0 or MIT license at your option.

Portions ported from deepwiki-rs (MIT © Sopaco) — see NOTICE.