CodeAlmanac

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.

Supported today: macOS with Codex or Claude Code. Requires Python 3.12+.

Quickstart

See Setup for configuration options.

Setup

Once CodeAlmanac is set up:

Setup

Install global agent instructions for the local tools you use:

Setup installs agent instructions for your chosen tools and three local macOS

launchd jobs. The jobs and all wiki work run locally.

These schedules run locally in the background. Use

codealmanac automation status to see what is installed.

The final setup step asks about anonymous telemetry and recommends Yes so we can

see which commands work and where the CLI breaks. It sends controlled command

and lifecycle outcomes plus sanitized unhandled crashes under a random install

UUID. It never sends code, paths, arguments, queries, prompts, transcripts,

repository/run IDs, locals, or credentials; GeoIP is disabled. Choose No in

setup, pass setup --no-telemetry, set telemetry.enabled to false, or use

DO_NOT_TRACK=1 at any time. Without a future login, the UUID profile has no

name or email.

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:

Customize automatic work during setup:

To uninstall CodeAlmanac-owned local artifacts:

Daily Read Surface

Agents and humans use the same local read commands:

Use --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 run one of three explicit agents—build, ingest, or garden—

through the public Yoke SDK. The existing

packaged prompt files remain the complete task instructions and direct agents

to edit the wiki under almanac/.

Yoke SDK

Lifecycle agents are trusted local coding agents. They run with the same broad,

non-interactive filesystem permissions CodeAlmanac historically provided, so

the almanac/ boundary is an instruction and commit policy, not an OS sandbox.

Run lifecycle commands only in repositories where you accept that trust model,

and review the resulting Git diff when automatic commits are disabled.

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.

init, ingest, and garden create queued runs and start a local worker. To

follow them visually, run codealmanac serve and select Jobs in the

sidebar. To stay in the terminal, use codealmanac jobs attach <run-id>.

Sync And Automation

CodeAlmanac can keep registered wikis current without requiring you to remember

maintenance commands.

Sync scans local Codex and Claude transcript stores for conversations active

since the previous completed sync. Conversations associated with registered

repositories are queued as ordinary ingest jobs. Sync may decide that a

conversation contains no durable knowledge and leave the wiki unchanged.

Garden periodically queues a maintenance job for each registered wiki. It

improves stale pages, weak links, topics, duplicated knowledge, and graph

structure.

Update keeps the locally installed CodeAlmanac CLI current. Scheduled

updates are skipped when an update would be unsafe, such as while lifecycle

work is active.

Automation is implemented with local macOS launchd jobs, not a hosted service

or cloud sync. Logs are stored under ~/.codealmanac/logs/.

config set updates the user TOML and immediately makes launchd match. If you

edit the TOML directly, run codealmanac config apply afterward.

Automation creates individual background runs. Inspect those runs separately

with codealmanac jobs.

Jobs

Lifecycle runs are recorded under ~/.codealmanac/. Use these commands to

inspect and control them:

show is a summary of the job; logs is a snapshot of its event history;

attach keeps watching and prints events as they arrive. All of these commands

read the same durable local job record, so they still work after the terminal

that started the job has closed. Add --json when consuming their output from

a script.

Providers

CodeAlmanac uses almanac-yoke as its single provider boundary. Codex runs

through app-server; Claude uses Yoke's default Claude surface (currently the

Python Agent SDK). Existing Codex or Claude Code OAuth sessions are reused, and

API credentials can be supplied through Yoke when embedding the SDK.

Build, ingest, and garden are packaged as a Yoke agent collection under

src/codealmanac/agents/. Each agent uses Yoke's native folder contract:

agent.yaml describes tools and permissions, while instructions.md contains

the durable agent instructions. A lifecycle run passes only its typed runtime

context as the task prompt. Optional Yoke skills/, subagents/, and

workflows/ folders can be added to an agent when the product needs them;

native Claude or Codex execution still decides how and when to use them.

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:

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

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:

The supported defaults are:

CLI flags still win over config.

Use codealmanac config set <key> <value> for normal changes. It applies

automation changes to launchd immediately. Direct file edits are supported but

must be followed by:

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.

Local Viewer

The viewer is read-only. It renders pages, search, topics, backlinks, and

file-reference navigation from local wiki data. serve opens it in your default

browser once the server is ready; use codealmanac serve --no-open for headless

or scripted use. By default the viewer can switch across available registered

local wikis. Use codealmanac serve --wiki <name> to narrow it to one wiki.

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.

Remove the old global package and any CodeAlmanac hooks or agent-instruction

sections it installed, then install and set up the Python CLI:

Also remove old bun, pnpm, or yarn installs and any stray legacy binaries from

PATH. Leave repo-local almanac/ trees alone; they are committed wiki

content, not part of the CLI install.

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:

Reinstalling does not sign you out: codex keeps its login under ~/.codex,

outside the npm package.

Or switch CodeAlmanac to the Claude harness instead:

The 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

Short alias: ca

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 legacy compatibility aliases beyond the supported ca shorthand.

No alternate wiki roots.

Optional anonymous usage and sanitized crash telemetry; disable it with

codealmanac config set telemetry.enabled false or --no-telemetry in setup.

No wiki, source, prompt, transcript, path, or command-argument upload path.

No second canonical product 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.