Agach MCP

Describe the feature. Agents build it.

Agach orchestrates AI coding agents for your team.

Define features through structured conversations. Agents execute the work

in isolated environments, one task at a time, on your codebase.

Open source · Self-hosted · Your code stays on your infrastructure

How It Works · Quick Start · Features · Architecture · Status

______________________________________________________________________

问题

AI可以写代码。瓶颈移动了。

代理会话从零上下文开始——之前的决定、尝试和失败的东西都消失了。规格是一个提示，有人输入并希望最好。当一个功能在几周后中断时，修复代理不知道最初的意图是什么，也不知道哪些合同必须仍然有效。总理问“状态如何？”而答案就在没有人看的终端窗口里。

缺少的是将功能描述与自主代理执行连接起来的层——具有结构化规划、跨任务的上下文保护、质量门、成本跟踪和整个团队的可见性。

运作原理

Agach有四个组成部分：a 服务器 （仪表板+API），a 守护进程 （在您的计算机或构建服务器上运行），a 边车 （在每个代理容器内运行），以及 代理定义 （定义代理工作方式的提示模板）。

1.定义特征

团队成员描述他们想要什么。在编写任何代码之前，规划代理读取代码库，挑战模糊的需求，协商范围，并生成具有可测试验收标准的结构化任务文件。

计划对话通过仪表板进行。守护进程在仓库的git工作树上生成一个Claude Code会话，消息实时双向流动。代币成本实时跟踪。完整的对话是持久的和可搜索的——它成为每个功能背后的“为什么”。

You:    We need OAuth2 login with Google
Agent:  "Handle errors gracefully" — what does that mean concretely?
        Return 400? Log and continue? Show a user-facing message?
You:    Return 401 with a JSON error body for invalid tokens
Agent:  Got it. Creating 6 tasks with dependencies...

规划代理生成：一个包含验收标准的特征规范、一个依赖关系图，以及每个任务一个包含上下文、预检查和断路器的文件。

2.代理人执行工作

守护进程接收未阻塞的任务，准备隔离的Docker容器，并为每个任务运行一个代理会话。每个容器都会自动注入sidecar——代理通过sidecar公开的MCP工具与agach交互，而sidecar则处理与服务器的所有通信。

[14:02] picking up task-3 — refresh token rotation
        loading parent summaries: task-1, task-2
        spawning container with sidecar...

[14:18] task-3 completed — summary pushed via sidecar
        tokens: 42,180 in / 8,340 out

[14:18] task-4 unblocked — token revocation on logout

在容器内部，代理可以看到MCP工具，如 complete_task, create_subtask, report_blocked，以及 push_summary。sidecar将这些转换为服务器API调用，上传摘要文件，并将状态更新流式传输回守护进程。代理从不直接与服务器通信——sidecar是唯一的桥梁。

任务遵循TDD工作流程：a 红色 代理编写失败的测试 绿色 代理使其以最少的实现通过 重构 代理清理，和 审稿人 根据原始验收标准进行验证。

3.审查叙述，而不是代码

工作完成后，仪表板将按执行顺序显示完整的功能叙述——每个任务摘要。你阅读的是代理做出的决策，而不是数千行生成的代码。当你需要时，代码差异就在那里，但摘要是你发现架构错误、范围蔓延和误解需求的地方。

合并请求通过您现有的审核管道。阿加奇不会取代你的工具。它养活了他们。

4.Bug倒流

当针对已完成的功能报告错误时，原始任务文件、验收标准、计划对话和完成摘要都可以作为上下文使用。修理工知道建造了什么，为什么建造，以及哪些合同必须仍然有效：

✓  Provider config loads from env
✓  Login redirects to Google
✗  Refresh token rotates on expiry       ← broken
✓  Logout revokes all tokens
✓  Integration tests pass

快速开始

git clone https://github.com/JLugagne/agach.git
cd agach
docker compose up --build

打开 http://localhost:8322默认凭据： admin@agach.local / admin --立即改变这一点。

连接守护进程

在仪表板上，在节点下生成入职代码。然后在您的机器上：

export AGACH_SERVER_URL=http://localhost:8322
export AGACH_ONBOARDING_CODE=123456
agach-daemon

守护进程向服务器注册，接收令牌，并通过WebSocket连接。

代币成本

Agach旨在生产 优质代码，而不是尽量减少令牌的使用。多代理TDD工作流——规划、脚手架、红色、绿色、重构、审查——用令牌换取正确性和可追溯性。单个功能可能会在许多代理会话中消耗大量令牌。

这是设计出来的。目标是结构化、可审查、支持回归的输出，而不是最便宜的差异路径。

如何保持成本合理

