AgentWiki

A self-maintaining wiki for your codebase.

Watch on Youtube 👉 VIDEO

npx @julianoczkowski/agentwiki init

One command, two Enter presses, complete wiki. No API keys, no configuration, no new subscription — built for prototyping repos where the "team" is a designer or PM, not a DevOps engineer.

What is it?

AgentWiki generates and maintains a documentation wiki (agentwiki/ in your repo) out of two kinds of content:

• Fact blocks — machine-owned. Generated deterministically from your code: files, exported symbols, import graphs (with a Mermaid diagram), manifests, and git history. Regenerated on every run, they can never hallucinate and never go stale silently.
• Prose sections — narrative explanations ("what is this module for", "what are we working on"). AgentWiki doesn't write these itself and never calls an LLM. Instead it hands them to the coding agent you already pay for — Cursor CLI or Claude Code, on your existing subscription.

How it works

flowchart TB
    subgraph repo["📦 Your repository"]
        code["Source code<br/>+ git history"]
        wiki["agentwiki/*.md<br/><b>fact blocks</b> — machine-owned<br/><b>prose slots</b> — agent-written"]
    end

    cli["<b>agentwiki CLI</b><br/>deterministic analysis<br/>no LLM · no API keys"]
    agent["<b>Your coding agent</b><br/>Cursor CLI or Claude Code<br/>on your existing subscription"]
    reader["👩‍💻 Developers & 🤖 AI agents<br/>read the wiki first"]

    code -- "scan · symbols · module graph · git facts" --> cli
    cli -- "writes fact blocks,<br/>flags stale prose" --> wiki
    wiki -- "queue of empty/stale slots<br/>(agentwiki enrich)" --> agent
    agent -- "writes prose between markers" --> wiki
    wiki --> reader

    subgraph auto["🔁 Hands-free automation"]
        hooks["Cursor rule + stop hook<br/>Claude Code stop hook<br/>→ agentwiki update after each session"]
        gha["GitHub Actions on every push<br/>→ refresh facts · commit back<br/>optional: prose in CI with one secret"]
    end

    hooks --> cli
    gha --> cli
    gha -. "CURSOR_API_KEY or<br/>CLAUDE_CODE_OAUTH_TOKEN" .-> agent

Loading

The loop: the CLI keeps the facts true on every change (locally via editor hooks, remotely via GitHub Actions), and whenever facts change under a prose section, that section is flagged stale and queued for your agent to rewrite — so the narrative can drift for at most one enrich cycle, and nothing is ever hallucinated into the fact tables.

The one-command experience

init walks you through everything interactively:

1. Monorepo? Pick what to document — when the repo contains multiple apps/packages, init asks what the wiki should cover: the folder you ran init from (pre-selected — just press Enter), the whole repository, or a typed path (validated as you confirm). No auto-detected app list to scroll through — you know your repo better than any heuristic. The choice is saved, and every later update (hooks, CI) honors it silently. Single-project repos never see this question. Change it any time with agentwiki init --scope <dir> (--scope . = whole repo).
2. Pick your prose writer — arrow-key select between Cursor CLI and Claude Code, with live readiness shown for each (installed? signed in?). If a tool is missing or logged out, you get numbered type-this-in-your-terminal steps, written for non-developers.
3. Watch the wiki generate — scan, git mining, symbol extraction, module graph, page generation, integration wiring, each with live progress.
4. "Write the Prose Now?" — if your agent is ready, press Enter and it writes every section in the same run, with a live spinner and elapsed time. A few minutes later: "all N slots written — wiki is fully fresh."

Most users never need a second command. Everything below is automation or power-user territory.

Agentwiki.mp4

What init creates

