CodeAlmanac Turns Agent Chats Into Wikis

CodeAlmanac is an open-source project from Almanac that turns conversations with coding agents into a local Markdown wiki for a codebase. It deals with the awkward gap between what code shows and what agent chats explain: decisions, invariants, gotchas, and cross-file flows. The takeaway is simple: treat agent conversation history as raw material, not documentation, then make every useful note reviewable in Git. That idea also gives developers doing mcp training a concrete anchor: context is only safe when it has a boundary, a reader, and a review path.

Read the wiki as a receipt, not a memory palace

CodeAlmanac is a living Markdown wiki maintained from coding-agent conversations. As of July 2026, the GitHub repository is Apache-2.0 licensed, mainly TypeScript, and describes support for macOS with Codex, OpenAI’s coding agent, or Claude Code, Anthropic’s coding agent.

The interesting part is not that it writes docs. Plenty of tools write docs. The interesting part is where it looks for the missing facts.

Agent chats often contain the real story: why the auth middleware skips one route, why a migration is split into two steps, why a flaky test is not safe to delete yet. CodeAlmanac tries to pull that knowledge out of recent agent conversations, keep it as plain Markdown in the repo, index it locally, and let you review it in Git like a code change.

The project’s README describes three local macOS launchd jobs. Sync scans recent Codex and Claude conversations and queues useful knowledge for the right registered wiki. Garden looks for stale, duplicated, or poorly connected notes. Update checks for safe CLI updates.

That local-first design is why developers paid attention. The pitch is not another hosted knowledge base. It is closer to a repo-native memory layer that your agent can read before it changes code.

The trap is assuming a transcript has the same status as a design decision. It does not. A chat can contain a good discovery, a temporary guess, or a confident mistake. The review step is the product boundary that matters.

Notice the Karpathy-style bet

The phrase Karpathy-style codebase wiki points at a compact body of notes that helps an agent understand a repo before editing it. It is not meant to be a full documentation site. It is meant to capture the sharp edges code alone cannot explain.

In Cursor, Anysphere’s AI code editor, this maps neatly to artifacts many teams already use: repository rules, AGENTS.md boundaries, review checklists, and scoped notes that keep an agent from rediscovering the same invariant every week. CodeAlmanac is playing in that same space, but with a different source of truth: the conversations you already had.

A real example is a payments repo with a recurring refund bug. The code can show that refunds must be idempotent. The old agent chat may explain the scar tissue: Stripe webhooks can arrive after the internal refund state changes, so the handler must tolerate both orders. That is exactly the kind of note you want preserved.

The obvious objection is also fair: where is the evidence that an AI can extract reusable knowledge well enough? The public project signal does not prove token savings or better outputs. It shows a plausible workflow, not a benchmark.

So do not treat it like magic memory. Treat it like an assistant that drafts a changelog for your repo’s hidden history. A human still decides which notes become durable context.

Try it on one repo without trusting it blindly

The safest first test is a small repo with real agent history and low blast radius. Good candidates are internal tools, SDK examples, or a service where a few invariants matter more than a thousand files.

Prerequisites:

• A macOS machine, because CodeAlmanac’s current setup is macOS-focused.
• Python 3.12 or newer.
• A repo where you have used Codex or Claude Code enough to create useful conversations.
• Cursor rules or an AGENTS.md file so the generated wiki has a review boundary.
• A branch where wiki changes can be reviewed like code.

Step 1: install from the project README on a branch. Use CodeAlmanac’s documented setup path for the local agent you use. Keep the first run away from your default branch so the first wiki diff is easy to inspect.

Step 2: add a Cursor rule for wiki edits. This makes the agent treat generated notes as claims that need evidence, not as fresh law.

---
description: Review generated codebase wiki changes before agents use them
globs:
  - docs/almanac/**/*.md
alwaysApply: false
---

When editing CodeAlmanac wiki notes, check that every durable claim points to a file, test, command, issue, or observed behavior.

Mark uncertain history as needs verification instead of turning it into a rule.

Do not promote temporary debugging guesses into architecture guidance.

Step 3: make the first MCP boundary read-only. MCP, the Model Context Protocol, is an open protocol for connecting AI tools to external context and actions through small servers. An MCP server is a process that exposes a bounded set of resources or tools to the client.

