CodeAlmanac Writes Wikis From Agent Chats

CodeAlmanac is an open-source TypeScript project from Divit at Almanac (YC S26) that turns Claude Code and Codex conversations into a living markdown wiki inside your repo. It deals with the awkward gap between code and chat: decisions, invariants, failures, and cross-file flows often live in agent transcripts, then disappear. The useful takeaway, especially for mcp training, is to make agent memory boring before connecting an mcp server: local files, Git review, narrow read paths. A codebase wiki is a set of durable notes that explains why the code is shaped the way it is, not just what the code currently says.

Notice what the chat remembered

The Show HN pitch landed because it named a real waste pattern. Claude Code, Anthropic's coding agent, and Codex, OpenAI's coding agent, can spend a long session learning why a subsystem is brittle, which test is misleading, or why a migration must happen in two phases. Then the next session starts cold.

CodeAlmanac tries to harvest that residue. Its README describes a wiki for AI coding agents that captures “what the code can't say”: decisions, flows, invariants, and gotchas. That is the right category of memory. Not every line of chat deserves to survive.

A concrete example: an agent helps you fix a billing retry loop. The code shows the final exponential backoff. The chat may contain the reason: one payment provider returns a 200 with a delayed failure webhook, so retrying immediately can double-charge a customer. That note belongs near the codebase, not buried in a transcript.

The trap is treating chat extraction as documentation magic. Hacker News commenters pushed on this directly: can an AI reliably extract reusable knowledge without strong guidance? That skepticism is healthy. A wiki generated from conversations should be reviewed like a code change, not trusted like a design doc written by the person who owns the system.

For more background on the same source story, see CodeAlmanac Turns Agent Chats Into Wikis.

Keep the wiki local and reviewable

The strongest design choice is not the AI part. It is the storage model.

CodeAlmanac keeps the wiki as plain markdown in the repo, indexes it locally, and expects changes to be reviewed in Git. As of July 2026, the public repository listed Apache-2.0 licensing, mainly TypeScript code, and support for macOS with Claude Code or Codex. The README also says Python 3.12+ is required.

That local-first shape matters for agentic coding. A markdown page can be diffed. A bad note can be reverted. A useful invariant can be linked from a small CLAUDE.md note without turning repository memory into a giant dumping ground.

A good boundary looks like this:

# CLAUDE.md

Read `.codealmanac/` for background only.
Treat wiki entries as context, not authority.
When a wiki note conflicts with code, tests, or docs, ask before editing.

That is intentionally small. CLAUDE.md should carry durable rules and pointers. The wiki can hold the richer trail: why a service boundary exists, what broke before, and which paths are risky.

The trap is assuming “local” means “safe.” Local markdown can still capture secrets, customer names, internal URLs, or credentials copied into a chat. Before you let any background job summarize conversations, decide what must never be written down.

Respect the Mac-only edge

One Hacker News objection was simple: why macOS only?

The README gives a practical clue. CodeAlmanac installs three local macOS launchd jobs: one to sync recent Claude and Codex conversations every five hours, one to garden registered wikis every 24 hours, and one to update the CLI every 24 hours when safe. That explains a lot. The product is leaning on local workstation automation, not a cloud service.

That is a reasonable early constraint. It also means Linux-heavy shops, dev containers, and CI-first workflows should not assume the same ergonomics yet.

Try it where it matches the grain: a Mac laptop, an active repo, and real agent conversations. Do not force it into production documentation flows on day one. The value is seeing whether the harvested notes are useful after the original chat has faded.

Try it safely on one real repo

Use a small experiment, not a grand policy. The goal is to learn whether conversation-derived wiki pages help the next coding session move faster and make fewer wrong assumptions.

Prerequisites: use a macOS machine, a repository you can safely modify, Python 3.12+, and either Claude Code or Codex conversation history. Pick a repo with real architectural context, not a toy app.

Step 1: choose one boundary.

Pick a subsystem with recurring confusion, such as billing retries, auth middleware, background jobs, or feature flag cleanup. Avoid the whole monorepo. A focused wiki is easier to judge.

Step 2: install from the source README.