Output	Purpose
agentwiki/quickstart.md	Identity facts, run scripts, module map
agentwiki/architecture.md	Layout, entrypoints, Mermaid module-dependency graph
agentwiki/activity.md	Hot files, recent commits, contributors (90-day window)
agentwiki/modules/*.md	Per-module pages: files, exports, imports/imported-by, activity
.cursor/rules/agentwiki.mdc	Always-on rule: Cursor's agent reads the wiki first and fills any pending prose as a side effect of normal work
.cursor/hooks.json	stop hook: refresh facts after each Cursor agent session (runs via npx — no global install needed; your other hooks are preserved)
AGENTS.md + CLAUDE.md	Pointer sections for coding agents — both files always ensured, existing content never overwritten
.github/workflows/agentwiki.yml	CI automation (see below)

Monorepos

Point the wiki at one app instead of the whole repo. The recommended flow — cd into the app, run init, press Enter:

┌ What Should the Wiki Document?
│
│ This repository contains multiple apps/packages. AgentWiki can
│ document one folder in depth, or the whole repository at once.
│
● This folder: clients/apps/tcweb/ (where you ran init from)
○ The whole repository (one wiki covering everything at once)
○ Type a folder path… (e.g. clients/apps/my-app)

• You choose, explicitly: the folder you're standing in (pre-selected), the whole repository, or a typed path (validated against the repo). No auto-detected list to scroll — works identically for NX, pnpm, Turbo, Go, or any layout, because it doesn't guess.
• Everything is scoped: file scan, module graph, symbols, hot files, and recent commits cover only the chosen folder; commits elsewhere never touch your wiki's prose. Every page carries a banner stating what its paths are relative to.
• Everything anchors at the git repo root: the wiki, rules, hooks, and the GitHub workflow land in one canonical place no matter which subfolder you run commands from — exactly as in a single-project repo.
• Set it directly: agentwiki init --scope clients/apps/tcweb (CI-friendly), --scope . for whole-repo. Saved in agentwiki/.agentwiki.json — hooks and CI honor it with zero prompts.

How it stays current — the full lifecycle, hands-free

Verified end-to-end on a real repo:

You do	The automation does
Routine commit & push	CI refreshes volatile facts (git head, activity); prose stays fresh
Change a module's exports	Its facts table updates; its prose is flagged stale (never overwritten) and rewritten on the next enrich
Add a whole new module	CI creates its wiki page with fact tables and queued prose slots; it appears in the map and the dependency graph
Delete a module	CI deletes the orphaned page, cleans the map/graph, and flags any prose that still mentions it
Work in Cursor	The stop-hook refreshes facts; the rule has Cursor's agent fill pending prose as it goes

The key mechanic: prose freshness is a hash of the page's structural facts only. Volatile facts (commit hashes, hot files) are excluded, so ordinary commits don't churn your documentation — only real shape changes do. Only activity.md's current-focus section intentionally tracks every commit.

CI prose enrichment — turns itself on

The workflow's fact refresh needs zero secrets. Prose enrichment in CI is built in and self-enabling: add ONE repository secret and the next push starts writing and committing prose automatically — no YAML editing:

Secret	Where it comes from
CURSOR_API_KEY	cursor.com/dashboard → API Keys (same subscription)
CLAUDE_CODE_OAUTH_TOKEN	run claude setup-token locally (personal repos; teams should use ANTHROPIC_API_KEY)

Without a secret, the enrichment steps skip themselves with a clear message. Bot commits never re-trigger the workflow, so there are no loops.

Commands

agentwiki init                 The one command: generate, wire, offer prose
        --scope <dir>              monorepo: document one app (`.` = whole repo)
agentwiki update               Refresh fact blocks; flag prose whose facts changed
agentwiki status               Freshness overview per page/slot + backend readiness
agentwiki queue [--json]       List prose slots that need writing
agentwiki enrich               Have your coding agent write the queued slots now
        --backend cursor|claude    override the saved preference
        --dry-run                  print the prompt, run nothing
        --verbose                  stream the agent's raw output
agentwiki backend              Re-pick your prose writer interactively
agentwiki pause / resume       Pause automation reversibly (docs kept)
agentwiki remove [--docs] [-y] Remove integrations with confirmation; docs KEPT
                               unless --docs — the wiki stays useful as plain markdown
agentwiki setup-action         (Re)write the GitHub Actions workflow
agentwiki uninstall            Remove the CLI from this computer (projects untouched)
agentwiki doctor               Check node, git, backend install + auth state

The enrich report is deterministic: it lists exactly which files gained which sections, computed from what actually changed on disk — never from the agent's own claims. Failed runs auto-show the agent's last output lines; the CLI also recognizes environment noise (like zsh's "insecure directories" warning) and explains the one-time fix.

How pages stay honest

<!-- agentwiki:facts id="dependencies" hash="1992f504c371" -->
- **Imports from:** `src (root)` (4)      ← regenerated every run, never edited
<!-- /agentwiki:facts -->

<!-- agentwiki:facts id="git-state" hash="1992f504c371" volatile="true" -->
- **Git:** branch `main` at `abc1234`     ← refreshed, but never stales prose
<!-- /agentwiki:facts -->

<!-- agentwiki:prose slot="purpose" status="fresh" facts-hash="1992f504c371" -->
This module owns the agent session lifecycle…   ← written by YOUR agent
<!-- /agentwiki:prose -->

A prose slot is fresh while its recorded facts-hash matches the page's current structural facts. A content snapshot guarantees no-op runs leave metadata untouched — safe for hooks and scheduled CI. Markers are invisible when the markdown renders, so the wiki reads clean everywhere — even after remove.

Leaving is easy

pause detaches the automation reversibly. remove strips every integration surgically (foreign hooks and your other AGENTS.md/CLAUDE.md content survive) and keeps your docs unless you pass --docs. uninstall removes the command itself, in plain language a non-developer can follow, and never touches your projects. Nothing global is ever stored on your machine.

Development

git clone https://github.com/julianoczkowski/agentwiki
cd agentwiki
npm install
npm run dev -- doctor     # run from source (tsx)
npm test                  # vitest unit suite
npm run build             # tsc -> dist/, then npm link for a global command

Releases are automated via npm Trusted Publishers (OIDC): npm version patch && git push --follow-tags — no tokens anywhere. See CHANGELOG.md for release notes.

---

Author

Built by Julian Oczkowski — I build AI tools for knowledge work.

• 🎥 YouTube · @aiforwork_app — walkthroughs and AI-for-work tutorials
• ✍️ Medium — deep dives on product and AI workflows
• 💼 LinkedIn — connect and follow along

MIT © Julian Oczkowski · 📺 youtube.com/@aiforwork_app