也就是说，有一些做法可以在不牺牲质量的情况下减少浪费：

• 保持你的 CLAUDE.md 简洁的。 每个代理会话都将其加载到上下文中。一个包含冗余指令、长示例或复制粘贴文档的臃肿文件会在每个任务上燃烧令牌。使用Agach技能（按需加载），而不是内联所有内容。
• 不要连接不必要的MCP服务器。 每个MCP服务器都会将工具定义添加到上下文窗口中。仅配置代理角色实际需要的服务器。
• 正确定义您的代理。 每个代理上2000行的系统提示是昂贵的。让提示集中在代理的具体工作上。通过技能而不是重复来分享共同的指示。
• 代理人越少，做得就越少。 红色/绿色/重构/审查周期对于复杂的功能很有价值。对于单行配置更改，具有直接提示的单个代理是可以的。将工作流与任务相匹配。
• 明智地使用任务依赖关系。 不必要的顺序依赖会妨碍并行性并增加挂钟时间，从而增加上下文漂移和返工的机会。
• 监控成本仪表板。 Agach跟踪每个任务和每个功能令牌的使用情况。检查一下。如果一个任务消耗了20万个令牌，那么提示或任务范围可能需要改进。

特性

服务器

• 功能生命周期 --草稿→ 准备→ 进行中→ done → 此 路 不通。每个功能的任务摘要。特征级统计
• 新增的定制看板图 --四列，拖放，内联编辑，实时WebSocket更新，任务依赖关系，WIP限制
• 专题叙述 --按执行顺序排列的功能的所有任务摘要。主要审查表面
• 代理管理 --使用提示模板、技能和技术栈定义代理。分配给项目。克隆和自定义
• 技能 --附加到代理的可重用功能。独立管理，自由创作
• Dockerfiles --附加到项目的版本化容器定义。守护进程从这些构建映像
• 身份 -用户、团队、JWT认证、API密钥、SSO（Google、GitHub）、基于角色的访问
• 节点 --通过有时限的入职代码注册守护进程实例。跟踪状态，管理访问权限
• 通知 --项目、代理和全球范围。严重程度。读取跟踪
• 成本跟踪 --每任务令牌使用情况（输入、输出、缓存）、冷启动指标、每模型成本明细
• 统计 --任务速度、令牌使用、模型成本、功能完成率
• REST API --每个实体的完整CRUD
• 实时 --用于仪表板和守护进程通信的WebSocket事件

守护进程

• 计划聊天 --在git工作树上生成Claude Code，通过仪表板双向传输消息，实时跟踪成本，在会话结束时保持完整对话
• Git工作树管理 --根据项目缓存，使用SSH和HTTPS身份验证进行克隆或拉取
• Docker构建 --构建、检查、修剪图像。流构建日志。本地SQLite用于构建历史记录
• 容器编排 --为每个任务生成Docker容器，自动注入sidecar二进制文件，挂载工作树，在退出时收集结果
• 安全入职 --6位代码，15分钟TTL，一次性使用，自动令牌刷新
• 会话生命周期 --30分钟空闲TTL，带警告，优雅关机，JSONL上传结束

边车

sidecar是守护进程在启动时注入每个代理容器的小型二进制文件。它与容器内的Claude Code一起运行，并在代理和agach服务器之间提供桥梁。

• MCP服务器 --将一系列操作作为代理自然调用的MCP工具公开： complete_task, create_subtask, report_blocked, push_summary, attach_file, add_comment
• 摘要上传 --手表 _SUMMARY.md 文件并自动将其推送到服务器
• 状态流 --通过本地套接字向守护进程报告任务进度、令牌使用情况和代理状态
• 令牌转发 --使用守护进程范围的凭据与服务器进行身份验证。代理永远不会看到或处理身份验证令牌
• 心跳 --定期发送活动信号，以便守护进程和仪表板知道容器仍在工作
• 优雅关闭 --在容器停止时，在退出之前刷新待处理的摘要和状态更新

代理定义（包括）

• 规划器 --读取代码库，挑战需求，生成功能规范和所有任务文件
• 脾气暴躁的下午 --输出与计划器相同，但通过对抗性对话实现。压力测试你的假设
• 脚手架 --创建空文件骨架，以便在写入任何逻辑之前通过构建
• 红色 --为每个任务写入一个失败的测试。编译失败，原因正确
• 绿色 --以最少的实现使失败的测试通过。仅此而已
• 重构 --绿色后清理干净。无行为变化
• 审稿人 --根据原始特征规范验证所有验收标准
• 变基 --处理合并冲突

测试