Use the current setup commands from the CodeAlmanac repository rather than copying stale install commands from an article. After setup, confirm the local jobs match your expectations before letting them run unattended.

Step 3: review the first wiki diff like code.

Look for three things: a true invariant, a decision that code does not explain, and a claim that needs deletion. If the first diff is mostly transcript summary, tighten the scope or stop the experiment.

Step 4: keep MCP read-only at first.

If you expose the wiki through MCP, make the first mcp server read-only. Model Context Protocol (MCP) is a standard way for AI clients to connect to external tools and context sources, but “can read context” should not quietly become “can rewrite project memory.”

A minimal project-level shape looks like this:

{
  "mcpServers": {
    "codebase-wiki-readonly": {
      "command": "python",
      "args": [
        "tools/mcp/wiki_readonly_server.py",
        "--root",
        ".codealmanac",
        "--readonly"
      ],
      "env": {}
    }
  }
}

Treat this as a permission note, not a claim that CodeAlmanac ships this exact server. The important part is the boundary: one local wiki root, no write tools, no broad filesystem access. This is also the cleanest mcp training exercise for developers learning MCP servers: expose one boring context source before connecting GitHub, Slack, databases, or ticketing systems.

Step 5: verify with a cold prompt.

Start a fresh agent session and ask it to explain the chosen subsystem before editing anything. A good result cites the wiki's durable facts and asks about uncertainty. A bad result sounds confident but cannot point to the file, note, or test that supports its claim.

Use it when the code has a memory gap

CodeAlmanac is a fit when the important knowledge is real, repeated, and absent from normal docs. It is less useful when the repo is small, the architecture is obvious, or your agents mostly make isolated edits.

The best first use is a repo where people already say, “We explained this to the agent last week.” That sentence is the smell. It means the knowledge exists, but the repo did not absorb it.

For a broader set of patterns around agentic coding, see the related training topic.

Try the smallest useful version

Pick one repo, one confusing subsystem, and one week of agent conversations. If the first reviewed wiki page helps a fresh agent avoid a real mistake, CodeAlmanac has earned a deeper look.

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.

Practical starter checklist

- [ ] Name the Claude Code artifact first: a hook boundary, an MCP permission note, a slash-command workflow, a Claude skill outline, a review checklist, or a concise CLAUDE.md note when repository memory is the topic.
- [ ] Write the review checklist before generation starts: scope, owner, tests, rollback.
- [ ] Keep the first step small enough that a reviewer can inspect the receipt without replaying the whole chat.

Common questions

• What should teams know about mcp server?

  Start by writing down one visible team rule for Claude Code, not a loose preference. That is the practical core of mcp server. That usually means a short repository convention, a review checklist, and one owner who can reject agent output when the evidence is missing.

• Which Claude Code artifact should teams standardize first?

  Standardize the smallest artifact that reviewers already touch: a hook checklist, MCP permission rule, slash-command workflow, skill outline, or concise CLAUDE.md note. The point is not documentation volume; it is a shared place where scope, allowed tools, expected tests, and rollback notes are visible before generated code reaches review.

• How do teams know the convention is working?

  The convention is working when reviewers can approve or reject agent output from the artifact and evidence alone. Track whether pull requests name the rule used, include the promised checks, and avoid replaying long sessions just to understand what changed.

Best ways to use this research

• Best for: Claude Code teams deciding which hook, skill, MCP boundary, slash-command workflow, review habit, or repository-memory convention to standardize next around “CodeAlmanac Writes Wikis From Agent Chats.”
• Best first artifact: turn the named fix into a hook checklist, skill note, MCP permission note, review receipt, or concise CLAUDE.md convention when repository memory is the real topic before the next automated run.
• Best comparison angle: compare the workflow against the current Claude Code handoff, hook behavior, and MCP scope; keep the path that leaves the shortest auditable trail.

Further reading

• codealmanac — source
• Model Context Protocol — specification
• OWASP — Top 10 for Large Language Model Applications
• developers.google.com: fundamentals creating helpful content

Where to go next

Start from the related training topic and make the first exercise prove scope, verification, and ownership in the PR body.