商业产业 Hacker News LLM 2026-07-09T17:21 正文 ok 1307 words

Show HN: CodeAlmanac – 为你的编程 Agent 提供自我更新的本地 Wiki（基于 Apache 2.0）

英文标题：🔶 Show HN: CodeAlmanac – Self-updating wiki for your coding agent (local, Apache)

CodeAlmanac 是一个由 AI 编程 Agent 维护的“活”Wiki，将代码库中无法仅靠代码承载的上下文（如架构原因、历史故障、不变量和跨文件工作流）沉淀为仓库中的 Markdown 文件。该项目提供本地 CLI 工具，支持搜索、阅读、通过 Agent 自动编写/整理页面，并可设置定时同步与花园整理任务。对开发者而言，它提供了一种可版本化、可审查的结构化知识管理方式，帮助 Agent 更准确地理解复杂系统，目前仅支持本地运行，未引入任何云端依赖。

打开原文相关 6 · 机会 1

837.1 KB

1.2 KB

2.7 KB

3.1 KB

1.3 KB

1.7 KB

1.3 KB

69.8 KB

中文

为你代码库提供的一个活 Wiki，由 AI 编程 Agent 维护。

CodeAlmanac 为 AI Agent 提供那些仅靠代码本身无法承载的上下文：系统为何如此设计、之前出现过哪些故障、哪些不变量至关重要，以及工作流如何跨文件和跨服务协作。该 Wiki 是仓库中的纯 Markdown 内容，在本地建立索引，并像其他代码变更一样通过 Git 进行审查。

curl -fsSL https://codealmanac.com/install.sh | sh

# 任选一种安装路径：
codealmanac setup                       # 交互式安装
codealmanac setup --yes                 # 快速安装；使用 Codex 作为 AI 运行器
codealmanac setup --yes --runner claude # 快速安装；使用 Claude 作为 AI 运行器

cd your-repo
codealmanac init                     # 如果尚未有 Wiki，则创建一个
codealmanac search "getting started" # 显示匹配的 Wiki 页面。
codealmanac show getting-started     # 在终端中打开某个页面
codealmanac serve                    # 在本地 Web 查看器中展示 Wiki。

通过安装脚本：

curl -fsSL https://codealmanac.com/install.sh | sh

或直接安装：

uv tool install codealmanac@latest

或：

python -m pip install codealmanac

从当前检出的代码安装：

uv sync
uv run codealmanac --help

需要 Python 3.12 及以上版本。

从 npm CLI 迁移

旧的 codealmanac npm 包已退役。PyPI 是目前唯一支持的发布渠道。如果你之前使用过 npm CLI，你的机器上可能还残留旧的全局安装以及它设置的钩子和 Agent 指令。在从 PyPI 安装之前，请先移除这些残留。

最简单的做法是把下面这段提示交给你的编程 Agent：

将本机从旧的 codealmanac npm CLI 迁移到新的 PyPI CLI。

1. 卸载所有旧版 CLI 及其依赖：
   npm uninstall -g codealmanac
   同时检查 bun、pnpm 和 yarn 的全局安装，并删除 PATH 中残留的任何
   codealmanac、almanac 或 alm 二进制文件。
2. 删除旧 CLI 安装到 Agent 工具中的所有内容：
   - 从 Claude Code 设置中删除 codealmanac 钩子
     （~/.claude/settings.json 以及项目内的 .claude/settings*.json）。
   - 从 ~/.claude/CLAUDE.md 及其他 Agent 指令文件中删除 codealmanac 相关段落
     和 @-import 引用。
3. 安装最新的 PyPI CLI：
   curl -fsSL https://codealmanac.com/install.sh | sh
4. 运行 codealmanac setup --yes 以重新安装 Agent 指令和自动化。
5. 验证迁移：
   which codealmanac 应指向新安装的版本，且 codealmanac --help 可以运行。

保留仓库本地的 almanac/ wiki 目录树——它们是已提交的 wiki 内容，不属于 CLI 安装的部分。

为你所使用的本地工具安装全局 Agent 指令：

# 交互式安装
codealmanac setup

# 使用推荐的默认设置快速安装；使用 Codex 作为 AI 运行器
codealmanac setup --yes

# 使用 Claude 作为 AI 运行器快速安装
codealmanac setup --yes --runner claude

安装程序会安装本地 Agent 指令以及默认的本地自动化：sync（同步）、garden（花园整理）和每日包更新。它不会连接到任何托管服务。

如果你没有 Codex 或更偏好 Claude，请使用 --runner claude。

--target 仅用于选择要安装哪些全局 Agent 指令文件；它不会选择 AI 运行器：

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

其他安装选项：

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

要卸载 CodeAlmanac 创建的本地产物：

codealmanac uninstall --yes

