Skip to content

nagarjun226/agentwiki-cc

BranchesTags

Repository files navigation

AgentWiki-CC

CI PyPI Python 3.11+ License: MIT

Persistent, compounding knowledge for Claude Code agents.

AgentWiki-CC gives Claude Code a wiki it maintains itself — pages are written by the agent, versioned in git, and injected into context at session start. Unlike CLAUDE.md (flat, manual) or RAG (re-derives knowledge every time), AgentWiki builds up structured knowledge that improves with every session.

Inspired by Andrej Karpathy's LLM OS wiki pattern.

Why AgentWiki?

Problem Without AgentWiki With AgentWiki
Session knowledge Lost on exit Persisted as wiki pages
Codebase understanding Re-derived every session Cumulative, improving
Repeated mistakes Happen again Captured as gotcha pages
Architecture decisions Buried in git log Surfaced as decision pages

Quick Start

# Install
pip install agentwiki-cc

# Initialize a wiki for your project (interactive — picks template, registers hooks)
cd /path/to/your/project
agentwiki init

# Start Claude Code — the wiki context injects automatically
claude

That's it. agentwiki init handles everything: directory setup, hook registration, and cron scheduling for background maintenance.

To check your installation health at any time:

agentwiki doctor

Installation

Requirements: Python 3.11+, Claude Code CLI (claude), macOS or Linux (uses POSIX file locking — Windows is not supported)

pip install agentwiki-cc

macOS note: macOS ships Python 3.13 as an externally-managed install that blocks pip. Use pyenv to manage a standalone Python 3.11:

pyenv install 3.11.0 && pyenv global 3.11.0
pip install agentwiki-cc

For development:

git clone https://github.com/nativeagents/agentwiki-cc
cd agentwiki-cc
pip install -e ".[dev]"
pytest tests/   # 354 tests passing

How It Works

AgentWiki has four layers:

Session Start/Stop
      │
      ▼
 Claude Code Hooks          ← deterministic, millisecond budget
 (SessionStart / SessionStop)
      │
      ▼
 Spool Directory            ← atomic job queue (rename → drain)
 ~/.agentwiki/spool/
      │
      ▼
 Background Worker          ← Claude Code headless, processes jobs
 (claude --print ...)
      │
      ▼
 Wiki Storage               ← SQLite + markdown pages + git history
 ~/.agentwiki/<wiki>/
  1. Session Start: The hook reads weights.json, selects high-scoring pages, injects them into context
  2. Session Stop: The hook spools a job to record what pages you accessed
  3. Background Worker: Drains the spool — writes/updates pages, runs lint, updates the behavioral graph
  4. Behavioral Graph: Tracks which pages co-occur in sessions; frequently co-accessed pages get recommended together

Templates

Two templates are available:

codebase-v1 (recommended for software projects)

Page types: overview, module, pattern, invariant, decision, gotcha, runbook

Best for: codebases, libraries, APIs — any project where you want the agent to track modules, patterns, and failure modes.

generic-v1 (general purpose)

Page types: overview, concept, how-to, reference, decision, gotcha

Best for: wikis, knowledge bases, research notes — anything that isn't a software codebase.

CLI Reference

All commands accept --help for detailed usage.

Setup

Command Description
agentwiki init Interactive setup: create a wiki, register hooks, configure cron
agentwiki hooks install Install session hooks into Claude Code settings.json
agentwiki hooks uninstall Remove hooks from settings.json
agentwiki doctor Check installation health (sqlite, git, hooks, weights freshness)
agentwiki status Show page counts, stale pages, and last activity for each wiki

Reading

Command Description
agentwiki list [--type TYPE] [--wiki WIKI] List pages, optionally filtered by type
agentwiki show <page-path> [--wiki WIKI] Display a page with frontmatter
agentwiki search <term> [--wiki WIKI] Full-text search (FTS5)
agentwiki query <question> [--wiki WIKI] Search ranked by behavioral graph weights
agentwiki context [--wiki WIKI] Preview what the session hook would inject
agentwiki log [--wiki WIKI] Show recent wiki activity log

Writing (agent use)

Command Description
agentwiki update <page-path> --stdin Write or update a page (reads content from stdin)
agentwiki update <page-path> --content-file <file> Write or update a page from a file
agentwiki link <from-page> <to-page> Add a backlink between two pages
agentwiki pin <page-path> Pin a page so it always appears in context injection
agentwiki unpin <page-path> Remove a page from always-on context injection

Page Management

Command Description
agentwiki delete <page-path> [--yes] Delete a page and remove from index
agentwiki rename <old-path> <new-path> Rename/move a page and update all backlinks
agentwiki lint [--wiki WIKI] Run quality checks (stale, missing title, coverage gaps, etc.)

Wiki Management

