A living wiki for your codebase, maintained by AI coding agents.
CodeAlmanac gives AI agents the context code alone cannot hold: why a system is shaped the way it is, what broke before, which invariants matter, and how workflows cross files and services. The wiki is plain markdown in your repo, indexed locally, and reviewed in Git like any other code change.
Quickstart
curl -fsSL https://codealmanac.com/install.sh | sh # Choose one setup path: codealmanac setup # Interactive setup codealmanac setup --yes # Quick install; uses Codex as the AI runner codealmanac setup --yes --runner claude # Quick install; uses Claude as the AI runner cd your-repo codealmanac init # Makes your wiki, if you don't have one codealmanac search "getting started" # Shows matching wiki pages. codealmanac show getting-started # Opens one page in the terminal codealmanac serve # Shows the wiki in local web viewer.
Install
With the install script:
curl -fsSL https://codealmanac.com/install.sh | shor directly:
uv tool install codealmanac@latest
or:
python -m pip install codealmanac
From this checkout:
uv sync uv run codealmanac --help
Requires Python 3.12+.
Migrating From The npm CLI
The legacy codealmanac npm package is retired. PyPI is the only supported
distribution. If you used the npm CLI, your machine may still carry the old
global install plus the hooks and agent instructions it set up. Remove those
before installing from PyPI.
The easiest path is to hand this prompt to your coding agent:
Migrate this machine from the old codealmanac npm CLI to the new PyPI CLI.
1. Uninstall every old install of the CLI and its dependencies:
npm uninstall -g codealmanac
Also check bun, pnpm, and yarn global installs, and remove any stray
codealmanac, almanac, or alm binaries left on PATH.
2. Remove everything the old CLI installed into agent tooling:
- Delete codealmanac hooks from Claude Code settings
(~/.claude/settings.json and any project .claude/settings*.json).
- Remove codealmanac sections and @-imports from ~/.claude/CLAUDE.md and
any other agent instruction files.
3. Install the latest PyPI CLI:
curl -fsSL https://codealmanac.com/install.sh | sh
4. Run codealmanac setup --yes to reinstall agent instructions and automation.
5. Verify the migration:
which codealmanac points at the new install and codealmanac --help runs.
Leave repo-local almanac/ wiki trees alone - they are committed wiki content,
not part of the CLI install.
Setup
Install global agent instructions for the local tools you use:
# Interactive setup codealmanac setup # Quick install with recommended defaults; uses Codex as the AI runner codealmanac setup --yes # Quick install using Claude as the AI runner codealmanac setup --yes --runner claude
Setup installs local agent instructions plus the default local automation: sync, Garden, and daily package update. It does not connect to a hosted service.
If you don't have Codex or prefer Claude, use --runner claude.
--target only chooses which global agent instruction files to install; it does
not choose the AI runner:
codealmanac setup --yes --target codex codealmanac setup --yes --target claude
Other setup flags:
codealmanac setup --yes --sync-every 5h codealmanac setup --yes --sync-off codealmanac setup --yes --garden-off codealmanac setup --yes --no-auto-update
To uninstall CodeAlmanac-owned local artifacts:
codealmanac uninstall --yes
Daily Read Surface
Agents and humans use the same local read commands:
codealmanac search "checkout timeout"
codealmanac search --mentions src/checkout/
codealmanac show checkout-flow
codealmanac topics
codealmanac health
codealmanac validateUse --wiki <name> to read another registered local wiki. By default,
commands target the exact current directory when it is a registered repository
root.
Updating The Wiki
Lifecycle commands can ask a configured local agent harness to edit wiki pages.
They only allow source edits under almanac/.
codealmanac ingest README.md --using codex codealmanac ingest github:pr:123 --using claude codealmanac garden --using codex
ingest folds selected local material into the wiki. Inputs can include files,
directories, Git diffs, commit ranges, GitHub PRs or issues, URLs, and local
agent transcripts.
garden improves the existing wiki graph: stale pages, links, topics, weak
leads, duplicate pages, and unsupported claims.
No-op is valid. If the material adds no durable wiki knowledge, the harness should leave the wiki unchanged.
ingest and garden create queued runs and start a local worker. Use
codealmanac jobs and codealmanac jobs attach <run-id> to follow them.
Sync And Automation
sync scans local Claude and Codex transcript stores, finds conversations active
since the last completed sync, and queues ordinary local ingest runs.
codealmanac sync status --from codex codealmanac sync --from codex --using codex codealmanac automation install sync --every 5h codealmanac automation install update --every 24h codealmanac automation status
Scheduled automation launches local sync, garden, or update commands with
explicit unattended policy. It is local scheduler state, not cloud sync.
Scheduler logs live under ~/.codealmanac/logs/.
Jobs
Lifecycle runs are recorded under ~/.codealmanac/:
codealmanac jobs codealmanac jobs show <run-id> codealmanac jobs logs <run-id> codealmanac jobs attach <run-id> codealmanac jobs cancel <run-id>
Run logs include source-resolution facts, harness events, safety errors, and terminal status.
Providers
CodeAlmanac currently supports local Codex app-server and Claude Agent SDK harnesses.
codex login claude auth login codealmanac doctor
Read commands do not need provider credentials. Write-capable lifecycle commands need the selected harness to be available and authenticated.
What Gets Created By Init
With the default root:
your-repo/
|-- almanac/
| |-- README.md
| |-- topics.yaml
| |-- architecture/
| | |-- README.md
| | `-- indexer.md
| |-- decisions/
| | `-- local-first.md
| `-- guides/
| `-- setup.md
|-- src/
`-- ...
Markdown pages live directly under almanac/ in meaningful folders.
topics.yaml organizes pages across folders. README.md files act as landing
pages for their folder routes.
For auto-detection, a repository counts as a CodeAlmanac wiki when
almanac/topics.yaml and almanac/README.md exist.
Runtime State
Derived local state lives under ~/.codealmanac/:
~/.codealmanac/codealmanac.db
~/.codealmanac/repos/<repo-id>/index.db
The local database records repositories, runs, run events, worker locks, and
sync state. Per-repository runtime files contain derived indexes. They do not
belong in the committed almanac/ tree.
Configuration
User config lives at:
~/.codealmanac/config.toml
Project config lives at:
The first supported defaults are:
auto_commit = true [harness] default = "codex"
CLI flags still win over config.
auto_commit means lifecycle prompts may tell the selected agent to use normal
Git commands for wiki source changes. CodeAlmanac does not stage files, split
diffs, or commit internally.
codealmanac setup --no-auto-commit codealmanac config set auto_commit false codealmanac config set auto_commit true
Local Viewer
The viewer is read-only. It renders pages, search, topics, backlinks, and
file-reference navigation from local wiki data. By default it can switch across
available registered local wikis. Use codealmanac serve --wiki <name> to
narrow the viewer to one wiki.
Troubleshooting
harness codex failed with status failed: Error: spawn ... codex ENOENT
The Codex CLI on this machine is broken or missing: the @openai/codex
package is installed but its native binary is gone (a common result of an
interrupted install or a Node version switch under nvm/volta/fnm). Verify
with:
If that fails with the same spawn ... ENOENT, reinstall the Codex CLI:
npm install -g @openai/codex codex --version # confirm the binary runs codex login status # confirm you are still signed in
Reinstalling does not sign you out: codex keeps its login under ~/.codex,
outside the npm package.
Or switch CodeAlmanac to the Claude harness instead:
codealmanac config set harness.default claudeThe same applies to harness claude failed errors: check
claude --version, reinstall the Claude Code CLI if broken, or switch the
default harness. codealmanac doctor reports harness availability.
Current Contract
This rewrite is local-only for now.
- Public command:
codealmanac - Repo wiki root:
almanac/only - Alternate repo wiki roots: none
- User state root:
~/.codealmanac/ - Runtime: Python 3.12+
- Storage: local markdown plus derived state under
~/.codealmanac/ - No hosted login/connect/upload commands.
- No public SDK or MCP package.
- No compatibility aliases.
- No alternate wiki roots.
- No hidden cloud write path.
- No second wiki command name.
This is the Python/PyPI product surface. Hosted integration can be added later around the same repo-owned wiki artifact, but it is not part of this release surface.