Agent 和人类使用相同的本地读取命令：

codealmanac search "checkout timeout"
codealmanac search --mentions src/checkout/
codealmanac show checkout-flow
codealmanac topics
codealmanac health
codealmanac validate

使用 --wiki <name> 来读取另一个已注册的本地 Wiki。默认情况下，当当前目录是一个已注册的仓库根目录时，命令会精确地指向该目录。

生命周期命令可以请求已配置的本地 Agent 执行环境来编辑 Wiki 页面。它们只允许对 almanac/ 下的源文件进行编辑。

codealmanac ingest README.md --using codex
codealmanac ingest github:pr:123 --using claude
codealmanac garden --using codex

ingest 将选中的本地材料整合到 Wiki 中。输入源可以包括文件、目录、Git diff、提交范围、GitHub PR 或 issue、URL 以及本地 Agent 对话记录。

garden 对现有的 Wiki 图谱进行改进：处理陈旧页面、链接、主题、弱引导段落、重复页面和未经证实的声明。

空操作是有效的。如果材料没有添加持久的 Wiki 知识，执行环境应保持 Wiki 不变。

ingest 和 garden 会创建排队运行任务并启动一个本地工作进程。使用 codealmanac jobs 和 codealmanac jobs attach <run-id> 来跟踪它们。

sync 扫描本地的 Claude 和 Codex 对话记录存储，查找自上次完成同步以来的活跃对话，并将普通的本地 ingest 运行任务加入队列。

codealmanac sync status --from codex
codealmanac sync --from codex --using codex
codealmanac automation install sync --every 5h
codealmanac automation install update --every 24h
codealmanac automation status

定时自动化会在明确无人值守的策略下启动本地的 sync、garden 或 update 命令。它是本地调度器状态，而非云端同步。调度器日志位于 ~/.codealmanac/logs/ 下。

生命周期运行记录保存在 ~/.codealmanac/ 下：

codealmanac jobs
codealmanac jobs show <run-id>
codealmanac jobs logs <run-id>
codealmanac jobs attach <run-id>
codealmanac jobs cancel <run-id>

运行日志包含源解析信息、执行环境事件、安全错误和终止状态。

CodeAlmanac 目前支持本地的 Codex 应用服务器和 Claude Agent SDK 两种执行环境。

codex login
claude auth login
codealmanac doctor

读取命令不需要提供商凭据。具备写入能力的生命周期命令需要所选执行环境可用且已认证。

Init 创建了什么

使用默认根目录时：

