codejunkie99/agentic-stack

One brain, many harnesses. Portable .agent/ folder (memory + skills + protocols) that plugs into Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, Hermes, or DIY Python — and keeps its knowledge when you switch.

agentic‑stack

是什么

agentic-stack 是一个工具箱，可为十几种代码生成代理（Claude Code、Cursor、GitHub Copilot CLI、Gemini CLI 等）赋予一个 可移植的“大脑”。这个大脑存储在隐藏的 .agent/ 目录中，包含：

记忆层 – 可配置保留策略的工作记忆、情景记忆、语义记忆和个人文件。
技能 – 可复用、自我文档化的命令片段，代理可调用。
协议 – 权限模式和工具调用契约，强制安全使用工具。
数据层 – 本地仪表板，聚合所有代理的 token 成本、KPI 摘要、运行日志和每日报告。
飞轮导出 – 已批准的运行可转换为 trace 记录、评估案例或下游模型训练就绪的 JSONL，无需上传至云端。

其理念是，你可以从 Claude Code 切换到 Cursor（或同时运行多个），代理仍能保留其学习成果、偏好和自定义技能，因为这些信息存储在任何单一工具之外。

核心概念

概念	作用
可移植大脑（`.agent/`）	存储任何支持的工具均可读取的记忆、技能和协议定义。
有界循环	确定性、预算受限的“代理循环”（`agentic-stack loop run …`），在项目内运行，支持检查点、git 工作树隔离和审计日志。
审查协议	每晚 `auto_dream.py` 阶段化候选学习内容；人类（或主机代理）必须通过 CLI 工具明确毕业或拒绝，并保留理由。
数据层与仪表板	仅本地 TUI（`agentic-stack dashboard`）和可选 Web UI（`mission‑control`），显示代理健康状态、token 使用量和 KPI 摘要。
飞轮导出	`data_flywheel_export.py` 将已批准的运行转换为 trace 记录、上下文卡片、评估案例或下游模型训练就绪的 JSONL。

支持的代理（适配器）

仓库为以下每个代理提供轻量级适配器，均读取相同的 .agent/ 结构：

Claude Code
GitHub Copilot CLI
Cursor
Google Gemini CLI
Windsurf
OpenCode
OpenClaw
Hermes
Pi Coding Agent
Codex
Autohand Code
独立 Python 循环
Antigravity

安装后可通过 agentic-stack add <adapter> / remove 命令添加或移除适配器。

快速开始（macOS / Linux）

# Homebrew 安装（添加 tap 和 formula）
brew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack
brew install agentic-stack

# 初始化项目 – 向导安装所选适配器并创建 .agent/
cd my‑project
agentic-stack claude-code   # 或 cursor, codex 等

Windows 用户可克隆仓库并运行 install.ps1，指定所需适配器。

典型工作流

上手 – 运行 ./install.sh（或适配器快捷方式）。向导会询问一些偏好问题（名称、主语言、解释风格等），并写入 .agent/memory/personal/PREFERENCES.md。
运行有界循环 – 例如 agentic-stack loop run ci‑sweeper "make the failing test green" ./my‑project --yes。循环尊重 token/运行时间限制，并记录其操作。
审查 – 每晚 auto_dream.py 阶段化候选学习内容后，使用 CLI 工具：
- list_candidates.py 查看待处理的学习内容
- graduate.py <id> --rationale "…" 接受
- reject.py <id> --reason "…" 拒绝
检查 – agentic-stack dashboard（TUI）或 agentic-stack mission‑control（本地 Web UI）显示记忆健康状态、token 使用量和 KPI 图表。
导出 – data_flywheel_export.py 将已批准的运行转换为 JSONL、trace 记录或评估卡片，用于下游分析。

高级功能

外部大脑集成 – 可选的 codejunkie99/brain 服务器可作为 git 支持的长期记忆存储。通过 Homebrew 安装，并使用 agentic-stack brain … 命令连接。
记忆搜索（测试版） – 启用对所有记忆文档（.agent/memory/.features.json → Enable FTS memory search）的全文搜索。使用 SQLite FTS5，失败时回退至 rg/grep。
迁移向导 – 通过单个 ./install.sh transfer 命令，将大脑从一个项目迁移到另一个项目（或纯 Python 工具）并生成 curl 兼容包。
升级安全 – agentic-stack upgrade --dry-run 预览对 .agent/ 骨架的更改，不触及现有学习内容或偏好。

项目健康状况

许可证 – Apache 2.0
发布节奏 – 语义化版本；README 列出最近补丁（v0.19.1）和详细 CHANGELOG.md。
安装方式 – 可通过 Homebrew、普通 git clone + 安装脚本，或 Windows 上的 PowerShell 获取。
测试 – 包含特定工具验证脚本（如 test_claude_code_hook.py）。
社区 – 主要维护者为 @Av1dlive（README 中的 Twitter/X 链接）。无显式贡献指南，但项目为开源，代码结构便于扩展。

谁会使用它？

在多个 AI 编码助手之间工作，希望在它们之间保持一致的偏好、学习成果和可复用技能的 开发者。
构建内部 AI 增强开发流水线，需要审计追踪、token 成本监控，并能将已批准运行导出用于模型微调的团队。
探索代理循环、有界推理或记忆增强型 LLM 工作流，且不依赖外部服务的 研究者。

总结

agentic-stack 是一个相当完整的开源框架，为代码生成代理提供共享、可移植的记忆和技能集，以及用于安全有界执行、审查、监控和数据导出的工具。它明确位于 AI 代理工具领域，对熟悉 macOS/Linux/Windows 命令行安装的任何人来说都已准备就绪。