For a first pass, connect a read-only wiki folder rather than a write-capable repo tool. This snippet shows the shape of a local MCP server configuration; the script should be your own small server that only reads from the wiki directory.

{
  "mcpServers": {
    "repo-wiki-readonly": {
      "command": "python",
      "args": ["scripts/mcp_readonly_wiki.py", "docs/almanac"]
    }
  }
}

This is the practical mcp training lesson hiding inside the CodeAlmanac story: start with context retrieval, not action. Let the agent read the almanac before you let it mutate tickets, files, or production systems.

Step 4: ask one question that used to require replaying chat. Try something concrete, such as: why does the billing worker retry after a successful external refund? Ask the agent to answer using both the wiki and the code, and to cite the files it checked.

Step 5: verify the wiki by deleting a bad note. The setup works when you can reject, edit, or remove a generated wiki entry without breaking the workflow. If the agent treats every note as unquestioned truth, the boundary is too weak.

This sits squarely inside the related training topic, but the move is small: one repo, one wiki diff, one reviewable context path. For a nearby local-agent experiment, see claw-coder Runs an Autonomous Local Agent.

Use it when the repo has hidden history

CodeAlmanac is a good fit when your repo has decisions that live in Slack threads, PR comments, agent chats, or one senior engineer’s memory. It is especially interesting for codebases where workflows cross services and the important rule is not visible in one file.

It is less compelling for tiny repos, greenfield prototypes, or libraries where the code is already the best explanation. If a generated wiki would mostly restate filenames and public APIs, skip it.

The macOS-only point matters. The current README describes local macOS launchd jobs, so Linux-first and Windows-heavy shops should treat the project as a pattern to study, not an immediately universal workflow.

There is also a production-workflow question. Could the same idea help with ops runbooks, support workflows, or research notes? Probably as a pattern. But CodeAlmanac’s public project is about codebase knowledge from coding-agent conversations, so do not overread it as a general business-memory system.

Here is the light fit check I would use before trying it:

Common questions

• Does CodeAlmanac prove better coding-agent output?

  No, not from the public signal alone. The project makes a credible product bet, but the repository description and discussion do not provide benchmark data for output quality or token savings. Measure it with one repeated task: same prompt, same repo, with and without the reviewed wiki.

• Why is CodeAlmanac macOS-only right now?

  The public README describes macOS support and local launchd jobs, so the limitation appears tied to its current local scheduling and tool integration path. That does not mean the core idea is Apple-specific. It means non-macOS users should wait, contribute portability work, or borrow the reviewable-wiki pattern.

• What is MCP doing in this workflow?

  MCP is the connection layer, not the wiki itself. A model context protocol mcp setup can expose selected wiki pages, issue data, docs, or repo metadata through bounded servers. The safest first server is read-only and narrow, because context mistakes are easier to recover from than write-capable tool mistakes.

• Is mcp training relevant if CodeAlmanac is not just an MCP project?

  Yes, because CodeAlmanac makes the context problem concrete. MCP servers are only useful when the material they expose is scoped, current, and reviewable. A local wiki generated from agent conversations is a good exercise in deciding what an agent may read before deciding what it may do.

• Should I replace AGENTS.md or Cursor rules with CodeAlmanac?

  No. Keep durable instructions in AGENTS.md, Cursor rules, or similar repo-scoped files, and use CodeAlmanac-style notes for discovered context. A rule should say what must happen. A wiki note should explain why that rule exists, where it came from, and what evidence supports it.

Best ways to use this research

• Best for: repos where agent conversations already contain architectural decisions, workflow gotchas, or failure history that never made it into docs.
• Best first artifact: a reviewed Markdown wiki diff plus a small Cursor rule that requires evidence for every durable claim.
• Best comparison angle: compare CodeAlmanac against manual AGENTS.md notes, not against a full documentation platform. The project is about preserving agent-discovered context.
• Best safety boundary: expose the wiki through a read-only path first, whether that is normal file context or an MCP server with no write tools.

Further reading

• codealmanac — source
• Model Context Protocol — specification
• OWASP — Top 10 for Large Language Model Applications
• Cursor rules documentation
• Cursor MCP documentation

Next step

Pick one repo where an agent has already learned something painful. Generate or draft three wiki notes, review them like code, and see whether the next agent can answer a real maintenance question without replaying the chat.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.