your-repo/
|-- almanac/
|   |-- README.md
|   |-- topics.yaml
|   |-- architecture/
|   |   |-- README.md
|   |   `-- indexer.md
|   |-- decisions/
|   |   `-- local-first.md
|   `-- guides/
|       `-- setup.md
|-- src/
`-- ...

Markdown 页面直接存放在有意义的文件夹中的 almanac/ 下。topics.yaml 组织跨文件夹的页面。README.md 文件充当其文件夹路径的着陆页。

为了实现自动检测，当仓库中存在 almanac/topics.yaml 和 almanac/README.md 时，该仓库即被视为一个 CodeAlmanac Wiki。

衍生的本地状态保存在 ~/.codealmanac/ 下：

~/.codealmanac/codealmanac.db
~/.codealmanac/repos/<repo-id>/index.db

本地数据库记录仓库、运行、运行事件、工作进程锁和同步状态。每个仓库的运行时文件包含派生索引，它们不属于已提交的 almanac/ 目录树。

用户配置位于：

~/.codealmanac/config.toml

项目配置位于：

首批支持的默认值为：

auto_commit = true

[harness]
default = "codex"

CLI 标志优先级仍然高于配置文件。

auto_commit 意味着生命周期提示可能会告知所选 Agent 使用常规 Git 命令来进行 Wiki 源文件更改。CodeAlmanac 本身不会暂存文件、拆分差异或在内部进行提交。

codealmanac setup --no-auto-commit
codealmanac config set auto_commit false
codealmanac config set auto_commit true

查看器是只读的。它根据本地 Wiki 数据渲染页面、搜索、主题、反向链接和文件引用导航。默认情况下，它可以在多个已注册的本地 Wiki 之间切换。使用 codealmanac serve --wiki <name> 可将查看器限定在某个 Wiki 上。

`harness codex failed with status failed: Error: spawn ... codex ENOENT`

本机上的 Codex CLI 已损坏或缺失：@openai/codex 包已安装，但其原生二进制文件已消失（这通常是安装中断或在 nvm/volta/fnm 下切换 Node 版本导致的常见结果）。通过以下命令验证：

如果该命令同样出现 spawn ... ENOENT 错误，请重新安装 Codex CLI：

npm install -g @openai/codex
codex --version       # 确认二进制文件可以运行
codex login status    # 确认仍处于登录状态

重新安装不会使你退出登录：codex 将其登录信息保存在 ~/.codex 下，而非 npm 包内。

或者将 CodeAlmanac 切换为使用 Claude 执行环境：

codealmanac config set harness.default claude

对于 harness claude failed 错误，同样的处理方法：检查 claude --version，如果 Claude Code CLI 已损坏则重新安装，或切换默认执行环境。codealmanac doctor 会报告执行环境的可用性。

本次重写目前仅支持本地使用。

公开命令：codealmanac
仓库 Wiki 根目录：仅 almanac/
备用仓库 Wiki 根目录：无
用户状态根目录：~/.codealmanac/
运行时：Python 3.12+
存储：本地 Markdown 及 ~/.codealmanac/ 下的派生状态
没有托管的登录/连接/上传命令。
没有公开的 SDK 或 MCP 包。
没有兼容性别名。
没有备用 Wiki 根目录。
没有隐藏的云端写入路径。
没有第二个 Wiki 命令名称。

这是以 Python/PyPI 形式提供的产品表面。后续可以围绕同一个仓库拥有的 Wiki 制品添加托管集成，但那不属于本次发布的内容。

English / 原文

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.

curl -fsSL https://codealmanac.com/install.sh | sh

# Choose one setup path:
codealmanac setup                       # Interactive setup
codealmanac setup --yes                 # Quick install; uses Codex as the AI runner
codealmanac setup --yes --runner claude # Quick install; uses Claude as the AI runner

cd your-repo
codealmanac init                     # Makes your wiki, if you don't have one
codealmanac search "getting started" # Shows matching wiki pages.
codealmanac show getting-started     # Opens one page in the terminal
codealmanac serve                    # Shows the wiki in local web viewer.

With the install script:

curl -fsSL https://codealmanac.com/install.sh | sh

or directly:

uv tool install codealmanac@latest

or:

python -m pip install codealmanac

From this checkout:

uv sync
uv run codealmanac --help

Requires Python 3.12+.

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.

The easiest path is to hand this prompt to your coding agent:

Migrate this machine from the old codealmanac npm CLI to the new PyPI CLI.

1. Uninstall every old install of the CLI and its dependencies:
   npm uninstall -g codealmanac
   Also check bun, pnpm, and yarn global installs, and remove any stray
   codealmanac, almanac, or alm binaries left on PATH.
2. Remove everything the old CLI installed into agent tooling:
   - Delete codealmanac hooks from Claude Code settings
     (~/.claude/settings.json and any project .claude/settings*.json).
   - Remove codealmanac sections and @-imports from ~/.claude/CLAUDE.md and
     any other agent instruction files.
3. Install the latest PyPI CLI:
   curl -fsSL https://codealmanac.com/install.sh | sh
4. Run codealmanac setup --yes to reinstall agent instructions and automation.
5. Verify the migration:
   which codealmanac points at the new install and codealmanac --help runs.

Leave repo-local almanac/ wiki trees alone - they are committed wiki content,
not part of the CLI install.

Install global agent instructions for the local tools you use:

# Interactive setup
codealmanac setup

# Quick install with recommended defaults; uses Codex as the AI runner
codealmanac setup --yes

# Quick install using Claude as the AI runner
codealmanac setup --yes --runner claude

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

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:

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

Other setup flags:

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

To uninstall CodeAlmanac-owned local artifacts:

codealmanac uninstall --yes

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 target the exact current directory when it is a registered repository root.

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 garden --using codex

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.

ingest and garden create queued runs and start a local worker. Use codealmanac jobs and codealmanac jobs attach <run-id> to follow them.

sync scans local Claude and Codex transcript stores, finds conversations active since the last completed sync, and queues ordinary local ingest runs.

codealmanac sync status --from codex
codealmanac sync --from codex --using codex
codealmanac automation install sync --every 5h
codealmanac automation install update --every 24h
codealmanac automation status

Scheduled automation launches local sync, garden, or update commands with explicit unattended policy. It is local scheduler state, not cloud sync. Scheduler logs live under ~/.codealmanac/logs/.

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.

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.

Derived local state lives under ~/.codealmanac/:

~/.codealmanac/codealmanac.db
~/.codealmanac/repos/<repo-id>/index.db

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.

User config lives at:

~/.codealmanac/config.toml

Project config lives at:

The first supported defaults are:

auto_commit = true

[harness]
default = "codex"

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

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.

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

npm install -g @openai/codex
codex --version       # confirm the binary runs
codex login status    # confirm you are still signed in

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

Or switch CodeAlmanac to the Claude harness instead:

codealmanac config set harness.default claude

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.

This rewrite is local-only for now.

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

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.