Alpha-wiki
Agent memory that compounds — in plain markdown, in your repo.
A Claude Code and OpenAI Codex plugin that turns Andrej Karpathy's LLM-Wiki sketch into repo-native markdown memory. Agents read, write, and grow a typed, lint-enforced markdown knowledge base across sessions. No embeddings. No vector store. Deterministic drift checks. Just files your team can read, diff, and review.
Hook Repair And OpenCode
Version 0.8.1 repairs known stale Codex adapters without replacing custom hooks.
The adapter starts on system Python 3.9; deterministic tools keep their isolated
Python 3.12+ environment. Updating a global plugin does not update project hooks.
See project repair.
OpenCode v2 uses native skills and commands:
python3 scripts/install_opencode.py --upgrade --dry-run
python3 scripts/install_opencode.py --upgrade
The installer preserves modified user files and does not change OpenCode config,
models or permissions. See OpenCode adapter.
What Alpha-Wiki Is
Alpha-Wiki is repo-native markdown memory for AI agents, developers, and project teams. It keeps project context, architecture notes, decisions, contracts, risks, status, and lightweight graph links in files your team can read, diff, and review.
It is for teams that want a new Claude Code or Codex session to quickly answer: what is this project, what must not break, what is stale, and where are the gaps.
Release Status
Alpha-Wiki is published for real Claude Code and Codex use on active projects.
Current release program:
- Branch:
main
- Release version:
v0.8.1 (Codex Hook Repair And OpenCode Installation)
- Status: source-bound document maintenance and dependency-safe tools; not v1.0
- Workflows: 12 core + 4 optional AgentOps (orchestrate, backlog, handoff, release-check)
- Live docs: https://yura4gus.github.io/alpha-wiki-creator/
Verification (publication/install receipts are maintained in the roadmap):
- Source and install evidence: release execution
- Fresh install smoke:
PASS
- Release audit:
READY
- Test suite:
354 passed
- Hosted CI / Pages: separate checks; local package gates do not prove hosted deployment
- Claude runtime: current hook schema (
SessionStart, PreToolUse, PostToolUse, SessionEnd) with JSON stdin handling
- Codex runtime: one namespaced
$alpha-wiki:* plugin surface, AGENTS.md, and trusted project hooks
- Deterministic tools: invoked as modules (
python -m tools.*) so copied target-project tools import correctly
- Obsidian: open the generated
wiki/ folder as the vault; Obsidian runtime state is ignored by git
Version 0.8.0 retains the opt-in AgentOps v0.2 control layer for controlled
multi-track execution. It stores backlog items, session summaries, handoffs, and
project release evidence under wiki/agentops/; normal init does not enable it.
The skills use the smallest sufficient evidence and checks. Release
blockers cite an existing requirement and a concrete failure; optional Pages,
wiki, or unused-platform findings keep their scope. Signing is required only
when the project requires it. See shared rules.
Not included in beta: embeddings, RAG, semantic search, PDF/DOCX/web crawlers, SaaS UI, multi-user permissions, or automatic truth resolution.
After init/upgrade, use python3 .alpha-wiki/run.py -m tools.<module>.
First setup or a runtime manifest change requires uv; dependencies live in
.alpha-wiki/runtime/.venv, never the product environment. A prepared runtime
can work without uv. Product manifests and lockfiles stay unchanged.
The 0.7 worker provides reviewed document_worker plan/apply,
source-preserving compaction, recovery/no-op checks and strict read-only reports.
0.8 uses one AGENTS.md contract and a Claude import adapter. Existing user
instructions and schemas are preserved. No server or daemon is required.
See maintenance.
0.7.1 restores missing bundled hooks only when existing Claude/Codex project
routing references them. Existing hook files and settings are preserved;
dry-run and unchanged repeat upgrades write nothing. Updating the plugin does
not automatically upgrade runtime files in existing project repositories.
Version 0.8.0 combines GOV-004, folder navigation and graph fixes.
It adds one AGENTS.md contract, a Claude import adapter, config-backed schema
evolution, valid Mermaid links, ownership grouping and concise engineering
writing guidance. Existing user files are preserved. No new AgentOps code is
included. Updating a plugin does not automatically migrate existing projects;
review and run the explicit upgrade for each target. See the
migration steps;
existing user contracts require deliberate merging, not overwriting.
Pre-release verification: 354 tests pass in both the working source and clean
source archive; smoke PASS, package audit READY. Isolated native Claude/Codex
installs expose the same writing guidance. See the
0.8.0 local receipt.
Quick Start
Claude Code install:
claude plugins marketplace add yura4gus/alpha-wiki-creator
claude plugins install alpha-wiki
Codex adapter install:
git clone https://github.com/yura4gus/alpha-wiki-creator
cd alpha-wiki-creator
python3 scripts/install_codex.py --upgrade --remove-legacy --remove-standalone
First workflow:
install -> init -> doctor --refresh -> ingest one source
-> query -> status -> render html
Why Alpha-wiki
LLM agents forget. RAG hides what they remember. Embeddings drift silently and obscure why a retrieval landed. Plain markdown with [[wikilinks]] doesn't have these problems — but raw markdown alone is undisciplined: pages go stale, links rot, structure entropies.
Alpha-wiki gives the wiki a runtime contract — typed entities, required frontmatter, bidirectional links the lint enforces, automated hooks that load compressed context at session start and run lint at session end. The result: agent memory that can compound week-over-week with visible drift checks.
Use it for engineering projects (decisions, modules, contracts, ADRs), research (papers, claims, experiments), product (features, personas, flows), or as a personal knowledge base. Five domain presets plus four architectural overlays (clean / hexagonal / DDD / layered) ship out of the box, and the schema evolves through ingest — new entity types are proposed, not preempted.
What's different from Karpathy's LLM-Wiki
Karpathy's 2025 gist sketched the idea in ~80 lines: three layers (raw / wiki / CLAUDE.md), three operations (ingest / query / lint), two service files (index.md / log.md). It is a beautiful sketch. Alpha-wiki is a pragmatic repo-native extension.
| Karpathy's gist (sketch) | Alpha-wiki (runtime) |
|---|
| 3 untyped layers | Same 3 layers, made explicit as mutability contracts + 5 domain presets + 4 architectural overlays |
| 3 operations (ingest, query, lint) | 12 core workflows + 4 optional AgentOps workflows — orchestration stays outside the first-run path |
| No frontmatter rules | Required frontmatter per entity type, lint-blocked on violations |
| Manual cross-links | Bidirectional enforcement — every forward link gets a reverse, written automatically by the engine |
| No automation | Three-layer hooks — session-start loads context_brief.md, post-tool-use rebuilds the graph, session-end runs lint and appends a log entry, pre-commit blocks 🔴 errors, weekly CI review |
| Static index.md | Auto-generated graph layer — edges.jsonl, context_brief.md (≤8000 chars, loaded into every session for free), open_questions.md |
| Bring your own UI | Obsidian-first — the generated wiki/.obsidian/ config ships with semantic color groups (🔴 repos/services, 🟢 modules/domains, 🔵 features/flows, ⚫ docs, 🟠 contracts) so the graph view reads like a system diagram |
| One-shot setup | Schema evolution — /alpha-wiki:evolve adds new entity types through ingest, gates them by default, logs every schema change |
| You write the subagents | Subagent slot — /alpha-wiki:spawn-agent generates wiki-aware Claude Code subagents that honor the mutability matrix |
In one line: Karpathy gave the idea, Alpha-wiki gives a small deterministic runtime around it.
Install
Claude Code
claude plugins marketplace add yura4gus/alpha-wiki-creator
claude plugins install alpha-wiki
Requires Python 3.12+ and uv (pipx install uv if missing).
Then in any project:
/alpha-wiki:init
/alpha-wiki:doctor --platform both --refresh
Updating
The marketplace source tracks main, so refresh the marketplace clone and reinstall to pull the latest release:
claude plugin marketplace update alpha
claude plugin uninstall alpha-wiki@alpha
claude plugin install alpha-wiki@alpha
Restart Claude Code, then verify the fresh version is active:
claude plugin list # alpha-wiki -> current version
ls ~/.claude/plugins/cache/alpha/alpha-wiki/*/skills/ # init, ingest, lint, query, render, evolve, status, spawn-agent, doctor, review, rollup
Why uninstall + install instead of update: a plain claude plugin update compares version strings. If a release forgets to bump version, the updater treats the cached build as current and serves a stale copy. The reinstall path forces a fresh clone of main. Every release must bump the version (see the release checklist in docs/docs-publishing.md) so plain update stays reliable.
Codex CLI (OpenAI)
Install and sign in to Codex, then install the Alpha-Wiki plugin:
npm install -g @openai/codex@latest
codex --login
git clone https://github.com/yura4gus/alpha-wiki-creator
cd alpha-wiki-creator
python3 scripts/install_codex.py --upgrade --remove-legacy --remove-standalone
Then in any project:
codex
Ask Codex to use $alpha-wiki:init to bootstrap the wiki. Plugin skills are namespaced ($alpha-wiki:query, $alpha-wiki:lint, $alpha-wiki:status, etc.). Claude slash commands stay unchanged.
The installer uses plugin-only mode by default so the Skills menu contains one set of 16 Alpha-Wiki workflows: 12 core and 4 optional AgentOps workflows. On a Codex surface that cannot load plugins, explicitly install the compatibility fallback with python3 scripts/install_codex.py --standalone; this mode skips plugin installation.
After init, use /hooks in Codex to review and trust the generated project hooks. Start a new Codex task after install or upgrade so the skill/plugin inventory refreshes.
Codex native subagents are supported without adding another Alpha-Wiki command.
$alpha-wiki:spawn-agent can create a reusable profile, run one bounded helper,
or run independent scopes in parallel. The controller pins one repository/SHA
snapshot and the generated SubagentStart hook gives every helper the wiki
contract and compact context.
Codex update command:
git pull --ff-only
npm install -g @openai/codex@latest
python3 scripts/install_codex.py --upgrade --remove-legacy --remove-standalone
Architecture
┌────────────────────────────────────────────────────────────────┐
│ Target Project │
│ │
│ ┌──────────┐ ┌─────────────────┐ ┌────────────────┐ │
│ │ raw/ │ ──> │ wiki/ │ <── │ CLAUDE/AGENTS │ │
│ │ (L1) │ │ (L2 + L3) │ │ (L4 schema) │ │
│ │ sources │ │ pages + graph/ │ │ contract │ │
│ │ read- │ │ LLM-mutable │ │ for the agent │ │
│ │ only │ │ + auto-derived │ │ │ │
│ └──────────┘ └─────────────────┘ └────────────────┘ │
│ ▲ ▲ ▲ │
│ │ │ │ │
│ │ ingest │ query/lint │ evolve │
│ │ │ │ │
│ ┌─────┴──────────────────┴───────────────────────┴───────┐ │
│ │ .claude/hooks/ + .codex/hooks/ + git + CI │ │
│ │ session-start: load context_brief.md │ │
│ │ pre/post-tool-use: validate + rebuild graph │ │
│ │ session-end: lint + log + summary │ │
│ └──────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
▲
│
┌─────────┴──────────┐
│ wiki plugin │
│ /alpha-wiki:init │
│ /alpha-wiki:doctor │
│ /alpha-wiki:ingest │
│ /alpha-wiki:query │
│ /alpha-wiki:lint │
│ /alpha-wiki:evolve │
│ /alpha-wiki:status │
│ /alpha-wiki:spawn-agent │
│ /alpha-wiki:render │
│ /alpha-wiki:review │
│ /alpha-wiki:rollup │
│ + optional AgentOps (4) │
└────────────────────┘
Features
- Three-layer mutability — raw (read-only), wiki (LLM-mutable), schema (gated)
- 5 domain presets — software-project (default), research, product, personal, knowledge-base, custom
- 4 architectural overlays — clean, hexagonal, ddd (combinable), layered
- Typed cross-references — bidirectional enforcement, lint flags missing reverses
- Schema evolution — new entity types added through ingest, never preempted
- Auto-generated context —
wiki/graph/context_brief.md (≤8000 chars) loaded at every session start
- Obsidian-compatible —
wiki/.obsidian/ config generated, so opening the wiki/ folder as a vault works out of the box
- Claude hook runtime — official hook event names, JSON stdin parsing, wiki-path filtering, and graph rebuild after wiki writes
- Codex runtime — one plugin skill surface,
AGENTS.md, trusted project hooks, and an explicit standalone compatibility mode
- Codex native subagents — bounded run-now/run-parallel workflows, reusable project profiles, pinned evidence snapshots, and
SubagentStart context
- Deterministic engine —
tools.doctor, tools.lint, and tools.wiki_engine are pure Python modules, no LLM, fully tested
- Schema-evolution gate — every new entity type confirmed before added (or auto-mode if you trust)
- CI-ready — deterministic GitHub Actions run
tools.lint, tools.review, and tools.rollup without Claude secrets
Workflow
Shortest first-run path:
install -> /alpha-wiki:init -> /alpha-wiki:doctor --refresh
-> /alpha-wiki:ingest raw/docs/project-brief.md
-> /alpha-wiki:query "what is this project building?"
-> /alpha-wiki:status
-> /alpha-wiki:render html
Full command surface:
1. /alpha-wiki:init Audit corpus → plan raw/wiki migration → bootstrap
2. /alpha-wiki:doctor Verify install/runtime/wiki health
3. /alpha-wiki:ingest <path> Raw artifact (PRD, ADR, OpenAPI spec, …) → wiki page(s)
4. /alpha-wiki:query <q> Ask/find in the wiki with cited evidence
5. /alpha-wiki:lint --fix Check/fix structure (links, reverses, frontmatter)
6. /alpha-wiki:status Health + mandatory Gap Check
7. /alpha-wiki:evolve <type> Add a new entity type to the schema
8. /alpha-wiki:spawn-agent Add a wiki-aware subagent
9. /alpha-wiki:render Refresh Obsidian config or generate static HTML
10. /alpha-wiki:review Weekly structural review — status + lint + next actions
11. /alpha-wiki:rollup Weekly/monthly activity summary
12. /alpha-wiki:audit-project Read-only delivery-readiness audit (git/docs/tests/deploy/security/providers/tech-debt)
13. /alpha-wiki:orchestrate Plan and control an optional multi-track execution wave
14. /alpha-wiki:backlog Manage one-file-per-task AgentOps backlog state
15. /alpha-wiki:handoff Transfer concise evidence between agent roles
16. /alpha-wiki:release-check Check target-project readiness from execution evidence
Commands 13-16 are optional. Enable them only for substantial coordinated work;
they do not change the normal install, init, ingest, query, status, or render path.
The session-start hook auto-loads context_brief.md so the agent has compressed context for free.
The session-end hook runs lint and appends a log entry. Most users never invoke /alpha-wiki:lint manually.
On existing projects, init first audits the repo: it enumerates current durable documents, proposes which ones belong in raw/ or a source manifest, proposes target wiki slots, and creates a batch plan so the first wiki pages are small, linked, and reviewable.
Daily agent start
Make Alpha-Wiki the first context source every session, before Claude or Codex starts writing code:
/alpha-wiki:status # where the project stopped, stale pages, blockers, gaps
/alpha-wiki:doctor --refresh # only when hooks/CI/setup feel broken or after an update
/alpha-wiki:query "<what you need>" # canons, architecture, contracts, APIs, enums, known gotchas, prior decisions
Query the wiki before coding so the agent inherits project canons, ownership boundaries, review rules, and test gates instead of re-deriving them. Run /alpha-wiki:review before any larger change, and /alpha-wiki:rollup when you want a retrospective or a compact record of recent progress.
A new agent entering the project should be able to answer these before writing a line of code:
- What is the active scope? (from
raw/docs/source-manifest.md)
- What is out of scope / deferred? — do not start work there.
- What are the canons? — architecture principles, standards, SOLID/Clean/Hexagonal/DDD rules.
- What is frozen? — money/custody/auth flows and other safety-gated areas (
wiki/security/).
- What must be checked before coding? — release gates, test gates, known blockers, security blockers.
- What is the next safe action? — from
/alpha-wiki:status and open questions.
If any of these is unanswerable, the wiki has a gap — capture it before coding, not after.
Recommended lifecycle
# once per project
/alpha-wiki:init # bootstrap + corpus audit
/alpha-wiki:ingest raw/docs/*.md # ADRs, specs, PRDs, standards, notes
/alpha-wiki:status · /alpha-wiki:doctor # confirm health
# every working session
/alpha-wiki:query "..." # retrieve canon before coding
... do the work ...
/alpha-wiki:review # before larger changes
/alpha-wiki:ingest raw/handoff-YYYY-MM-DD.md # persist handoff / retro / release notes
/alpha-wiki:rollup # summarize progress
The point is durable operational memory: what was decided, what was already checked, where development stopped, and what the next safe action is — all surfaced on demand instead of lost between sessions.
Skills
| Slash command | Purpose |
|---|
/alpha-wiki:init | Bootstrap wiki + scaffolding into the current project |
/alpha-wiki:doctor | Verify Python/tools/wiki graph/hooks/CI/Codex/Claude runtime health |
/alpha-wiki:ingest | raw → wiki page(s); triggers schema-evolve if no slot fits |
/alpha-wiki:query | Ask/find in the wiki; synthesize from index + relevant cited pages |
/alpha-wiki:lint | Check/fix wiki structure: links, reverses, orphans, frontmatter, dependency rules |
/alpha-wiki:status | Health + Gap Check — recent activity, stale pages, structural blind spots, schema-evolution log |
/alpha-wiki:evolve | Add a new entity type to the schema |
/alpha-wiki:spawn-agent | Generate a wiki-aware subagent |
/alpha-wiki:render | Refresh Obsidian config or render static HTML |
/alpha-wiki:review | Wiki-level structural review — status snapshot, lint findings, next actions |
/alpha-wiki:rollup | Weekly/monthly wiki activity rollup |
/alpha-wiki:audit-project | Read-only delivery-readiness audit — git/docs/tests/deploy/security/providers/tech-debt → structured status report |
/alpha-wiki:orchestrate | Opt-in controller for goals, tracks, native agents, sessions, and synthesis |
/alpha-wiki:backlog | Create, filter, update, and validate the optional Markdown backlog |
/alpha-wiki:handoff | Store a concise role-to-role transfer without raw logs |
/alpha-wiki:release-check | Evaluate target-project readiness as GREEN, WARNING, or BLOCKED |
Reading the Obsidian graph
The bootstrap ships a default wiki/.obsidian/graph.json with color groups so the graph view tells a story at a glance. Open the generated wiki/ directory itself as the Obsidian vault; do not open the repository root.
| Color | Meaning |
|---|
| 🔴 Red | Repo / service / top-level architectural unit (services/, repos/, bounded-contexts/, applications/) |
| 🟢 Green | Module / domain / sub-component within a service (modules/, components/, core/, ports/, domains/, adapters/) |
| 🔵 Blue | Feature / function / user-facing flow (features/, flows/, use-cases/, application/) |
| ⚫ Black | Document/evidence page — decisions, specs, concepts, APIs, papers, claims, summaries, etc. |
| 🟠 Orange | Contract — REST/GraphQL/gRPC/events at service boundaries (contracts/) |
| ⚪ Light grey | People / tasks — meta layer |
A red node is a repo/service boundary. A green cluster around red is the service's modules/domains/components. A blue node shows a feature or function implemented by those modules. Black nodes are documents/evidence attached to the architecture. An orange node bridging two reds is a contract owned by one service and consumed by another. Isolated red or black nodes are maintenance gaps.
Color is not a clustering mechanism. Clusters should emerge from typed links and shared architecture boundaries; colors only label the kind of node you are looking at.
Customize: edit wiki/.obsidian/graph.json → colorGroups array. Full legend at wiki/.obsidian/COLOR-LEGEND.md after bootstrap.
Obsidian may rewrite wiki/.obsidian/graph.json, workspace.json, app.json, appearance.json, and core-plugins.json during normal use. Alpha-Wiki treats those as local runtime state and ignores them in git; the portable defaults live under assets/obsidian/.
Documentation
Current architecture set:
Decision records:
Archived design materials:
References:
Development
git clone https://github.com/yura4gus/alpha-wiki-creator
cd alpha-wiki-creator
uv sync --dev
.venv/bin/python -m pytest
Without uv, use Python 3.12+ and install the declared dev extra:
python3.12 -m venv .venv
.venv/bin/python -m pip install -U pip
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest
Run the deterministic final-release gate:
.venv/bin/python -m tools.release_audit --root .
Current expected release-audit verdict: READY.
License
MIT
Created by RateXAI — https://ratex.ai