Command Description
agentwiki wiki list List all configured wikis
agentwiki wiki delete <name> [--yes] Delete a wiki and all its pages
agentwiki source add <wiki> --path <dir> Register a source directory to watch
agentwiki source list <wiki> List registered source directories
agentwiki source remove <wiki> --path <dir> Remove a source directory

Schema Customization

Command Description
agentwiki schema edit <wiki> Open WIKI.md in $EDITOR
agentwiki schema add-type <wiki> --name <type> Add a new page type template
agentwiki schema edit-prompt <wiki> --prompt <name> Edit a worker prompt in $EDITOR

Ingest

Command Description
agentwiki ingest [--wiki WIKI] Queue incremental source ingest
agentwiki ingest --full [--yes] Full re-ingest (wipes existing pages, asks for confirmation)

Behavioral Graph

Command Description
agentwiki graph stats [--wiki WIKI] Show node/edge/path counts and strongest paths
agentwiki graph show <page> [--wiki WIKI] Show weights and connections for a page
agentwiki graph decay [--wiki WIKI] Apply time-decay to all graph weights

Worker

Command Description
agentwiki worker status Show worker status, queue depth, last run time
agentwiki worker run Run worker manually in foreground
agentwiki worker log Show recent worker activity

Admin

Command Description
agentwiki git <args...> Run git commands against the internal ~/.agentwiki/ repo

Configuration

AgentWiki stores everything under ~/.agentwiki/:

~/.agentwiki/
├── config.yaml                   # Global config
├── wikis/
│   └── <wiki-name>/
│       ├── pages/                # Markdown pages
│       │   ├── overview.md
│       │   ├── modules/
│       │   └── decisions/
│       ├── WIKI.md               # Schema definition (page types, worker prompts)
│       ├── index.md              # Auto-maintained page catalog
│       └── log.md                # Append-only activity log
├── db/
│   └── access.db                 # SQLite: FTS5 index + behavioral graph
├── graph/
│   └── weights.json              # Context injection scores (updated by worker)
├── spool/                        # Job queue (agent → worker)
│   └── dead-letter/              # Failed jobs (inspect for errors)
└── worker/
    ├── worker.log                # Worker activity log (rotated at 5MB)
    └── worker.lock               # Prevents concurrent runs

~/.agentwiki/config.yaml (set by agentwiki init, edit manually if needed):

version: '0.1'
wikis:
  - name: myproject
    wiki_type: codebase
    template_version: codebase-v1
    enabled: true
    sources:
      - path: /path/to/project
half_life_days: 30          # Decay rate for access weights
token_budget: 500           # Max tokens injected per session
max_pages_in_context: 8     # Max pages listed in context block
cold_start_min_pages: 10    # Pages needed before weight-ranked mode activates
cold_start_min_events: 10   # Access events needed before weight-ranked mode activates
model: claude-haiku-4-5-20251001      # Background worker model (fast, cheap)
ingest_model: claude-sonnet-4-6-20250514  # Ingest/summarization model (smarter)

What You'll See

At session start, AgentWiki injects a context block like this into Claude Code:

━━━ AgentWiki: myproject ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Task hint: fix/auth-overhaul

★ HIGH   decisions/auth-approach.md                (weight: 0.92)
★ PIN    overview.md                               (weight: 0.10)
★ HIGH   modules/session-manager.md               (weight: 0.87)
  MED    patterns/retry-logic.md                  (weight: 0.54)
  MED    gotchas/token-refresh-race.md            (weight: 0.48)
⚠ STALE  modules/legacy-auth.md                  (weight: 0.31)
  LOW    runbooks/deploy-checklist.md             (weight: 0.19)
  LOW    concepts/jwt-validation.md               (weight: 0.12)

→ PATH  auth-approach → session-manager → token…  (weight: 0.76)

agentwiki show <page> · agentwiki query "<q>" · agentwiki list
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Labels explained:

  • ★ PIN — always shown (manually pinned with agentwiki pin)
  • ★ HIGH — composite weight ≥ 0.7 (frequently accessed + structurally linked)
  • MED — weight 0.4–0.7
  • LOW — weight < 0.4 (still surfaced if within budget)
  • ⚠ STALE — page has status: stale or source files changed since last review
  • → PATH — a repeated multi-page navigation sequence (myelinated path)

Task hint: the current git branch name, used to boost pages whose tags overlap with branch tokens (e.g. branch fix/auth-overhaul boosts pages tagged auth, session).

Cold-start mode (fewer than cold_start_min_pages pages or cold_start_min_events events): the block shows a directory listing instead of ranked pages, so you know the wiki is building — not broken:

━━━ AgentWiki: myproject (cold-start) ━━━━━━━━━━━━━━━━━━━━━━━
  3 pages indexed. Access pattern learning starts after a few sessions.
  [overview] overview.md
  [module] modules/auth.md · modules/session.md
agentwiki show <page> · agentwiki query "<q>" · agentwiki list
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

While initial ingest runs (zero pages yet):

