CodeAlmanac

为 AI 编码代理维护的代码库活维基,记录代码本身说不出的事情:设计决策、流程、不变量和坑。

Star 数
★ 950
最近更新
4 个月前
License
Apache-2.0
主语言
TypeScript

30 秒速览

运行形态
命令行工具
可在哪里用
兼容但需适配Codex · Claude Code
费用
软件免费,模型调用费用自付
上手难度
中 · 需要几步配置
开始前需要
macOSPython 3.12+uvCodex CLI 或已认证的 Claude Code CLIShell / 命令行网络访问本地文件系统
典型场景
团队已有代码但缺乏设计文档时,用 codealmanac ingest 把 PR、提交范围和源码目录转成可审阅的 Markdown 维基。
不适合
  • 需要 Linux 或 Windows 支持的团队
  • 不希望本地编码代理以广泛文件系统权限运行的用户
  • 依赖托管云端同步或团队协作后端的组织
官网
codealmanac.com ↗ 来自 GitHub 仓库设置
维护状态
近半年有提交最近提交 2026-07-17最新版本 v0.4.4(2026-07-11)

这个 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 提供只读的本地浏览器界面,渲染页面、搜索、主题、反向链接和文件引用跳转。

  1. 团队已有代码但缺乏设计文档时,用 codealmanac ingest 把 PR、提交范围和源码目录转成可审阅的 Markdown 维基。
  2. 新成员或 AI 代理在大型仓库中定位某个模块的决策背景时,用 codealmanac search 和 codealmanac show 直接获得页面。
  3. 长期使用 Claude Code 或 Codex 的开发者,让后台同步任务把对话中沉淀的经验自动归档到对应仓库的维基。
  4. 维基页面积累过多后,用 codealmanac garden 清理重复、陈旧和孤立的页面与链接。
  5. 在代码评审流程中,把 almanac/ 目录当作普通源码提交,让维基改动与代码改动一起走 Git 审核。
  6. 希望在浏览器中浏览和交叉跳转维基内容而不想部署服务时,使用本地只读查看器 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?

FollowAgents 源码审查 · FARS-2.1
缺口较多
51/ 100 五分制 2.6 / 5
信任安全 13/29
可靠稳定 8/14
适用触发 10/18
规范维护 10/18
有效结果 7/13
证据核验 3/8
查看各维度的扣分理由
信任安全13 / 29 · 2.2/5

信任: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。

可靠稳定8 / 14 · 2.9/5

可靠性: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。

适用触发10 / 18 · 2.8/5

适应性: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。

规范维护10 / 18 · 2.8/5

惯例: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。

有效结果7 / 13 · 2.7/5

有效性:CLI 输出、jobs、viewer、JSON 输出使结果可用,output_usability 得 2;相对普通文档提供决策/不变量等增量价值,marginal_value 得 2;但需本地代理、定时任务与遥测,成本较高,cost_benefit 得 1。

证据核验3 / 8 · 1.9/5

可验证性: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,其他环境不可用。
证据充分度:低 评估于 2026年11月17日 审查版本 0f153501f40a
查看完整评分方法 →
你是这个项目的维护者?把 FARS 徽章加到 README

徽章显示当前的评审分数和结论,点击回到本页。重新评审后约一小时内更新。

FARS

[![FARS 评测](https://followagents.com/badge/codealmanac.svg?lang=zh)](https://followagents.com/zh/agents/codealmanac)
<a href="https://followagents.com/zh/agents/codealmanac"><img src="https://followagents.com/badge/codealmanac.svg?lang=zh" alt="FARS 评测"></a>

最近版本

来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。

  1. v0.4.4 CodeAlmanac 0.4.4
    发布说明摘录
    Full Changelog: https://github.com/AlmanacCode/codealmanac/compare/v0.4.3...v0.4.4
    在 GitHub 查看 ↗
  2. 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 查看 ↗
  3. 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 需要付费吗?
CLI 本身免费且开源(Apache-2.0),但写入类命令会调用本机已登录的 Codex 或 Claude,费用取决于该模型服务的订阅或用量计费;阅读命令和本地查看器不需要模型凭据。
维基内容会被上传到 CodeAlmanac 的服务器吗?
不会。README 声明的当前契约是本地优先:维基是仓库内 Markdown,运行时状态在 ~/.codealmanac/,后台任务由本地 launchd 调度;匿名遥测只包含受控的命令与生命周期结果以及脱敏崩溃,可随时关闭。
生命周期代理有多大的文件系统权限?
README 明确指出 build、ingest、garden 以广泛、非交互的权限运行,almanac/ 目录边界属于指令和提交策略,不是操作系统级沙箱;建议只在接受该信任模型的仓库中执行,并在关闭自动提交时审查 Git 差异。
可以在 Linux 或 Windows 上使用吗?
当前不支持。README 声明支持范围为 macOS、Python 3.12+,自动化基于 macOS launchd 任务。
如果自动更新或后台任务出问题怎么办?
可用 codealmanac automation status 查看已安装任务,用 codealmanac config set automation.<job>.enabled false 关闭,或用 codealmanac uninstall --yes 移除 CodeAlmanac 创建的本地产物;日志位于 ~/.codealmanac/logs/。
CodeAlmanac 官网是什么?
CodeAlmanac 的 GitHub 仓库填写的官网是 https://codealmanac.com。这个链接由仓库作者设置;源码在 GitHub(AlmanacCode/codealmanac)。
CodeAlmanac 开源吗?
开源。源码在 GitHub(AlmanacCode/codealmanac),许可证是 Apache-2.0。
CodeAlmanac 还在维护吗?
更新变慢了:GitHub 上最近一次提交是 2026-07-17,在最近半年内,但不在最近 30 天内。最新版本是 v0.4.4(2026-07-11)。
CodeAlmanac 是谁开发的?
CodeAlmanac 由 GitHub 账号 AlmanacCode 发布。FollowAgents 没有核实这个账号背后是哪个人或公司。
这页内容对你有帮助吗?
在 GitHub 查看 ↗ 安装 ↓

所属宿主生态

对比同类 Agent

用同一套 FARS 评审,横向比较这个 Agent 所属的短名单。

相关核心概念