CodeAlmanac
为 AI 编码代理维护的代码库活维基,记录代码本身说不出的事情:设计决策、流程、不变量和坑。
- Star 数
- ★ 950
- 最近更新
- 4 个月前
- License
- Apache-2.0
- 主语言
- TypeScript
- FA 评分
- 51/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 兼容但需适配Codex · Claude Code
- 费用
- 软件免费,模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 团队已有代码但缺乏设计文档时,用
codealmanac ingest把 PR、提交范围和源码目录转成可审阅的 Markdown 维基。 - 不适合
- 需要 Linux 或 Windows 支持的团队
- 不希望本地编码代理以广泛文件系统权限运行的用户
- 依赖托管云端同步或团队协作后端的组织
- 官网
- codealmanac.com ↗ 来自 GitHub 仓库设置
- 维护状态
- 近半年有提交最近提交 2026-07-17最新版本 v0.4.4(2026-07-11)
- 源码审查
- 51/100 · 缺口较多
这个 Agent 能做什么,适合哪些场景?
CodeAlmanac 是一个本地优先的命令行工具,在仓库内生成并维护一组纯 Markdown 维基页面(默认位于 almanac/ 目录),为 Codex 或 Claude Code 这类编码代理补充代码之外的上下文。它通过 init、ingest、garden 三个显式生命周期代理来创建、吸收材料和整理维基,这些代理被打包为 Yoke 代理集合,由 almanac-yoke 统一调度 Codex 或 Claude。所有运行时状态(作业记录、索引数据库、同步状态)保存在 ~/.codealmanac/ 下,维基本身则像普通代码一样提交到 Git 审查。阅读侧提供 search、show、topics、health、validate 等命令以及一个只读的本地 Web 查看器 codealmanac serve。项目当前仅支持 macOS,需要 Python 3.12+,写入类命令依赖本机已登录的 Codex 或 Claude Code。
核心流程围绕 Yoke 代理集合中的三个生命周期代理展开:build 由 codealmanac init 触发,创建 almanac/README.md、topics.yaml 及各文件夹下的 Markdown 页面;ingest 接收文件、目录、Git 差异、提交范围、GitHub PR/issue、URL 或本地代理对话记录,把其中有长期价值的知识折叠进维基,无价值时允许不做改动;garden 检查现有维基图,处理陈旧页面、链接、主题、重复内容和缺乏支撑的论断。每次运行会在 ~/.codealmanac/ 下生成持久化作业,可用 codealmanac jobs、jobs show、jobs logs、jobs attach、jobs cancel 查看与控制。阅读命令(search、show、topics、health、validate)读取本地派生索引 ~/.codealmanac/repos/<repo-id>/index.db,不需要模型凭据。可选的 launchd 后台任务每 5 小时扫描 Codex/Claude 对话记录执行同步,每 24 小时执行 garden 与 CLI 自动更新。codealmanac serve 提供只读的本地浏览器界面,渲染页面、搜索、主题、反向链接和文件引用跳转。
- 团队已有代码但缺乏设计文档时,用
codealmanac ingest把 PR、提交范围和源码目录转成可审阅的 Markdown 维基。 - 新成员或 AI 代理在大型仓库中定位某个模块的决策背景时,用
codealmanac search和codealmanac show直接获得页面。 - 长期使用 Claude Code 或 Codex 的开发者,让后台同步任务把对话中沉淀的经验自动归档到对应仓库的维基。
- 维基页面积累过多后,用
codealmanac garden清理重复、陈旧和孤立的页面与链接。 - 在代码评审流程中,把 almanac/ 目录当作普通源码提交,让维基改动与代码改动一起走 Git 审核。
- 希望在浏览器中浏览和交叉跳转维基内容而不想部署服务时,使用本地只读查看器
codealmanac serve。
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 安装 / 启动命令
uv tool install codealmanac@latest
- 运行环境
- Python 3.12+
- 安装说明涉及
- macOS
如何安装或部署这个 Agent?
需要 macOS、Python 3.12+ 与 uv,以及已登录的 Codex 或 Claude Code CLI。
uv tool install codealmanac@latest
codealmanac setup以推荐默认值快速安装(默认使用 Codex 作为 AI 运行器):
codealmanac setup --yes改用 Claude 作为运行器:
codealmanac setup --yes --runner claude若从旧版 npm 包迁移,需先卸载旧全局包与其安装的钩子:
npm uninstall -g codealmanac
uv tool install codealmanac@latest
codealmanac setup --yes
codealmanac doctor安装后可用 codealmanac doctor 检查运行器是否可用。
如何使用这个 Agent?
在仓库中初始化并读取维基:
cd your-repo
codealmanac init
codealmanac search "getting started"
codealmanac show getting-started
codealmanac serve吸收材料与整理维基(需要已认证的 Codex 或 Claude):
codealmanac ingest README.md --using codex
codealmanac ingest github:pr:123 --using claude
codealmanac garden --using codex跟踪作业:
codealmanac jobs
codealmanac jobs show <run-id>
codealmanac jobs logs <run-id>
codealmanac jobs attach <run-id>查看与调整自动化任务:
codealmanac automation status
codealmanac config set automation.sync.every 5h
codealmanac config set automation.sync.enabled false关闭遥测:
codealmanac config set telemetry.enabled false这个 Agent 有哪些优点和局限?
- 维基是仓库内的纯 Markdown 与 topics.yaml,与代码一起提交和评审,不锁定在任何私有格式或托管服务中。
- 围绕 build、ingest、garden 三种显式生命周期代理组织工作,并有持久化作业记录,可用 jobs logs/attach 追踪执行过程。
- 阅读命令与本地只读查看器不消耗模型凭据,只有写入类生命周期命令才需要 Codex 或 Claude。
- 通过 almanac-yoke 统一提供方边界,Codex 与 Claude 可在同一 CLI 中切换,并复用已有 OAuth 登录。
- 遥测默认可选关闭,README 明确声明不上传代码、路径、提示、对话和命令参数。
- 当前仅支持 macOS,需要 Python 3.12+,并按平台使用 launchd 后台任务。
- 写入类命令让编码代理以广泛、非交互的文件系统权限运行,almanac/ 边界只是指令与提交策略而非操作系统沙箱。
- 依赖本机已安装并登录的 Codex 或 Claude Code CLI,出现 ENOENT 一类安装损坏时需手动重装。
- 从旧 npm 分发的迁移需要手工清理旧全局包、钩子和遗留二进制,存在残留风险。
- README 中的默认模型(如 gpt-5.5)会随上游变化,实际行为受所选运行器版本影响。
这个 Agent 与同类方案有什么区别?
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| CodeAlmanac 当前 | 51 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 950 | 4 个月前 | TypeScript | Codex · Claude Code |
| Yardlet | 80 · 表现良好 | 桌面应用免费 | ★ 46 | 今天 | Swift | Codex · Claude Code |
| wsp | 59 · 缺口较多 | 桌面应用免费 + 模型费 | ★ 15 | 8 天前 | TypeScript | Codex · Claude Code |
| Crew44 | 48 · 缺口较多 | 桌面应用免费 + 模型费 | ★ 358 | 5 个月前 | Go | Codex · Claude Code |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
信任:README 明确说明生命周期代理以“广泛、非交互式文件系统权限”运行,almanac/ 边界只是指令与提交策略而非 OS 沙箱,属于权限过宽且无隔离,故 least_privilege 仅 1;setup/uninstall 有 --yes 与交互确认、非交互无 --yes 时非零退出(见 uninstall 计划),user_confirmation 得 2;遥测默认推荐开启但提供 --no-telemetry、DO_NOT_TRACK、config 关闭,且声明不上传代码/路径/提示词,透明度尚可但默认开启扣分,data_flow_transparency 得 2;sensitive_data_handling 方面会扫描本地 Codex/Claude 会话记录并入库,虽声明本地存储,但敏感会话内容的处理边界描述薄弱,得 1;依赖清单含 posthog 遥测、almanac-yoke 等,无锁文件或漏洞审计证据,dependency_security 得 1;external_effects 涉及 launchd 定时任务、自动更新、自动提交,虽有开关但默认开启且影响面大,得 1;rollback 有 uninstall --yes、--no-auto-commit、jobs cancel 与 Git 提交可回滚,得 2;source_attribution 仅 README 徽章与 pyproject 作者字段,发布者身份未验证,得 1。
可靠性:AGENTS.md/CLAUDE.md 仍引用 .almanac/、npm、TypeScript 与旧路径,与 README 的 almanac/、PyPI、Python 重写不一致,self_consistency 得 1;依赖版本有下界约束且 CI 用 uv sync --locked,dependency_availability 得 2;Troubleshooting 与 doctor 提供具体失败信息,failure_messages 得 2。
适应性:README 明确面向 AI 编码代理与开发者、支持 macOS+Codex/Claude,audience_and_scenarios 得 2;Current Contract 明确本地-only、无托管、无 MCP,capability_boundaries 得 2;SKILL.md 的 description 触发条件具体,trigger_precision 得 2;但仅支持 macOS 与两种 harness,environment_fit 得 1。
惯例:README 结构清晰、有目录树与命令表,information_architecture 得 2;安装步骤与迁移说明完整,install_notes 得 2;命名在 almanac/codealmanac、.almanac/almanac 间存在历史漂移,naming_stability 得 1;有 Quickstart、Troubleshooting、迁移示例,examples_and_faq 得 2;明确列出当前限制(仅 macOS、本地-only、无托管),known_limitations 得 2;LICENSE.md 为完整 Apache-2.0 且 pyproject 声明一致,license 得 3;pyproject 有版本号但无 CHANGELOG,versioning_changelog 得 1;维护责任仅靠作者字段与 Discord/LinkedIn,无明确维护者承诺,maintenance_responsibility 得 1。
有效性:CLI 输出、jobs、viewer、JSON 输出使结果可用,output_usability 得 2;相对普通文档提供决策/不变量等增量价值,marginal_value 得 2;但需本地代理、定时任务与遥测,成本较高,cost_benefit 得 1。
可验证性:README 声明多为产品描述,缺少可追溯的测试或基准证据,claim_traceability 得 1;docs/bugs 与 plans 提供部分交叉印证但多为历史/计划文档,cross_source_corroboration 得 1;文档中事实与推断(如“更权威”)混用,fact_inference_separation 得 1。
- 生命周期代理以广泛非交互式文件系统权限运行,almanac/ 不是 OS 沙箱;仅在信任该模型的仓库中使用。
- 默认安装 launchd 定时任务(同步、garden、自动更新)并默认 auto_commit=true,可能自动提交与自动升级,建议显式关闭或审查。
- 遥测默认推荐开启,虽可关闭且声明不上传代码/路径/提示词,仍应确认配置。
- AGENTS.md/CLAUDE.md 仍引用 .almanac/、npm、TypeScript 等旧路径,与 README 的 Python/PyPI 重写不一致,可能误导代理。
- 发布者身份未经验证,依赖清单含遥测与第三方 SDK,缺少锁文件与漏洞审计证据。
- 仅支持 macOS 与 Codex/Claude,其他环境不可用。
最近版本
来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。
-
v0.4.4 CodeAlmanac 0.4.4
发布说明摘录
Full Changelog: https://github.com/AlmanacCode/codealmanac/compare/v0.4.3...v0.4.4在 GitHub 查看 ↗ -
v0.4.3 CodeAlmanac 0.4.3
发布说明摘录
Build, ingest, and garden are now packaged as a first-class Yoke agent collection. Stable instructions live in Yoke agent folders; lifecycle workflows send only typed runtime context. Removes the old prompt-rendering service, requires Yoke 0.1.5, preserves the previous instruction words exactly, and refreshes the canonical provider/agent architecture documentation.在 GitHub 查看 ↗ -
v0.4.2 CodeAlmanac 0.4.2
发布说明摘录
Requires Yoke 0.1.4 so Codex internal message/reasoning lifecycle wrappers stay out of human-readable CLI and viewer activity. Real assistant text, tools, native subagents, statuses, and failures remain visible.在 GitHub 查看 ↗
常见问题
使用 CodeAlmanac 需要付费吗?
维基内容会被上传到 CodeAlmanac 的服务器吗?
生命周期代理有多大的文件系统权限?
可以在 Linux 或 Windows 上使用吗?
如果自动更新或后台任务出问题怎么办?
codealmanac automation status 查看已安装任务,用 codealmanac config set automation.<job>.enabled false 关闭,或用 codealmanac uninstall --yes 移除 CodeAlmanac 创建的本地产物;日志位于 ~/.codealmanac/logs/。CodeAlmanac 官网是什么?
CodeAlmanac 开源吗?
CodeAlmanac 还在维护吗?
CodeAlmanac 是谁开发的?
谢谢反馈,我们会据此改进页面。