{"slug": "show-hn-codealmanac-karpathy-style-codebase-wiki-from-your-conversations", "title": "Show HN: CodeAlmanac – Karpathy-style codebase wiki from your conversations", "summary": "CodeAlmanac, a new open-source tool that creates a Karpathy-style wiki for codebases from AI coding agent conversations, launched on Hacker News. The tool runs locally on macOS with Codex or Claude Code, requires Python 3.12+, and stores plain markdown in the repo for version control. It offers background jobs for syncing agent transcripts, gardening stale knowledge, and auto-updating, with telemetry that excludes code and prompts.", "body_md": "A living wiki for your codebase, maintained by AI coding agents.\n\nCodeAlmanac 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.\n\n**Supported today:** macOS with Codex or Claude Code. Requires Python 3.12+.\n\n```\nuv tool install codealmanac@latest\ncodealmanac setup\n```\n\nSee [Setup](#setup) for configuration options.\n\nOnce CodeAlmanac is set up:\n\n```\ncd your-repo\ncodealmanac init                     # Makes your wiki, if you don't have one\ncodealmanac search \"getting started\" # Shows matching wiki pages.\ncodealmanac show getting-started     # Opens one page in the terminal\ncodealmanac serve                    # Shows the wiki in local web viewer.\n```\n\nInstall global agent instructions for the local tools you use:\n\n```\n# Interactive setup\ncodealmanac setup\n\n# Quick install with recommended defaults; uses Codex as the AI runner\ncodealmanac setup --yes\n\n# Quick install using Claude as the AI runner\ncodealmanac setup --yes --runner claude\n```\n\nSetup installs agent instructions for your chosen tools and three local macOS\n`launchd`\n\njobs. The jobs and all wiki work run locally.\n\n| Job | Default schedule | What it does |\n|---|---|---|\n| Sync | Every 5 hours | Scans recent Codex and Claude conversations and queues useful knowledge for the relevant registered wiki. |\n| Garden | Every 24 hours | Reviews every registered wiki for stale, duplicated, or poorly connected knowledge. |\n| Update | Every 24 hours | Checks for and installs CodeAlmanac CLI updates when it is safe to do so. |\n\nThese schedules run locally in the background. Use\n`codealmanac automation status`\n\nto see what is installed.\n\nThe final setup step asks about anonymous telemetry and recommends Yes so we can\nsee which commands work and where the CLI breaks. It sends controlled command\nand lifecycle outcomes plus sanitized unhandled crashes under a random install\nUUID. It never sends code, paths, arguments, queries, prompts, transcripts,\nrepository/run IDs, locals, or credentials; GeoIP is disabled. Choose No in\nsetup, pass `setup --no-telemetry`\n\n, set `telemetry.enabled`\n\nto `false`\n\n, or use\n`DO_NOT_TRACK=1`\n\nat any time. Without a future login, the UUID profile has no\nname or email.\n\nIf you don't have Codex or prefer Claude, use `--runner claude`\n\n.\n\n`--target`\n\nonly chooses which global agent instruction files to install; it does\nnot choose the AI runner:\n\n```\ncodealmanac setup --yes --target codex\ncodealmanac setup --yes --target claude\n```\n\nCustomize automatic work during setup:\n\n```\n# Change how often recent agent conversations are scanned\ncodealmanac setup --yes --sync-every 5h\n\n# Do not install automatic transcript sync\ncodealmanac setup --yes --sync-off\n\n# Do not install automatic wiki cleanup\ncodealmanac setup --yes --garden-off\n\n# Do not install automatic CodeAlmanac updates\ncodealmanac setup --yes --no-auto-update\n```\n\nTo uninstall CodeAlmanac-owned local artifacts:\n\n```\ncodealmanac uninstall --yes\n```\n\nAgents and humans use the same local read commands:\n\n```\ncodealmanac search \"checkout timeout\"\ncodealmanac search --mentions src/checkout/\ncodealmanac show checkout-flow\ncodealmanac topics\ncodealmanac health\ncodealmanac validate\n```\n\nUse `--wiki <name>`\n\nto read another registered local wiki. By default,\ncommands target the exact current directory when it is a registered repository\nroot.\n\nLifecycle commands run one of three explicit agents—build, ingest, or garden—\nthrough the public [Yoke SDK](https://github.com/AlmanacCode/Yoke). The existing\npackaged prompt files remain the complete task instructions and direct agents\nto edit the wiki under `almanac/`\n\n.\n\nLifecycle agents are trusted local coding agents. They run with the same broad,\nnon-interactive filesystem permissions CodeAlmanac historically provided, so\nthe `almanac/`\n\nboundary is an instruction and commit policy, not an OS sandbox.\nRun lifecycle commands only in repositories where you accept that trust model,\nand review the resulting Git diff when automatic commits are disabled.\n\n```\ncodealmanac ingest README.md --using codex\ncodealmanac ingest github:pr:123 --using claude\ncodealmanac garden --using codex\n```\n\n`ingest`\n\nfolds selected local material into the wiki. Inputs can include files,\ndirectories, Git diffs, commit ranges, GitHub PRs or issues, URLs, and local\nagent transcripts.\n\n`garden`\n\nimproves the existing wiki graph: stale pages, links, topics, weak\nleads, duplicate pages, and unsupported claims.\n\nNo-op is valid. If the material adds no durable wiki knowledge, the harness should leave the wiki unchanged.\n\n`init`\n\n, `ingest`\n\n, and `garden`\n\ncreate queued runs and start a local worker. To\nfollow them visually, run `codealmanac serve`\n\nand select **Jobs** in the\nsidebar. To stay in the terminal, use `codealmanac jobs attach <run-id>`\n\n.\n\nCodeAlmanac can keep registered wikis current without requiring you to remember maintenance commands.\n\n**Sync** scans local Codex and Claude transcript stores for conversations active\nsince the previous completed sync. Conversations associated with registered\nrepositories are queued as ordinary ingest jobs. Sync may decide that a\nconversation contains no durable knowledge and leave the wiki unchanged.\n\n**Garden** periodically queues a maintenance job for each registered wiki. It\nimproves stale pages, weak links, topics, duplicated knowledge, and graph\nstructure.\n\n**Update** keeps the locally installed CodeAlmanac CLI current. Scheduled\nupdates are skipped when an update would be unsafe, such as while lifecycle\nwork is active.\n\nAutomation is implemented with local macOS `launchd`\n\njobs, not a hosted service\nor cloud sync. Logs are stored under `~/.codealmanac/logs/`\n\n.\n\n```\n# See installed schedules\ncodealmanac automation status\n\n# Change a schedule\ncodealmanac config set automation.sync.every 5h\ncodealmanac config set automation.garden.every 24h\ncodealmanac config set automation.update.every 24h\n\n# Disable or re-enable a schedule\ncodealmanac config set automation.sync.enabled false\ncodealmanac config set automation.sync.enabled true\n```\n\n`config set`\n\nupdates the user TOML and immediately makes launchd match. If you\nedit the TOML directly, run `codealmanac config apply`\n\nafterward.\n\nAutomation creates individual background runs. Inspect those runs separately\nwith `codealmanac jobs`\n\n.\n\nLifecycle runs are recorded under `~/.codealmanac/`\n\n. Use these commands to\ninspect and control them:\n\n```\n# List recent jobs with their IDs, kinds, statuses, and elapsed times\ncodealmanac jobs\n\n# Show one job's status, summary, page changes, timestamps, and error details\ncodealmanac jobs show <run-id>\n\n# Print the events recorded so far, including progress, tool activity, and errors\ncodealmanac jobs logs <run-id>\n\n# Follow new events live until the job finishes, fails, or is marked cancelled\ncodealmanac jobs attach <run-id>\n\n# Prevent a queued job from starting, or stop a running job and its agent\ncodealmanac jobs cancel <run-id>\n```\n\n`show`\n\nis a summary of the job; `logs`\n\nis a snapshot of its event history;\n`attach`\n\nkeeps watching and prints events as they arrive. All of these commands\nread the same durable local job record, so they still work after the terminal\nthat started the job has closed. Add `--json`\n\nwhen consuming their output from\na script.\n\nCodeAlmanac uses `almanac-yoke`\n\nas its single provider boundary. Codex runs\nthrough app-server; Claude uses Yoke's default Claude surface (currently the\nPython Agent SDK). Existing Codex or Claude Code OAuth sessions are reused, and\nAPI credentials can be supplied through Yoke when embedding the SDK.\n\nBuild, ingest, and garden are packaged as a Yoke agent collection under\n`src/codealmanac/agents/`\n\n. Each agent uses Yoke's native folder contract:\n`agent.yaml`\n\ndescribes tools and permissions, while `instructions.md`\n\ncontains\nthe durable agent instructions. A lifecycle run passes only its typed runtime\ncontext as the task prompt. Optional Yoke `skills/`\n\n, `subagents/`\n\n, and\n`workflows/`\n\nfolders can be added to an agent when the product needs them;\nnative Claude or Codex execution still decides how and when to use them.\n\n```\ncodex login\nclaude auth login\ncodealmanac doctor\n```\n\nRead commands do not need provider credentials. Write-capable lifecycle commands need the selected harness to be available and authenticated.\n\nWith the default root:\n\n```\nyour-repo/\n|-- almanac/\n|   |-- README.md\n|   |-- topics.yaml\n|   |-- architecture/\n|   |   |-- README.md\n|   |   `-- indexer.md\n|   |-- decisions/\n|   |   `-- local-first.md\n|   `-- guides/\n|       `-- setup.md\n|-- src/\n`-- ...\n```\n\nMarkdown pages live directly under `almanac/`\n\nin meaningful folders.\n`topics.yaml`\n\norganizes pages across folders. `README.md`\n\nfiles act as landing\npages for their folder routes.\n\nFor auto-detection, a repository counts as a CodeAlmanac wiki when\n`almanac/topics.yaml`\n\nand `almanac/README.md`\n\nexist.\n\nDerived local state lives under `~/.codealmanac/`\n\n:\n\n```\n~/.codealmanac/codealmanac.db\n~/.codealmanac/repos/<repo-id>/index.db\n```\n\nThe local database records repositories, runs, run events, worker locks, and\nsync state. Per-repository runtime files contain derived indexes. They do not\nbelong in the committed `almanac/`\n\ntree.\n\nUser config lives at:\n\n```\n~/.codealmanac/config.toml\n```\n\nThe supported defaults are:\n\n```\nauto_commit = true\n\n[harness]\ndefault = \"codex\"\nmodel = \"gpt-5.5\"\n\n[automation.sync]\nenabled = true\nevery = \"5h\"\n\n[automation.garden]\nenabled = true\nevery = \"24h\"\n\n[automation.update]\nenabled = true\nevery = \"24h\"\n```\n\nCLI flags still win over config.\n\nUse `codealmanac config set <key> <value>`\n\nfor normal changes. It applies\nautomation changes to launchd immediately. Direct file edits are supported but\nmust be followed by:\n\n```\ncodealmanac config apply\n```\n\n`auto_commit`\n\nmeans lifecycle prompts may tell the selected agent to use normal\nGit commands for wiki source changes. CodeAlmanac does not stage files, split\ndiffs, or commit internally.\n\n```\ncodealmanac setup --no-auto-commit\ncodealmanac config set auto_commit false\ncodealmanac config set auto_commit true\ncodealmanac serve\n```\n\nThe viewer is read-only. It renders pages, search, topics, backlinks, and\nfile-reference navigation from local wiki data. `serve`\n\nopens it in your default\nbrowser once the server is ready; use `codealmanac serve --no-open`\n\nfor headless\nor scripted use. By default the viewer can switch across available registered\nlocal wikis. Use `codealmanac serve --wiki <name>`\n\nto narrow it to one wiki.\n\nThe legacy `codealmanac`\n\nnpm package is retired. PyPI is the only supported\ndistribution. If you used the npm CLI, your machine may still carry the old\nglobal install plus the hooks and agent instructions it set up. Remove those\nbefore installing from PyPI.\n\nRemove the old global package and any CodeAlmanac hooks or agent-instruction sections it installed, then install and set up the Python CLI:\n\n```\nnpm uninstall -g codealmanac\nuv tool install codealmanac@latest\ncodealmanac setup --yes\ncodealmanac doctor\n```\n\nAlso remove old bun, pnpm, or yarn installs and any stray legacy binaries from\n`PATH`\n\n. Leave repo-local `almanac/`\n\ntrees alone; they are committed wiki\ncontent, not part of the CLI install.\n\nThe Codex CLI on this machine is broken or missing: the `@openai/codex`\n\npackage is installed but its native binary is gone (a common result of an\ninterrupted install or a Node version switch under nvm/volta/fnm). Verify\nwith:\n\n```\ncodex --version\n```\n\nIf that fails with the same `spawn ... ENOENT`\n\n, reinstall the Codex CLI:\n\n```\nnpm install -g @openai/codex\ncodex --version       # confirm the binary runs\ncodex login status    # confirm you are still signed in\n```\n\nReinstalling does not sign you out: codex keeps its login under `~/.codex`\n\n,\noutside the npm package.\n\nOr switch CodeAlmanac to the Claude harness instead:\n\n```\ncodealmanac config set harness.default claude\n```\n\nThe same applies to `harness claude failed`\n\nerrors: check\n`claude --version`\n\n, reinstall the Claude Code CLI if broken, or switch the\ndefault harness. `codealmanac doctor`\n\nreports harness availability.\n\nThis rewrite is local-only for now.\n\n- Public command:\n`codealmanac`\n\n- Short alias:\n`ca`\n\n- Repo wiki root:\n`almanac/`\n\nonly - Alternate repo wiki roots: none\n- User state root:\n`~/.codealmanac/`\n\n- Runtime: Python 3.12+\n- Storage: local markdown plus derived state under\n`~/.codealmanac/`\n\n- No hosted login/connect/upload commands.\n- No public SDK or MCP package.\n- No legacy compatibility aliases beyond the supported\n`ca`\n\nshorthand. - No alternate wiki roots.\n- Optional anonymous usage and sanitized crash telemetry; disable it with\n`codealmanac config set telemetry.enabled false`\n\nor`--no-telemetry`\n\nin setup. - No wiki, source, prompt, transcript, path, or command-argument upload path.\n- No second canonical product name.\n\nThis 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.", "url": "https://wpnews.pro/news/show-hn-codealmanac-karpathy-style-codebase-wiki-from-your-conversations", "canonical_source": "https://github.com/AlmanacCode/codealmanac/", "published_at": "2026-07-21 17:12:01+00:00", "updated_at": "2026-07-21 17:55:43.562418+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["CodeAlmanac", "Codex", "Claude Code", "Yoke SDK", "Hacker News"], "alternates": {"html": "https://wpnews.pro/news/show-hn-codealmanac-karpathy-style-codebase-wiki-from-your-conversations", "markdown": "https://wpnews.pro/news/show-hn-codealmanac-karpathy-style-codebase-wiki-from-your-conversations.md", "text": "https://wpnews.pro/news/show-hn-codealmanac-karpathy-style-codebase-wiki-from-your-conversations.txt", "jsonld": "https://wpnews.pro/news/show-hn-codealmanac-karpathy-style-codebase-wiki-from-your-conversations.jsonld"}}