• 91个Go测试文件，包括28个安全测试，记录了带有行引用的特定漏洞
• 契约测试模式：每个存储库接口都有一个模拟和行为测试套件
• Playwright E2E套件，具有确定性种子数据和Docker Compose基础设施

建筑

四个组成部分：

系统概述

graph TB
    subgraph Server
        API[REST API]
        WS[WebSocket Hub]
        Dashboard
        Identity
        PG[(PostgreSQL)]
        API --> PG
        Identity --> PG
    end

    subgraph Daemon
        Chat[Planning Chat]
        Git[Git Worktrees]
        Docker[Docker Builds]
        Scheduler[Task Scheduler]
        SQLite[(Local SQLite)]
        Docker --> SQLite
    end

    subgraph Container 1
        CC1[Claude Code]
        SC1[Sidecar]
        CC1 --> MCPtools
        MCPtools --> SC1
    end

    subgraph Container 2
        CC2[Claude Code]
        SC2[Sidecar]
        CC2 --> MCPtools
        MCPtools --> SC2
    end

    Dashboard  WS
    Daemon -- WebSocket + REST --> Server
    Scheduler -- spawns --> Container1
    Scheduler -- spawns --> Container2
    SC1 -- REST --> API
    SC2 -- REST --> API

任务执行流程

sequenceDiagram
    participant PM as PM / Dashboard
    participant S as Server
    participant D as Daemon
    participant C as Container
    participant SC as Sidecar

    PM->>S: Create feature
    PM->>S: Start planning chat
    S->>D: chat.start (WebSocket)
    D->>D: Clone/pull worktree
    D->>D: Spawn Claude Code
    D-->>PM: Stream planning conversation
    Note over PM,D: PM and planning agent negotiate spec

    D->>S: Upload conversation JSONL
    S->>S: Store tasks from plan

    loop For each unblocked task
        D->>D: Build Docker image (if needed)
        D->>C: Spawn container + inject sidecar
        C->>SC: complete_task (MCP)
        SC->>S: POST /api/tasks/{id}/complete
        SC->>S: Upload _SUMMARY.md
        S-->>PM: Task completed (WebSocket)
    end

    PM->>PM: Review feature narrative

TDD代理工作流程

graph LR
    S[scaffold-1] --> R1[red-1]
    S --> R2[red-2]
    S --> R3[red-3]
    R1 --> G1[green-1]
    R2 --> G2[green-2]
    R3 --> G3[green-3]
    G1 --> RF[refactor-1]
    G2 --> RF
    G3 --> RF
    RF --> RV[reviewer]

    style S fill:#6b7280,stroke:#4b5563,color:#f9fafb
    style R1 fill:#ef4444,stroke:#dc2626,color:#fff
    style R2 fill:#ef4444,stroke:#dc2626,color:#fff
    style R3 fill:#ef4444,stroke:#dc2626,color:#fff
    style G1 fill:#22c55e,stroke:#16a34a,color:#fff
    style G2 fill:#22c55e,stroke:#16a34a,color:#fff
    style G3 fill:#22c55e,stroke:#16a34a,color:#fff
    style RF fill:#a78bfa,stroke:#7c3aed,color:#fff
    style RV fill:#3b82f6,stroke:#2563eb,color:#fff

项目结构

internal/
  server/            # Project management
    domain/          #   Types, errors, repository interfaces
    app/             #   Business logic, prompt rendering
    inbound/         #   REST handlers, converters
    outbound/pg/     #   PostgreSQL + migrations
    ux/              #   React + TypeScript dashboard
  identity/          # Auth, users, teams, nodes
    domain/          #   Types, repositories, service interfaces
    app/             #   Auth, SSO, onboarding, node management
    inbound/         #   REST handlers
    outbound/pg/     #   PostgreSQL
  daemon/            # Agent orchestration
    domain/          #   Types, build repository
    app/             #   Chat manager, git service, Docker service
    client/          #   Onboarding, auth, projects, upload clients
    inbound/ws/      #   WebSocket event handlers
    outbound/sqlite/ #   Local build history
  sidecar/           # In-container bridge (planned)
    mcp/             #   MCP tool definitions
    client/          #   Server API client
    watcher/         #   Summary file watcher
pkg/
  server/            # Shared DTOs with validation
  daemonws/          # Shared WebSocket protocol (docker + chat events)
  controller/        # HTTP response helpers
  middleware/        # Auth, rate limiting, body limits
  websocket/         # WebSocket hub
  sse/               # Server-sent events hub

六边形建筑。域拥有这些接口。每个有界上下文都有自己的持久性，没有从其他上下文的导入。

技术栈

状态

阿加奇在 阿尔法.

工作

进行中

计划的

贡献

欢迎捐款。打开问题或提交拉取请求。

许可证

麻省理工学院