CodeAlmanac

CodeAlmanac is a local codebase wiki maintained by AI coding agents.

It keeps durable project knowledge next to the code: decisions, workflows, invariants, incidents, gotchas, and context from real engineering sessions. The wiki is markdown in your repository, backed by a local SQLite index for fast search.

Current Status

This Python rewrite is usable as a local alpha. It is not the old Node CLI and it does not require a hosted service.

• 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/

Install

From a published package:

uv tool install codealmanac

or:

python -m pip install codealmanac

From this checkout:

uv sync
uv run codealmanac --help

Setup

Install global agent instructions for the local tools you use:

codealmanac setup --yes
codealmanac setup --yes --target codex
codealmanac setup --yes --target claude

Plain setup installs local agent instructions plus the default local automation: sync, Garden, and daily package update. It does not connect to a hosted service.

codealmanac setup --yes --sync-every 5h --sync-quiet 45m
codealmanac setup --yes --sync-off
codealmanac setup --yes --garden-off
codealmanac setup --yes --no-auto-update

During interactive onboarding, setup asks whether to keep CodeAlmanac up to date automatically. --yes chooses the default happy path and enables it.

To uninstall CodeAlmanac-owned local artifacts:

codealmanac uninstall --yes

Quickstart

Inside a repository:

codealmanac init
codealmanac search "getting"
codealmanac show getting-started
codealmanac serve

init creates a local wiki scaffold under almanac/. CodeAlmanac does not support alternate repo wiki roots.

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 validate

Use --wiki <name> to read another registered local wiki. By default, commands resolve the nearest repository wiki from the current directory.

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 ingest README.md --using codex --background
codealmanac garden --using codex
codealmanac garden --using codex --background

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.

Add --background to queue an ingest or garden run and start a detached local worker. Plain ingest and garden run in the foreground.

Sync And Automation

sync scans local Claude and Codex transcript stores, waits for quiet sessions, and runs ordinary local ingest for eligible transcript ranges.

codealmanac sync status --from codex
codealmanac sync --from codex --using codex
codealmanac sync --from codex --using codex --background
codealmanac automation install sync --every 5h --quiet 30m
codealmanac automation install update --every 24h
codealmanac automation status

Scheduled automation launches foreground sync, garden, or update commands with explicit unattended policy. It is local scheduler state, not cloud sync. Scheduler logs live under ~/.codealmanac/logs/. Use sync --background for manual queue-and-worker execution.

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/repos/<repo-id>/index.db
~/.codealmanac/repos/<repo-id>/runs/

Those runtime files are rebuildable local machine state. They do not belong in the committed almanac/ tree.

Configuration

User config lives at:

~/.codealmanac/config.toml

Project config lives at:

almanac/config.toml

The first supported defaults are:

auto_commit = true

[harness]
default = "codex"

[sync]
quiet = "30m"

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

codealmanac serve

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.

Public Contract

This rewrite is local-only for now.

• 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.

Hosted integration can be added later around the same repo-owned wiki artifact, but it is not part of this release surface.