━━━ AgentWiki: myproject (building) ━━━━━━━━━━━━━━━━━━━━━━━━━
  Initial ingest in progress. Wiki pages will appear after worker completes.
  Use: agentwiki status
agentwiki show <page> · agentwiki query "<q>" · agentwiki list
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Skills (Slash Commands)

AgentWiki installs seven Claude Code skills into ~/.claude/commands/ during agentwiki init. Use them directly inside any Claude Code session:

Skill Usage What it does
/wiki-query /wiki-query <question> FTS + graph-ranked search, synthesized answer
/wiki-show /wiki-show <page-path> Display a page with related-page hints
/wiki-list /wiki-list [--type <type>] Browse pages grouped by type
/wiki-search /wiki-search <term> Full-text search across all pages
/wiki-update /wiki-update <page-path> Write or update a page with session discoveries
/wiki-refine /wiki-refine [--wiki <name>] Review schema and propose improvements
/wiki-design /wiki-design <name> Interactively design a new wiki type

Skills are installed to ~/.claude/commands/wiki-*.md and become available as /wiki-* slash commands in Claude Code.

Behavioral Graph

AgentWiki tracks which wiki pages co-occur across sessions and builds a weighted graph:

  • Co-access edges: pages read in the same session
  • Sequential edges: pages read one after another
  • Paths: common multi-page navigation sequences

This powers two features:

  1. Context injection: pages that co-occur with recently accessed pages score higher
  2. Lint suggestions: the behavioral_link_suggestion rule flags page pairs with high co-access but no structural link

Weights decay with a configurable half-life (default 30 days) so stale knowledge fades naturally.

Troubleshooting

No pages are appearing in context

  1. Check that the worker has run: agentwiki worker status
  2. If the queue is non-empty, start the worker: agentwiki worker run
  3. Check weights.json exists: ls ~/.agentwiki/graph/weights.json
  4. Run agentwiki doctor to diagnose configuration issues

Hooks are not firing on session start/stop

  1. Verify hooks are installed: agentwiki doctor (look for "hooks" section)
  2. Check ~/.claude/settings.json for SessionStart and Stop entries
  3. If missing, reinstall: agentwiki hooks install
  4. Hooks must use absolute paths — ~ is not expanded by Claude Code

Worker not running / jobs stuck in queue

  1. Check the queue depth: agentwiki worker status
  2. Inspect the worker log: agentwiki worker log
  3. Check for dead-letter jobs: ls ~/.agentwiki/spool/dead-letter/
  4. Dead-letter files contain the raw job payload and error context
  5. Ensure claude CLI is installed and in PATH: which claude

agentwiki ingest runs but no pages appear

After ingest is queued, the background worker must process it. Run:

agentwiki worker run   # process the queue now
agentwiki list         # should show pages

If worker run produces no output, check that sources are configured:

agentwiki source list <wiki-name>

Pages are stale / not updating

Run an incremental scan to detect source changes and queue update jobs:

agentwiki ingest
agentwiki worker run

To force a full rebuild from scratch:

agentwiki ingest --full --yes
agentwiki worker run

Development

git clone https://github.com/nativeagents/agentwiki-cc
cd agentwiki-cc
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=agentwiki --cov-report=term-missing

# Test isolation: AGENTWIKI_DIR env var overrides ~/.agentwiki/
AGENTWIKI_DIR=/tmp/test-wiki pytest

See CONTRIBUTING.md for the full contribution guide.

Publishing a release

Releases are published automatically when a version tag is pushed. The GitHub Actions publish.yml workflow verifies the tag matches __version__, runs the full test suite, builds the wheel and sdist, and publishes via PyPI Trusted Publishing (no API token needed).

Setup (one-time, in GitHub):

  1. Go to PyPI → Account Settings → Add a new Pending Publisher
  2. Project: agentwiki-cc, GitHub owner: nativeagents, repo: agentwiki-cc, workflow: publish.yml
  3. In GitHub → Settings → Environments, create an environment named pypi

To release:

# Bump version in pyproject.toml and src/agentwiki/__init__.py
# Update CHANGELOG.md
git tag v0.1.1
git push origin v0.1.1

The publish workflow fires on tag push and handles the rest.

Architecture Notes

  • Worker: Uses claude --print --model <model> -p "<prompt>" (Claude Code headless mode), not raw API — no separate API key needed
  • Spool: Jobs are atomic file renames into spool/pending/; the worker processes them in order
  • FTS5: Regular SQLite FTS5 table (not contentless) — all columns stored for retrieval
  • Context hook: Runs in the Claude Code session hook budget; reads only weights.json (no SQLite)
  • Git: The pages/ directory is a git repo; the worker commits every page change automatically

License

MIT — see LICENSE.

Contributing

Contributions welcome! See CONTRIBUTING.md.

Changelog

See CHANGELOG.md.

About

Agent-maintained wiki system for Claude Code — knowledge that compounds across sessions

github.com/nagarjun226/agentwiki-cc

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages