code-wiki

code-wiki is a Codex / Claude Code / AI agent skill set for keeping repository-local wiki context in the loop before, during, and after software development work.

It is inspired by Andrej Karpathy's LLM Wiki idea: instead of making an LLM rediscover context from raw sources on every query, let the LLM maintain a persistent Markdown wiki that compounds over time.

This project applies that pattern to software repositories and AI coding agent workflows. A code-wiki is a durable development context layer that helps agents orient themselves, narrow code exploration, verify against the real source, and keep project knowledge current after changes.

Inspiration

Karpathy's LLM Wiki gist describes a general pattern for LLM-maintained personal knowledge bases: raw sources remain the source of truth, while an LLM keeps a structured wiki between those sources and future questions. New sources, questions, contradictions, cross-references, indexes, logs, and maintenance passes all make the wiki richer over time.

code-wiki adapts that idea for software development. The raw sources are source code, tests, configuration, commands, dependencies, and checked-in docs. The maintained wiki is repository-local Markdown. The operating rules are encoded as Codex / Claude Code / AI agent skills, so agents default to reading the right wiki context before work and updating it when durable project knowledge changes.

This project is inspired by the LLM Wiki pattern; it is not an official, endorsed, or affiliated Karpathy project.

How this adapts the LLM Wiki pattern

Karpathy's LLM Wiki pattern	This project
Raw sources	Source code, tests, config, docs, commands, dependencies, and runtime evidence
LLM-maintained wiki	Repository-local Markdown files, usually under wiki/
Schema	code-wiki skills plus project conventions and repo-local instructions
Ingest	Creating or updating wiki pages from codebase context
Query	Reading minimal relevant wiki context before answering or editing
Lint	Auditing the wiki for stale, vague, unsupported, or inconsistent claims
Index and log	wiki/index.md, wiki/modules/index.md, and wiki/log.md
Compounding knowledge	Keeping project context current across agent sessions and code changes

Problem

AI agents often reread large parts of a repository because durable project context is scattered across source files, tests, configuration, docs, and previous investigations. A useful wiki should preserve the development map: structure, domains, entry points, commands, data flow, dependencies, gotchas, and verification paths.

This package does not promise to replace source-code verification. It gives agents a consistent way to create, read, update, and audit a wiki so they can narrow their source inspection.

Core Purpose

A code-wiki is not a marketing overview, a broad summary, or a one-time documentation dump. It is an operational map for development agents:

• It prevents agents from rereading the whole repository from scratch for every task.
• It keeps project knowledge from disappearing into chat history.
• It narrows source-code inspection to the files, commands, modules, and risks most likely to matter.
• It keeps documentation current after code, configuration, tests, commands, architecture, dependencies, or module responsibilities change.
• It preserves the rule that source code is the source of truth. If wiki context conflicts with code, trust the code and update the wiki.
• It records what exists in the project, which domains own which behavior, where source verification is still required, and how changes should be tested.

What this is not

code-wiki is not a replacement for reading code.

It is not a vector database, a generic RAG system, or a complete documentation generator. It is a skill-driven workflow that helps AI agents maintain and use a persistent repository wiki while working on software projects.

Installation

Codex Plugin

The preferred Codex distribution path is the installable code-wiki Codex plugin. The plugin manifest lives at .codex-plugin/plugin.json and exposes the existing skills/ directory as the plugin's skill payload.

When code-wiki is published through a Codex plugin marketplace, install it through the Codex plugin UI or CLI for that marketplace. For local marketplace maintenance, use:

./scripts/sync-to-codex-plugin.sh -n --repo owner/name --dest plugins/code-wiki

The sync script copies only the plugin payload into the destination plugin repository: .codex-plugin/, skills/, public docs, examples, license, changelog, code of conduct, and contributing guide. It intentionally leaves local test and development infrastructure out of the embedded plugin.

Manual Skills

Copy or symlink the skill directories you want into your agent's skill directory. Install using-code-wiki as the bootstrap skill for project-related conversations, then install the sub-skills it routes to.

For Codex-style local skills:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ln -s /path/to/code-wiki/skills/using-code-wiki "${CODEX_HOME:-$HOME/.codex}/skills/using-code-wiki"
ln -s /path/to/code-wiki/skills/creating-code-wiki "${CODEX_HOME:-$HOME/.codex}/skills/creating-code-wiki"
ln -s /path/to/code-wiki/skills/reading-code-wiki "${CODEX_HOME:-$HOME/.codex}/skills/reading-code-wiki"
ln -s /path/to/code-wiki/skills/exploring-code-with-wiki "${CODEX_HOME:-$HOME/.codex}/skills/exploring-code-with-wiki"
ln -s /path/to/code-wiki/skills/updating-code-wiki "${CODEX_HOME:-$HOME/.codex}/skills/updating-code-wiki"
ln -s /path/to/code-wiki/skills/auditing-code-wiki "${CODEX_HOME:-$HOME/.codex}/skills/auditing-code-wiki"
ln -s /path/to/code-wiki/skills/writing-code-wiki-skills "${CODEX_HOME:-$HOME/.codex}/skills/writing-code-wiki-skills"

Install individual skills/* directories. The repository root is not a skill.

Default Workflow

Once installed, code-wiki is intended to be part of every project-related conversation.

The agent should:

1. Check whether the repository has an existing code-wiki.
2. Read the minimal relevant wiki context.
3. Use the wiki to guide targeted source-code inspection.
4. Perform the requested task.
5. Check whether the task changed anything the wiki should know.
6. Update the wiki when needed.
7. Record stale or missing wiki context when discovered.

Users do not need to explicitly say "use code-wiki" for normal project work.

This is the software-development version of a compounding wiki: each useful orientation, code investigation, fix, command change, architectural shift, or stale-wiki discovery can make future agent sessions cheaper and more accurate.

Basic Workflow

1. Use creating-code-wiki to initialize a wiki in a repository.
2. Let using-code-wiki run at the start of project-related work.
3. Use reading-code-wiki before development to identify relevant pages.
4. Use exploring-code-with-wiki to inspect the source paths the wiki points to.
5. Use updating-code-wiki after durable project changes.
6. Use auditing-code-wiki when quality, consistency, or staleness is in doubt.

Skills

Skill	When to use
using-code-wiki	Any project-related conversation starts in a code repository or workspace.
creating-code-wiki	A project needs a new or substantially regenerated repository wiki.
reading-code-wiki	An agent needs project orientation from an existing wiki before editing or answering.
exploring-code-with-wiki	Wiki context should narrow source-code inspection.
updating-code-wiki	Code, config, tests, commands, architecture, dependencies, or documented behavior changed.
auditing-code-wiki	A wiki needs quality review, consistency checks, stale-claim detection, or publication readiness review.
writing-code-wiki-skills	This skill set itself is being changed or extended.

Examples

See examples/basic-workflow.md for common project prompts and expected wiki-first behavior.

Applying To An Existing Project

Start by asking the agent to use creating-code-wiki in the target repository. After that, ordinary project tasks should trigger using-code-wiki automatically. The generated wiki should use stable common filenames such as overview.md, architecture.md, commands.md, testing.md, and modules/<domain-slug>.md. Project-specific pages are allowed, but the same purpose should keep the same filename across projects.

For an existing wiki, run auditing-code-wiki first if the structure is inconsistent or stale.

Contributing

Contributions should keep skills narrow and testable. Update tests/skill-set-contract.md and run:

python3 scripts/validate_wiki_contract.py
bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
python3 /home/kdg/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .

See CONTRIBUTING.md for details.

License

MIT. See LICENSE.