Add deep dive research documentation on AI agent orchestration and communication standards
- Introduced multiple markdown files covering agent spawn packages, inter-agent communication protocols, and multi-agent orchestration tools. - Detailed analysis of official SDKs for CLI agents (Claude Code, Codex, Gemini) and their integration potential. - Documented various competitor approaches to agent spawning and communication, highlighting strengths and weaknesses. - Provided insights into best practices for implementing multi-provider support within Electron applications. This comprehensive documentation aims to enhance understanding of the current AI agent ecosystem and serve as a resource for developers and stakeholders.
This commit is contained in:
iliya
parent
ecba775c76
commit
fe90ac866d
9 changed files with 4332 additions and 0 deletions
465
docs/research/agent-spawn-packages.md
Normal file
465
docs/research/agent-spawn-packages.md
Normal file
|
|
@ -0,0 +1,465 @@
|
|||
# Agent Spawn Packages — Deep Dive Research
|
||||
|
||||
**Дата:** 2026-03-25
|
||||
**Цель:** Найти лучший способ программно запускать CLI-агентов (Claude Code, Codex, Gemini CLI) из Electron-приложения.
|
||||
|
||||
---
|
||||
|
||||
## TL;DR — Итоговая Рекомендация
|
||||
|
||||
У всех трёх главных CLI-агентов **теперь есть ОФИЦИАЛЬНЫЕ SDK** для программного запуска:
|
||||
|
||||
| Агент | SDK Пакет | Лицензия | Зрелость |
|
||||
|-------|-----------|----------|----------|
|
||||
| Claude Code | `@anthropic-ai/claude-agent-sdk` | **Proprietary** (Commercial ToS) | Stable (v0.2.83) |
|
||||
| Codex | `@openai/codex-sdk` | **Apache-2.0** | Stable (v0.116.0) |
|
||||
| Gemini CLI | `@google/gemini-cli-sdk` + `@google/gemini-cli-core` | **Apache-2.0** | Early (v0.30.0+) |
|
||||
|
||||
**Вывод:** Вместо форка `@swarmify/agents-mcp` или написания своих spawn-обёрток, лучше использовать **официальные SDK** от каждого провайдера. Они более надёжны, поддерживаются, и дают нативный доступ без хрупкого парсинга stdout.
|
||||
|
||||
---
|
||||
|
||||
## 1. @swarmify/agents-mcp
|
||||
|
||||
**npm:** https://www.npmjs.com/package/@swarmify/agents-mcp
|
||||
**Сайт:** https://swarmify.co/
|
||||
**GitHub:** НЕ НАЙДЕН (closed-source или приватный репозиторий)
|
||||
|
||||
### Что это
|
||||
MCP-сервер, который позволяет любому MCP-клиенту (Claude, Codex, Gemini, Cursor) спавнить параллельных агентов. Часть экосистемы Swarmify.
|
||||
|
||||
### Предоставляет
|
||||
- **4 MCP-тула:** Spawn, Status, Stop, Tasks
|
||||
- **3 режима:** plan (read-only), edit (can write), ralph (autonomous)
|
||||
- Фоновые процессы — агенты переживают перезапуск IDE
|
||||
- Авто-детект Claude, Codex, Gemini CLI при установке
|
||||
|
||||
### Как спавнит агентов
|
||||
Агенты коммуницируют через файловую систему — каждый агент пишет в свой лог-файл (stdout.log). Тул Status читает эти логи, нормализует события между разными форматами агентов, и возвращает сводку.
|
||||
|
||||
### IAgent / BaseAgent — НЕ НАЙДЕНЫ
|
||||
Несмотря на множество поисков, интерфейсы `IAgent` и `BaseAgent` **не обнаружены** в публичной документации пакета. Возможно, они существуют внутри скомпилированного npm-пакета (можно проверить через `node_modules`), но исходный код закрыт.
|
||||
|
||||
### Оценка для нас
|
||||
- **Надёжность: 3/10** — Closed-source, нет GitHub, невозможно форкнуть
|
||||
- **Уверенность: 2/10** — Без исходного кода невозможно оценить качество
|
||||
- **Вердикт:** НЕ подходит для нашего проекта
|
||||
|
||||
---
|
||||
|
||||
## 2. @anthropic-ai/claude-agent-sdk (OFFICIAL)
|
||||
|
||||
**npm:** https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk
|
||||
**GitHub:** https://github.com/anthropics/claude-agent-sdk-typescript
|
||||
**Docs:** https://platform.claude.com/docs/en/agent-sdk/typescript
|
||||
**Версия:** 0.2.83 (25 марта 2026)
|
||||
**Лицензия:** Proprietary (Anthropic Commercial Terms of Service)
|
||||
**Звёзды:** ~1000 | **Форки:** ~117 | **Релизы:** 67
|
||||
**691 проект** в npm registry используют этот пакет
|
||||
|
||||
### Что это
|
||||
Официальный SDK от Anthropic для программного запуска Claude Code. Переименован из "Claude Code SDK" в "Claude Agent SDK". Даёт те же инструменты, agent loop и context management, что и Claude Code.
|
||||
|
||||
### Ключевой API
|
||||
|
||||
```typescript
|
||||
import { query } from "@anthropic-ai/claude-agent-sdk";
|
||||
|
||||
// Основная функция — async generator
|
||||
const q = query({
|
||||
prompt: "Fix the bug in auth.py",
|
||||
options: {
|
||||
model: "opus",
|
||||
cwd: "/path/to/project",
|
||||
allowedTools: ["Read", "Edit", "Bash"],
|
||||
permissionMode: "bypassPermissions",
|
||||
allowDangerouslySkipPermissions: true,
|
||||
maxTurns: 50,
|
||||
maxBudgetUsd: 5.0,
|
||||
env: { ANTHROPIC_API_KEY: "..." },
|
||||
mcpServers: { /* MCP config */ },
|
||||
agents: {
|
||||
// Программно определяемые субагенты
|
||||
reviewer: {
|
||||
description: "Code reviewer agent",
|
||||
prompt: "Review code for bugs",
|
||||
model: "sonnet",
|
||||
tools: ["Read", "Grep", "Glob"],
|
||||
}
|
||||
},
|
||||
settingSources: ["project"], // Загрузка CLAUDE.md
|
||||
thinking: { type: "adaptive" },
|
||||
}
|
||||
});
|
||||
|
||||
// Стриминг событий
|
||||
for await (const message of q) {
|
||||
// SDKMessage types: assistant, user, result, system, etc.
|
||||
console.log(message);
|
||||
}
|
||||
|
||||
// Query object methods:
|
||||
// q.interrupt(), q.close(), q.setModel(), q.mcpServerStatus()
|
||||
// q.initializationResult(), q.supportedModels(), q.supportedAgents()
|
||||
```
|
||||
|
||||
### Как спавнит Claude Code
|
||||
SDK **запускает Claude Code CLI как subprocess** — НЕ чисто API-библиотека. Каждый вызов `query()` спавнит новый процесс (~12 сек overhead).
|
||||
|
||||
Ключевые опции:
|
||||
- `spawnClaudeCodeProcess` — кастомная функция для запуска процесса (VMs, Docker, remote)
|
||||
- `pathToClaudeCodeExecutable` — путь к бинарнику Claude Code
|
||||
- `env` — переменные окружения для subprocess (полезно для Electron)
|
||||
- `executable` — runtime: `'node'`, `'bun'`, `'deno'`
|
||||
|
||||
### Session Management
|
||||
```typescript
|
||||
import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";
|
||||
|
||||
const sessions = await listSessions({ dir: "/path/to/project", limit: 10 });
|
||||
const messages = await getSessionMessages(sessionId, { limit: 20 });
|
||||
|
||||
// Resume session
|
||||
const q = query({
|
||||
prompt: "Continue working",
|
||||
options: { resume: sessionId }
|
||||
});
|
||||
```
|
||||
|
||||
### V2 Preview API (упрощённый интерфейс)
|
||||
Новый API с `send()` и `stream()` паттернами для multi-turn conversations.
|
||||
|
||||
### Субагенты
|
||||
Определяются программно через `agents` option в `AgentDefinition`:
|
||||
```typescript
|
||||
type AgentDefinition = {
|
||||
description: string;
|
||||
prompt: string;
|
||||
tools?: string[];
|
||||
disallowedTools?: string[];
|
||||
model?: "sonnet" | "opus" | "haiku" | "inherit";
|
||||
mcpServers?: AgentMcpServerSpec[];
|
||||
skills?: string[];
|
||||
maxTurns?: number;
|
||||
};
|
||||
```
|
||||
|
||||
### MCP-серверы
|
||||
Поддерживает in-process MCP серверы:
|
||||
```typescript
|
||||
import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
|
||||
import { z } from "zod";
|
||||
|
||||
const server = createSdkMcpServer({
|
||||
name: "my-server",
|
||||
tools: [
|
||||
tool("search", "Search the web", { query: z.string() }, async ({ query }) => {
|
||||
return { content: [{ type: "text", text: `Results for: ${query}` }] };
|
||||
})
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
### Ограничения лицензии
|
||||
- **Proprietary** — НЕ open-source
|
||||
- Запрещено использовать OAuth токены Claude Free/Pro/Max — нужен **API key**
|
||||
- Продукт должен иметь **собственный брендинг** (не Claude Code)
|
||||
- Anthropic собирает telemetry (usage, feedback, conversations)
|
||||
|
||||
### Оценка для нас
|
||||
- **Надёжность: 9/10** — Официальный SDK от Anthropic, активно развивается
|
||||
- **Уверенность: 9/10** — Отлично документирован, 691+ пользователь
|
||||
- **Риск:** Proprietary лицензия, ~12 сек overhead на query(), зависимость от CLI binary
|
||||
|
||||
---
|
||||
|
||||
## 3. @openai/codex-sdk (OFFICIAL)
|
||||
|
||||
**npm:** https://www.npmjs.com/package/@openai/codex-sdk
|
||||
**GitHub:** https://github.com/openai/codex/tree/main/sdk/typescript
|
||||
**Docs:** https://developers.openai.com/codex/sdk
|
||||
**Версия:** 0.116.0
|
||||
**Лицензия:** Apache-2.0
|
||||
**107 проектов** в npm registry используют этот пакет
|
||||
|
||||
### Что это
|
||||
Официальный TypeScript SDK от OpenAI для программного управления Codex CLI. Оборачивает CLI, обменивается JSONL-событиями через stdin/stdout.
|
||||
|
||||
### Ключевой API
|
||||
|
||||
```typescript
|
||||
import { Codex } from "@openai/codex-sdk";
|
||||
|
||||
// Инициализация
|
||||
const codex = new Codex({
|
||||
env: { PATH: "/usr/local/bin" }, // Полезно для Electron
|
||||
config: {
|
||||
show_raw_agent_reasoning: true,
|
||||
sandbox_workspace_write: { network_access: true }
|
||||
},
|
||||
baseUrl: "https://api.example.com" // Optional
|
||||
});
|
||||
|
||||
// Thread management
|
||||
const thread = codex.startThread({
|
||||
workingDirectory: "/path/to/project",
|
||||
skipGitRepoCheck: true // Для non-git environments
|
||||
});
|
||||
|
||||
// Buffered response
|
||||
const turn = await thread.run("Fix the test failure");
|
||||
console.log(turn.finalResponse);
|
||||
console.log(turn.items);
|
||||
|
||||
// Streaming response
|
||||
const { events } = await thread.runStreamed("Diagnose failures");
|
||||
for await (const event of events) {
|
||||
switch (event.type) {
|
||||
case "item.completed": console.log("Item:", event.item); break;
|
||||
case "turn.completed": console.log("Usage:", event.usage); break;
|
||||
}
|
||||
}
|
||||
|
||||
// Multi-turn conversations
|
||||
const turn1 = await thread.run("Diagnose issue");
|
||||
const turn2 = await thread.run("Implement the fix");
|
||||
|
||||
// Resume persisted thread
|
||||
const thread2 = codex.resumeThread(process.env.CODEX_THREAD_ID!);
|
||||
```
|
||||
|
||||
### Как спавнит Codex CLI
|
||||
SDK спавнит **Codex CLI** (Rust-based `@openai/codex`) как subprocess и обменивается JSONL-событиями через stdin/stdout.
|
||||
|
||||
- Работает **ТОЛЬКО** с Native (Rust) версией Codex
|
||||
- SDK инжектит `CODEX_API_KEY` поверх переданных env variables
|
||||
- `env` параметр — полный контроль над переменными (полезно для Electron)
|
||||
- `config` — JSON → dotted paths → TOML literals → `--config key=value` flags
|
||||
|
||||
### Session Persistence
|
||||
- Threads сохраняются в `~/.codex/sessions`
|
||||
- `resumeThread(id)` — восстановление потерянного Thread
|
||||
|
||||
### Structured Output
|
||||
```typescript
|
||||
const schema = {
|
||||
type: "object",
|
||||
properties: {
|
||||
summary: { type: "string" },
|
||||
status: { type: "string", enum: ["ok", "action_required"] }
|
||||
},
|
||||
required: ["summary", "status"],
|
||||
additionalProperties: false
|
||||
} as const;
|
||||
|
||||
const turn = await thread.run("Summarize status", { outputSchema: schema });
|
||||
```
|
||||
|
||||
### Multi-Agent Collaboration
|
||||
Поддержка spawn_agent, send_input, wait для координации между threads.
|
||||
|
||||
### Оценка для нас
|
||||
- **Надёжность: 9/10** — Официальный SDK от OpenAI, Apache-2.0
|
||||
- **Уверенность: 8/10** — Хорошо документирован, активно развивается
|
||||
- **Риск:** Только Rust-based Codex, зависимость от Git repo (опционально отключается)
|
||||
|
||||
---
|
||||
|
||||
## 4. @google/gemini-cli-sdk + @google/gemini-cli-core (OFFICIAL)
|
||||
|
||||
**npm (CLI):** https://www.npmjs.com/package/@google/gemini-cli
|
||||
**npm (Core):** https://www.npmjs.com/package/@google/gemini-cli-core
|
||||
**GitHub:** https://github.com/google-gemini/gemini-cli
|
||||
**Docs:** https://deepwiki.com/google-gemini/gemini-cli/5.9-sdk-and-programmatic-api
|
||||
**Версия:** SDK появился в v0.30.0 (2026-02-25)
|
||||
**Лицензия:** Apache-2.0
|
||||
**Звёзды:** ~99K
|
||||
|
||||
### Что это
|
||||
Официальный SDK от Google для программного запуска Gemini CLI. Монорепо-архитектура.
|
||||
|
||||
### Архитектура пакетов
|
||||
| Пакет | Роль |
|
||||
|-------|------|
|
||||
| `@google/gemini-cli-sdk` | Consumer-facing API |
|
||||
| `@google/gemini-cli-core` | Core orchestration, tools, API |
|
||||
| `@google/gemini-cli` | Terminal reference implementation |
|
||||
|
||||
### Ключевой API
|
||||
|
||||
```typescript
|
||||
import { LocalAgentExecutor, LocalAgentDefinition } from '@google/gemini-cli-core';
|
||||
|
||||
const agentDef: LocalAgentDefinition = {
|
||||
modelId: 'gemini-2.0-flash',
|
||||
systemPrompt: 'You are a helpful assistant',
|
||||
tools: ['read_file', 'write_file', 'run_shell_command'],
|
||||
maxTurns: 30,
|
||||
timeoutMs: 600000 // 10 min
|
||||
};
|
||||
|
||||
const executor = new LocalAgentExecutor(config, agentDef);
|
||||
|
||||
// Activity monitoring
|
||||
executor.onActivity((event) => {
|
||||
console.log('Agent activity:', event);
|
||||
});
|
||||
|
||||
const result = await executor.run({
|
||||
task: 'Analyze the codebase and suggest improvements'
|
||||
});
|
||||
|
||||
console.log('Termination mode:', result.terminateMode); // GOAL | MAX_TURNS | TIMEOUT
|
||||
console.log('Result:', result.output);
|
||||
```
|
||||
|
||||
### Как спавнит Gemini
|
||||
В отличие от Claude и Codex, SDK Gemini — **НЕ CLI wrapper**, а **нативная библиотека**. Использует core-логику напрямую:
|
||||
- `GeminiCliAgent` / `LocalAgentExecutor` — primary entity
|
||||
- Каждый агент получает свой `ToolRegistry` (изоляция)
|
||||
- `MessageBus` для async events (tool confirmations)
|
||||
- `Config` class для model selection и auth
|
||||
|
||||
### Tool Management
|
||||
- Built-in tools (file system, shell, web)
|
||||
- MCP server tools
|
||||
- Extension-provided tools
|
||||
- Tool confirmation через `TOOL_CONFIRMATION_REQUEST` event
|
||||
|
||||
### Agent Termination
|
||||
```typescript
|
||||
enum AgentTerminateMode {
|
||||
GOAL, // Успешно вызвал complete_task
|
||||
MAX_TURNS, // Достиг лимита (default 30)
|
||||
TIMEOUT // Превысил время (default 10 min)
|
||||
}
|
||||
```
|
||||
|
||||
### Headless Mode (альтернатива)
|
||||
```bash
|
||||
gemini --output-format json -p "Summarize project"
|
||||
gemini --output-format stream-json -p "Fix bug"
|
||||
```
|
||||
|
||||
### Зрелость
|
||||
- SDK появился в v0.30.0 (2026-02-25) — **очень свежий**
|
||||
- Feature request #15539 (Dec 2025) формально запрашивал SDK
|
||||
- API может меняться
|
||||
|
||||
### Оценка для нас
|
||||
- **Надёжность: 6/10** — Apache-2.0, открытый код, но SDK совсем новый
|
||||
- **Уверенность: 6/10** — API может меняться, документация неполная
|
||||
- **Преимущество:** Нативная библиотека (не CLI wrapper), лучшая производительность
|
||||
|
||||
---
|
||||
|
||||
## 5. Альтернативные Multi-Agent Frameworks
|
||||
|
||||
### jayminwest/overstory
|
||||
**GitHub:** https://github.com/jayminwest/overstory
|
||||
**Лицензия:** MIT
|
||||
|
||||
Pluggable `AgentRuntime` интерфейс с **11 адаптерами** (Claude Code, Codex, Gemini CLI, Aider, Goose, Amp и др). Агенты работают в изолированных git worktrees через tmux.
|
||||
|
||||
| Runtime | CLI | Guard Mechanism |
|
||||
|---------|-----|-----------------|
|
||||
| Claude Code | `claude` | `settings.local.json` hooks |
|
||||
| Codex | `codex` | OS-level sandbox |
|
||||
| Gemini | `gemini` | `--sandbox` flag |
|
||||
| Aider | `aider` | None (`--yes-always`) |
|
||||
| Goose | `goose` | Profile-based permissions |
|
||||
| + 6 others | ... | ... |
|
||||
|
||||
**Интересно, но:** Ориентирован на CLI/tmux workflow, не на Electron SDK.
|
||||
|
||||
### desplega-ai/agent-swarm
|
||||
**GitHub:** https://github.com/desplega-ai/agent-swarm
|
||||
**Docs:** https://docs.agent-swarm.dev/
|
||||
|
||||
Lead-worker паттерн с Docker-изоляцией. Поддерживает Claude Code, с планами на Codex/Gemini. SQLite + bun.
|
||||
|
||||
---
|
||||
|
||||
## 6. Сравнительная Таблица SDK
|
||||
|
||||
| | Claude Agent SDK | Codex SDK | Gemini CLI SDK |
|
||||
|---|---|---|---|
|
||||
| **Пакет** | `@anthropic-ai/claude-agent-sdk` | `@openai/codex-sdk` | `@google/gemini-cli-sdk` |
|
||||
| **Версия** | 0.2.83 | 0.116.0 | ~0.30.0+ |
|
||||
| **Лицензия** | Proprietary | Apache-2.0 | Apache-2.0 |
|
||||
| **Архитектура** | CLI subprocess | CLI subprocess (Rust) | Нативная библиотека |
|
||||
| **Стриминг** | AsyncGenerator<SDKMessage> | AsyncGenerator (events) | onActivity callback |
|
||||
| **Session Resume** | Да (sessionId) | Да (resumeThread) | Да (SessionContext) |
|
||||
| **Субагенты** | Да (agents option) | Да (spawn_agent) | Да (LocalAgentDefinition) |
|
||||
| **MCP серверы** | Да (in-process + external) | Нет (native tools only) | Да (ToolRegistry) |
|
||||
| **Custom Env** | Да (env option) | Да (env option) | Да (Config) |
|
||||
| **Custom Spawn** | Да (spawnClaudeCodeProcess) | Нет | Нет (нативная) |
|
||||
| **Structured Output** | Да (JSON Schema) | Да (JSON Schema + Zod) | Да (zod OutputConfig) |
|
||||
| **Node.js** | 18+ | 18+ | 18+ |
|
||||
| **Overhead** | ~12s per query() | Не измерен | Минимальный (нативная) |
|
||||
| **npm Users** | 691 | 107 | N/A (новый) |
|
||||
|
||||
---
|
||||
|
||||
## 7. Рекомендация для Claude Agent Teams UI
|
||||
|
||||
### Основной подход (Recommended)
|
||||
**Использовать официальные SDK каждого провайдера** вместо единого абстрактного слоя.
|
||||
|
||||
```
|
||||
src/main/services/agents/
|
||||
├── types.ts # Общие типы (AgentProcess, AgentEvent, AgentConfig)
|
||||
├── claude-adapter.ts # Обёртка над @anthropic-ai/claude-agent-sdk
|
||||
├── codex-adapter.ts # Обёртка над @openai/codex-sdk
|
||||
├── gemini-adapter.ts # Обёртка над @google/gemini-cli-sdk
|
||||
└── agent-registry.ts # Реестр доступных агентов
|
||||
```
|
||||
|
||||
Тонкий адаптерный слой (~100-150 LOC на адаптер) над каждым SDK, нормализующий:
|
||||
- Стриминг событий → единый `AgentEvent` формат
|
||||
- Session management → единый `AgentSession` интерфейс
|
||||
- Process lifecycle → start/stop/status
|
||||
|
||||
### Почему НЕ @swarmify/agents-mcp
|
||||
1. Closed-source — невозможно аудировать или форкнуть
|
||||
2. MCP-only интерфейс — мы уже имеем прямой доступ к процессам
|
||||
3. Filesystem-based communication — избыточный overhead для Electron
|
||||
|
||||
### Почему НЕ единый CLI spawn
|
||||
1. Все 3 провайдера выпустили свои SDK
|
||||
2. SDK дают типизированные события, session management, structured output
|
||||
3. Raw CLI spawn хрупок (парсинг stdout/ANSI codes)
|
||||
|
||||
### Почему НЕ overstory AgentRuntime
|
||||
1. Ориентирован на tmux/worktree workflow
|
||||
2. MIT лицензия хорошая, но архитектура не подходит для Electron
|
||||
3. 11 адаптеров — избыточно, нам нужны 3
|
||||
|
||||
### Порядок интеграции
|
||||
1. **Claude Code** (`@anthropic-ai/claude-agent-sdk`) — у нас уже есть, нужно мигрировать на SDK
|
||||
2. **Codex** (`@openai/codex-sdk`) — Apache-2.0, простой API, thread-based
|
||||
3. **Gemini** (`@google/gemini-cli-sdk`) — подождать стабилизации API (SDK очень свежий)
|
||||
|
||||
### Риски
|
||||
- **Claude SDK Proprietary лицензия** — нужно проверить совместимость с нашим MIT
|
||||
- **~12s overhead** Claude SDK per query — может потребоваться process pooling
|
||||
- **Gemini SDK API unstable** — может сломаться в любом релизе
|
||||
|
||||
---
|
||||
|
||||
## Источники
|
||||
|
||||
- [@swarmify/agents-mcp (npm)](https://www.npmjs.com/package/@swarmify/agents-mcp)
|
||||
- [Swarmify](https://swarmify.co/)
|
||||
- [@anthropic-ai/claude-agent-sdk (npm)](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
|
||||
- [Claude Agent SDK TypeScript (GitHub)](https://github.com/anthropics/claude-agent-sdk-typescript)
|
||||
- [Claude Agent SDK Reference](https://platform.claude.com/docs/en/agent-sdk/typescript)
|
||||
- [Run Claude Code programmatically](https://code.claude.com/docs/en/headless)
|
||||
- [@openai/codex-sdk (npm)](https://www.npmjs.com/package/@openai/codex-sdk)
|
||||
- [Codex SDK TypeScript (GitHub)](https://github.com/openai/codex/tree/main/sdk/typescript)
|
||||
- [Codex SDK Docs](https://developers.openai.com/codex/sdk)
|
||||
- [@google/gemini-cli (GitHub)](https://github.com/google-gemini/gemini-cli)
|
||||
- [Gemini CLI SDK (DeepWiki)](https://deepwiki.com/google-gemini/gemini-cli/5.9-sdk-and-programmatic-api)
|
||||
- [Gemini CLI SDK Feature Request #15539](https://github.com/google-gemini/gemini-cli/issues/15539)
|
||||
- [overstory (GitHub)](https://github.com/jayminwest/overstory)
|
||||
- [agent-swarm (GitHub)](https://github.com/desplega-ai/agent-swarm)
|
||||
334
docs/research/ai-maestro-deep-dive.md
Normal file
334
docs/research/ai-maestro-deep-dive.md
Normal file
|
|
@ -0,0 +1,334 @@
|
|||
# AI Maestro — Deep Dive Research
|
||||
|
||||
**Дата исследования:** 2026-03-25
|
||||
**Репозиторий:** [23blocks-OS/ai-maestro](https://github.com/23blocks-OS/ai-maestro)
|
||||
**Сайт:** [ai-maestro.23blocks.com](https://ai-maestro.23blocks.com/)
|
||||
**Автор:** Juan Pelaez / 23blocks
|
||||
**Лицензия:** MIT
|
||||
|
||||
---
|
||||
|
||||
## Общая информация
|
||||
|
||||
AI Maestro — open-source оркестратор AI-агентов с системой навыков (Skills System), дашбордом для управления агентами, собственным протоколом обмена сообщениями (AMP) и поддержкой мультимашинных mesh-сетей. Позиционирует себя как "The Future of Work: Humans + AI Agents".
|
||||
|
||||
### Метрики репозитория (на 25 марта 2026)
|
||||
|
||||
| Метрика | Значение |
|
||||
|---------|----------|
|
||||
| Stars | **557** |
|
||||
| Forks | 77 |
|
||||
| Open issues | 8 |
|
||||
| Коммитов | 890+ |
|
||||
| Контрибьюторов | ~5 (249 от jpelaez-23blocks, далее 9, 7, 4, 2) |
|
||||
| Создан | 10 октября 2025 |
|
||||
| Последний коммит | 25 марта 2026 (сегодня!) |
|
||||
| Последний релиз | v0.26.4 (25 марта 2026) |
|
||||
| Языки | TypeScript 89%, Shell 6.7%, JS 3.4%, CSS 0.5% |
|
||||
| Размер репо | ~312 MB |
|
||||
|
||||
**Вывод:** Проект активно развивается, коммиты ежедневные. Но по факту это проект одного человека (Juan Pelaez — 249 из ~270 коммитов от людей). 4 коммита от аккаунта `claude` — что ироничным образом подтверждает AI-происхождение кода.
|
||||
|
||||
---
|
||||
|
||||
## Origin Story
|
||||
|
||||
Цитата из описания проекта:
|
||||
> "I had 35 terminals and couldn't tell which was which."
|
||||
|
||||
Автор запускал 35+ AI-агентов одновременно и стал "human mailman" между ними — копировал контекст из одного терминала в другой. Сейчас утверждает, что запускает **80+ агентов** на нескольких компьютерах.
|
||||
|
||||
---
|
||||
|
||||
## Поддерживаемые агенты
|
||||
|
||||
### Заявленная совместимость:
|
||||
- **Claude Code** (основной)
|
||||
- **Aider**
|
||||
- **Cursor**
|
||||
- **GitHub Copilot CLI**
|
||||
- **OpenCode** (через Skills)
|
||||
- **Любой терминальный AI-агент**
|
||||
|
||||
### Как это работает:
|
||||
AI Maestro не является "мультипровайдерным" в том смысле, что он сам вызывает API разных LLM. Он работает на уровне **терминалов** — оборачивает tmux-сессии и предоставляет dashboard для управления ими. Любой инструмент, который работает в терминале, может быть "агентом" в AI Maestro.
|
||||
|
||||
**Важное уточнение:** AI Maestro НЕ абстрагирует LLM-провайдеров (как например LiteLLM). Он оркестрирует **процессы в терминале**. Claude Code внутри себя использует Anthropic API, Aider может использовать OpenAI/Anthropic/etc — но AI Maestro этого не контролирует.
|
||||
|
||||
---
|
||||
|
||||
## Архитектура
|
||||
|
||||
### Tech Stack
|
||||
|
||||
| Компонент | Технология | Роль |
|
||||
|-----------|-----------|------|
|
||||
| Frontend | **Next.js** | Web-дашборд |
|
||||
| Terminal | **xterm.js** | Эмуляция терминала в браузере |
|
||||
| Database | **CozoDB** | Граф-реляционная БД для памяти и Code Graph |
|
||||
| Code Analysis | **ts-morph** | Парсинг AST для Code Graph |
|
||||
| Process Mgmt | **tmux** | Мультиплексор терминалов |
|
||||
| Networking | **Peer Mesh** | P2P сеть между машинами |
|
||||
|
||||
### CozoDB — выбор базы данных
|
||||
|
||||
CozoDB (3 926 stars) — необычный выбор. Это транзакционная реляционно-графовая-векторная БД, использующая **Datalog** для запросов. Ключевые фичи:
|
||||
- Реляционная модель + графовые алгоритмы
|
||||
- Векторный поиск через HNSW-индексы
|
||||
- Встраиваемая (embedded)
|
||||
- Time-travel запросы
|
||||
|
||||
Это позволяет хранить и код-граф (структура кодобазы), и память агентов (conversation history), и выполнять векторный поиск — в одной БД.
|
||||
|
||||
### Три уровня "интеллекта"
|
||||
|
||||
1. **Memory** — Персистентная память через CozoDB. Агенты помнят прошлые решения и разговоры.
|
||||
2. **Code Graph** — Визуализация структуры кодобазы. ts-morph парсит AST, извлекает классы/функции/импорты, строит граф зависимостей. Delta-индексация (переиндексируются только изменённые файлы).
|
||||
3. **Documentation** — Автогенерируемая документация из кода, доступная агентам для поиска.
|
||||
|
||||
### Мультимашинная mesh-сеть
|
||||
|
||||
- Peer-to-peer топология: каждая машина — равноправный узел
|
||||
- Нет центрального сервера
|
||||
- Новая машина автоматически присоединяется к mesh
|
||||
- Все агенты со всех машин видны в одном дашборде
|
||||
- Поддержка remote access через Tailscale VPN
|
||||
|
||||
### Структура репозитория
|
||||
|
||||
```
|
||||
/app — Application logic
|
||||
/components — UI-компоненты
|
||||
/services — Backend-сервисы
|
||||
/plugin — Система плагинов для Claude Code
|
||||
/agent-container — Контейнеризированные агенты
|
||||
/infrastructure/terraform/aws-agent — AWS deployment
|
||||
/docs — Документация
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Messaging Protocol (AMP)
|
||||
|
||||
AMP — это **собственный протокол** 23blocks для межагентной коммуникации. Отдельный репозиторий: [agentmessaging/protocol](https://github.com/agentmessaging/protocol) (20 stars, Apache 2.0).
|
||||
|
||||
### Ключевые характеристики
|
||||
|
||||
| Параметр | Значение |
|
||||
|----------|----------|
|
||||
| Версия | 0.1.3-draft |
|
||||
| Лицензия | Apache 2.0 |
|
||||
| Безопасность | Ed25519 криптографические подписи |
|
||||
| Адресация | Email-подобная: `agent-name@tenant.provider` |
|
||||
| Спецификации | 11 документов |
|
||||
|
||||
### Формат сообщений
|
||||
|
||||
Конверт содержит:
|
||||
- `from` / `to` — адреса отправителя/получателя
|
||||
- `subject` — тема
|
||||
- `priority` — приоритет
|
||||
- `in_reply_to` — для тредов
|
||||
- `payload` — произвольный JSON
|
||||
- `signature` — Ed25519 подпись
|
||||
|
||||
Каноническая подпись: `from|to|subject|priority|in_reply_to|SHA256(payload)`
|
||||
|
||||
### Доставка сообщений
|
||||
|
||||
4 способа:
|
||||
1. **WebSocket** — реалтайм для подключённых агентов
|
||||
2. **REST API** — polling
|
||||
3. **Webhook** — HTTP POST push
|
||||
4. **Relay queue** — очередь для офлайн-агентов (TTL 7 дней по умолчанию)
|
||||
5. **Mesh** — локальная маршрутизация без интернета
|
||||
|
||||
### Провайдеры (федеративная модель)
|
||||
|
||||
- **AI Maestro** (self-hosted): `http://localhost:23000/api/v1` — работает
|
||||
- **crabmail.ai** — "coming soon"
|
||||
- **lolainbox.com** — "coming soon"
|
||||
|
||||
### Безопасность
|
||||
|
||||
- Ed25519 подписи предотвращают подмену отправителя
|
||||
- Trust-level аннотации для внешних сообщений
|
||||
- Key revocation с федеративным распространением
|
||||
- Защита от prompt injection (34 паттерна)
|
||||
- SSRF-превенция для webhook
|
||||
|
||||
### Критическая оценка AMP
|
||||
|
||||
**Плюсы:**
|
||||
- Формально специфицированный протокол (11 документов)
|
||||
- Криптографическая безопасность по умолчанию
|
||||
- Федеративная модель
|
||||
- Поддержка офлайн-агентов
|
||||
|
||||
**Минусы:**
|
||||
- Всего 20 stars на GitHub
|
||||
- Единственная реализация — сам AI Maestro
|
||||
- Федерация заявлена, но 2 из 3 провайдеров "coming soon"
|
||||
- По факту проприетарный протокол одного проекта, несмотря на Apache 2.0 лицензию
|
||||
- Не совместим с ACP (Agent Communication Protocol), MCP или другими стандартами
|
||||
|
||||
---
|
||||
|
||||
## Kanban Board
|
||||
|
||||
AI Maestro включает kanban-доску с:
|
||||
- **5 колонок** (статусы задач)
|
||||
- **Drag-and-drop** перемещение карточек
|
||||
- **Зависимости** между задачами
|
||||
- **Шаренные задачи** между агентами
|
||||
- Часть "War Room" — split-pane интерфейс для командных встреч
|
||||
|
||||
**Детали реализации Kanban ограничены** — в документации и на сайте нет скриншотов или подробного описания UX. Описание сводится к маркетинговым фразам: "full Kanban board with drag-and-drop, dependencies, and 5 status columns."
|
||||
|
||||
---
|
||||
|
||||
## Gateways — внешние интеграции
|
||||
|
||||
AI Maestro поддерживает "Gateways" для подключения к внешним сервисам:
|
||||
- **Slack**
|
||||
- **Discord**
|
||||
- **Email**
|
||||
- **WhatsApp**
|
||||
|
||||
Маршрутизация через синтаксис `@AIM:agent-name`. Заявлена защита от 34 паттернов prompt injection.
|
||||
|
||||
---
|
||||
|
||||
## Skills System
|
||||
|
||||
Система плагинов, устанавливаемых через `npx skills add`. Навыки автоматически триггерят:
|
||||
- Поиск по памяти
|
||||
- Запросы к Code Graph
|
||||
- Поиск документации
|
||||
|
||||
Совместим с 30+ агентами через "Agent Skills Standard".
|
||||
|
||||
### Agent Identity (AID)
|
||||
|
||||
Новая фича (v0.26.0, 24 марта 2026): агенты могут аутентифицироваться на OAuth 2.0 серверах используя Ed25519 identity. Без паролей, без API-ключей.
|
||||
|
||||
---
|
||||
|
||||
## Релизная активность
|
||||
|
||||
Последние 5 релизов (за 2 дня!):
|
||||
|
||||
| Версия | Дата | Описание |
|
||||
|--------|------|----------|
|
||||
| v0.26.4 | 25.03.2026 | AMP mesh routing fix |
|
||||
| v0.26.3 | 24.03.2026 | AID v0.2.0: независим от AMP |
|
||||
| v0.26.2 | 24.03.2026 | Dynamic discovery для verification |
|
||||
| v0.26.1 | 24.03.2026 | Переименование installer, auto-discover skills |
|
||||
| v0.26.0 | 24.03.2026 | Agent Identity (AID) интеграция |
|
||||
|
||||
5 релизов за 2 дня — это очень высокий темп. Может свидетельствовать как об активной разработке, так и о незрелости (частые фиксы только что выпущенных фич).
|
||||
|
||||
---
|
||||
|
||||
## Сравнение с нашим продуктом (Claude Agent Teams UI)
|
||||
|
||||
### Фундаментальные различия
|
||||
|
||||
| Аспект | AI Maestro | Claude Agent Teams UI |
|
||||
|--------|-----------|----------------------|
|
||||
| **Подход** | Терминальный оркестратор (tmux wrapper) | Нативная UI-надстройка над Claude Code Agent Teams |
|
||||
| **Агенты** | Любой терминальный AI | Claude Code (нативный Agent Teams API) |
|
||||
| **Мультипровайдер** | Да (на уровне терминалов) | Нет (Claude-only, но с multi-model: Opus/Sonnet/Haiku) |
|
||||
| **Kanban** | Есть (5 колонок, drag-drop, dependencies) | Есть (5 колонок, drag-drop, real-time) |
|
||||
| **Межагентная связь** | AMP protocol (собственный) | Нативный Claude Code inbox/task system |
|
||||
| **Code Review** | Не указан | Diff view с approve/reject/comment |
|
||||
| **Deep Analytics** | Memory + Code Graph + Docs | Session analysis, context tracking, token usage |
|
||||
| **Мультимашинность** | Peer mesh network | Нет (локальный) |
|
||||
| **UI** | Web (Next.js, браузер) | Desktop (Electron) |
|
||||
| **Процесс** | tmux sessions | stream-json CLI processes |
|
||||
|
||||
### Где AI Maestro сильнее
|
||||
|
||||
1. **Мультимашинность** — peer mesh сеть, агенты на разных компьютерах. У нас этого нет вообще.
|
||||
2. **Мультиагентность** — поддерживает Claude, Aider, Cursor, Copilot и любой терминальный инструмент. Мы только Claude Code.
|
||||
3. **Memory System** — CozoDB с графовыми запросами, векторным поиском, персистентной памятью. У нас аналитика сессий, но не полноценная "память" агентов.
|
||||
4. **Code Graph** — визуализация кодобазы через ts-morph + CozoDB. У нас такого нет.
|
||||
5. **External Gateways** — Slack, Discord, Email, WhatsApp. У нас встроенный MCP-сервер, но не gateway к мессенджерам.
|
||||
6. **Scale** — заявляет 80+ агентов. Наш продукт ориентирован на команды 3-8 агентов.
|
||||
|
||||
### Где наш продукт сильнее
|
||||
|
||||
1. **Нативная интеграция с Claude Code** — мы работаем с официальным Agent Teams API, а не просто оборачиваем терминалы. Наши агенты нативно общаются через inbox, шарят задачи, имеют structured task references.
|
||||
2. **Code Review** — полноценный diff view с accept/reject/comment, как в Cursor. У AI Maestro это не заявлено.
|
||||
3. **Kanban UX** — у нас real-time обновления, direct messaging на карточках, quick actions, structured task references с кросс-ссылками. AI Maestro заявляет Kanban, но без деталей UX.
|
||||
4. **Deep Session Analysis** — bash commands, reasoning, subprocesses breakdown, chunk timeline. AI Maestro показывает терминал, но не анализирует сессии.
|
||||
5. **Context Monitoring** — 6 категорий контекста (CLAUDE.md, tool outputs, thinking, team coordination), token usage by category. Уникальная фича.
|
||||
6. **Desktop App** — нативный Electron, не браузерная вкладка.
|
||||
7. **DM to agents** — прямые сообщения конкретному агенту с карточки задачи.
|
||||
8. **Zero-setup** — встроенная установка Claude Code и аутентификация. AI Maestro требует Node.js + tmux + установку.
|
||||
9. **Built-in Code Editor** — редактор файлов с Git support.
|
||||
10. **Post-compact context recovery** — восстановление инструкций после context compaction.
|
||||
|
||||
### Фундаментальная разница в философии
|
||||
|
||||
**AI Maestro** = "Terminal multiplexer on steroids" — оборачивает tmux, добавляет UI и межагентную коммуникацию. Агенты — это просто терминальные сессии. Протокол AMP — собственный, не стандартный.
|
||||
|
||||
**Claude Agent Teams UI** = "CTO dashboard for Claude teams" — нативная надстройка над Claude Code Agent Teams, с глубоким пониманием внутренних протоколов Claude (stream-json, inbox, tasks). Агенты — это структурированные сущности с ролями, задачами и коммуникацией.
|
||||
|
||||
---
|
||||
|
||||
## Рыночное позиционирование
|
||||
|
||||
AI Maestro позиционирован в [awesome-agent-orchestrators](https://github.com/andyrewlee/awesome-agent-orchestrators) в категории **"Parallel Agent Runners"** наряду с 38 другими инструментами.
|
||||
|
||||
### Конкуренты AI Maestro (не наши)
|
||||
|
||||
| Инструмент | Фокус | Stars |
|
||||
|-----------|-------|-------|
|
||||
| **Maestro** (RunMaestro) | Desktop orchestrator, Claude/Codex/OpenCode | 2000+ |
|
||||
| **Vibe Kanban** (BloopAI) | Kanban + Git worktree + MCP | N/A |
|
||||
| **Claw-Kanban** | Kanban + role-based auto-assignment | N/A |
|
||||
| **Agent Orchestrator** (ComposioHQ) | Plugin-based, tracker-agnostic | N/A |
|
||||
|
||||
RunMaestro (отдельный проект) — самый серьёзный конкурент для AI Maestro: 2000+ stars, desktop app, Group Chat, Auto Run, Mobile Remote Control.
|
||||
|
||||
---
|
||||
|
||||
## Оценки
|
||||
|
||||
### Надёжность решения: 6/10
|
||||
|
||||
- Проект одного разработчика (249 из ~270 коммитов)
|
||||
- Зависимость от CozoDB (нишевая БД)
|
||||
- 5 релизов за 2 дня — признак незрелости
|
||||
- AMP протокол — 20 stars, единственная реализация
|
||||
- Нет community reviews (Reddit/HN)
|
||||
- Нет automated tests (не видно в описании)
|
||||
|
||||
### Уровень угрозы для нашего продукта: 4/10
|
||||
|
||||
- Другая ниша: мультиагентный терминальный оркестратор vs нативный Claude Teams UI
|
||||
- Наша аудитория — пользователи Claude Code Agent Teams
|
||||
- Их аудитория — пользователи 3+ разных AI-инструментов
|
||||
- Пересечение небольшое: только если пользователь Claude Code решит добавить другие инструменты
|
||||
|
||||
### Что стоит позаимствовать
|
||||
|
||||
1. **Memory System** — персистентная память агентов между сессиями. Наши агенты теряют контекст при рестарте. CozoDB — overengineered для нас, но концепция ценная.
|
||||
2. **Code Graph** — визуализация кодобазы. Можно реализовать через tree-sitter или ts-morph + простое хранение.
|
||||
3. **Multi-machine** — даже не P2P mesh, но хотя бы возможность подключаться к remote Claude Code сессиям.
|
||||
4. **External integrations** — Slack/Discord уведомления о прогрессе задач.
|
||||
|
||||
---
|
||||
|
||||
## Источники
|
||||
|
||||
- [GitHub: 23blocks-OS/ai-maestro](https://github.com/23blocks-OS/ai-maestro)
|
||||
- [AI Maestro Website](https://ai-maestro.23blocks.com/)
|
||||
- [AMP Protocol: agentmessaging/protocol](https://github.com/agentmessaging/protocol)
|
||||
- [Agent Messaging Protocol Website](https://agentmessaging.org/)
|
||||
- [CozoDB](https://github.com/cozodb/cozo)
|
||||
- [Medium: "Your AI Agent Has Amnesia"](https://medium.com/23blocks/your-ai-agent-has-amnesia-heres-how-we-fixed-it-49980712f2e4) (paywall)
|
||||
- [Medium: "From 47 Terminal Windows to One Dashboard"](https://medium.com/23blocks/building-ai-maestro-from-47-terminal-windows-to-one-beautiful-dashboard-64cd25ff3b43) (paywall)
|
||||
- [awesome-agent-orchestrators](https://github.com/andyrewlee/awesome-agent-orchestrators)
|
||||
- [Maestro vs Superpowers vs ECC comparison gist](https://gist.github.com/jeffscottward/de77a769d9e25a8ccdc92b65291b1c34)
|
||||
523
docs/research/competitor-spawn-patterns.md
Normal file
523
docs/research/competitor-spawn-patterns.md
Normal file
|
|
@ -0,0 +1,523 @@
|
|||
# Competitor Agent Spawn Patterns Research
|
||||
|
||||
**Date**: 2026-03-25
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Все 4 конкурента построили собственные adapter-слои для spawning CLI-агентов. Ни один не использует готовую библиотеку. Паттерн единый: **интерфейс/trait + per-agent реализация + config-driven overrides**.
|
||||
|
||||
Самый зрелый и переиспользуемый паттерн у **vibe-kanban** (Rust trait `StandardCodingAgentExecutor` + `enum_dispatch` + ACP harness). У **Emdash** паттерн проще (per-service TypeScript классы + auto-discovery). **Dorothy** самый примитивный (node-pty напрямую). **Superset** закрыт ELv2 лицензией.
|
||||
|
||||
---
|
||||
|
||||
## 1. Vibe Kanban (BloopAI)
|
||||
|
||||
**Repo**: [github.com/BloopAI/vibe-kanban](https://github.com/BloopAI/vibe-kanban)
|
||||
**Язык**: Rust (backend) + TypeScript (frontend)
|
||||
**Лицензия**: Apache-2.0
|
||||
**Stars**: ~23K
|
||||
**Поддерживаемые агенты**: Claude Code, Codex, Gemini CLI, Copilot, Amp, Cursor, OpenCode, Droid, QwenCode, Qoder
|
||||
|
||||
### Архитектура
|
||||
|
||||
Самый архитектурно зрелый подход среди конкурентов.
|
||||
|
||||
**Ядро** — Rust trait + enum_dispatch:
|
||||
|
||||
```rust
|
||||
#[async_trait]
|
||||
#[enum_dispatch(CodingAgent)]
|
||||
pub trait StandardCodingAgentExecutor {
|
||||
async fn spawn(&self, current_dir: &Path, prompt: &str,
|
||||
env: &ExecutionEnv) -> Result<SpawnedChild, ExecutorError>;
|
||||
|
||||
async fn spawn_follow_up(&self, current_dir: &Path, prompt: &str,
|
||||
session_id: &str, reset_to_message_id: Option<&str>,
|
||||
env: &ExecutionEnv) -> Result<SpawnedChild, ExecutorError>;
|
||||
|
||||
async fn spawn_review(&self, current_dir: &Path, prompt: &str,
|
||||
session_id: Option<&str>, env: &ExecutionEnv)
|
||||
-> Result<SpawnedChild, ExecutorError>;
|
||||
}
|
||||
```
|
||||
|
||||
**Dispatch через enum** (compile-time, zero-cost):
|
||||
|
||||
```rust
|
||||
#[enum_dispatch]
|
||||
#[derive(Clone, Serialize, Deserialize, PartialEq, TS, Display)]
|
||||
pub enum CodingAgent {
|
||||
ClaudeCode, Amp, Gemini, Codex, Opencode,
|
||||
CursorAgent, QwenCode, Copilot, Droid, QaMock
|
||||
}
|
||||
```
|
||||
|
||||
### Структура файлов
|
||||
|
||||
```
|
||||
crates/executors/src/
|
||||
executors/
|
||||
mod.rs — trait + enum_dispatch + CodingAgent enum
|
||||
claude.rs — ClaudeCode executor
|
||||
gemini.rs — Gemini executor (через ACP harness)
|
||||
codex.rs — Codex executor
|
||||
amp.rs — Amp executor
|
||||
copilot.rs — GitHub Copilot
|
||||
cursor.rs — Cursor Agent
|
||||
opencode.rs — OpenCode
|
||||
droid.rs — Droid (factory.ai)
|
||||
qwen.rs — QwenCode
|
||||
qa_mock.rs — Mock для тестов
|
||||
utils.rs — Общие утилиты
|
||||
acp/ — ACP (Agent Communication Protocol) harness
|
||||
mod.rs
|
||||
client.rs — ACP client
|
||||
harness.rs — Spawn + session lifecycle
|
||||
session.rs — Session management
|
||||
normalize_logs.rs — Log normalization
|
||||
claude/ — Claude-specific subdirectory
|
||||
codex/ — Codex-specific subdirectory
|
||||
cursor/ — Cursor-specific subdirectory
|
||||
droid/ — Droid-specific subdirectory
|
||||
opencode/ — OpenCode-specific subdirectory
|
||||
command.rs — CommandBuilder (base cmd + params + overrides)
|
||||
env.rs — ExecutionEnv (env vars, repo context)
|
||||
executor_discovery.rs — Auto-discovery + caching
|
||||
mcp_config.rs — MCP server config per agent
|
||||
model_selector.rs — Model selection logic
|
||||
profile.rs — Agent profiles (DEFAULT, APPROVALS variants)
|
||||
approvals.rs — Permission/approval system
|
||||
stdout_dup.rs — Stdout duplication utilities
|
||||
lib.rs — Crate root
|
||||
```
|
||||
|
||||
### Как добавить нового агента (на примере Qoder PR #1759)
|
||||
|
||||
1. `crates/executors/src/executors/qoder.rs` — реализация trait
|
||||
2. `mod.rs` — добавить в `CodingAgent` enum
|
||||
3. `mcp_config.rs` — MCP Passthrough adapter
|
||||
4. `default_profiles.json` — профили (DEFAULT/APPROVALS)
|
||||
5. `generate_types.rs` — ts-rs type generation
|
||||
6. `shared/types.ts` — TypeScript enum (автогенерация)
|
||||
7. `shared/schemas/qoder.json` — JSON schema
|
||||
8. `docs/agents/qoder.mdx` — документация
|
||||
|
||||
### Пример: Gemini executor
|
||||
|
||||
```
|
||||
Base command: "npx -y @google/gemini-cli@0.29.3"
|
||||
Flags: --experimental-acp, --model <name>, --yolo (if auto mode)
|
||||
Harness: AcpAgentHarness — manages spawn, follow-up, session lifecycle
|
||||
Output: ACP protocol (structured agent communication)
|
||||
```
|
||||
|
||||
### Ключевые паттерны
|
||||
|
||||
- **CommandBuilder** (builder pattern): base cmd → params → overrides → platform-specific split → CommandParts
|
||||
- **ExecutionEnv**: HashMap<String, String> env vars + repo context, inject into tokio::Command
|
||||
- **CmdOverrides**: replace base cmd / append params / set env vars (per-profile)
|
||||
- **ACP Harness**: shared session/spawn logic for ACP-compatible agents (Gemini, Qoder, etc.)
|
||||
- **executor_discovery**: async discovery + caching по (path, command_key, agent_type)
|
||||
- **ts-rs**: Rust types → TypeScript types автогенерация
|
||||
|
||||
### Оценка
|
||||
|
||||
| Метрика | Значение |
|
||||
|---------|----------|
|
||||
| LOC adapter layer | ~2000-3000 (весь crate executors) |
|
||||
| Паттерн | trait + enum_dispatch + CommandBuilder |
|
||||
| Сложность добавления агента | ~150-200 LOC per agent |
|
||||
| Можно переиспользовать? | Нет (Rust, другой стек) |
|
||||
| Можно скопировать паттерн? | ДА — отличный reference |
|
||||
| Надёжность подхода | 9/10 |
|
||||
|
||||
---
|
||||
|
||||
## 2. Emdash (General Action)
|
||||
|
||||
**Repo**: [github.com/generalaction/emdash](https://github.com/generalaction/emdash)
|
||||
**Язык**: TypeScript (Electron)
|
||||
**Лицензия**: MIT
|
||||
**Stars**: ~6K
|
||||
**YC W26**
|
||||
**Поддерживаемые агенты**: 22+ (Claude Code, Codex, Gemini, Amp, Cursor, Copilot, Goose, Droid, Kiro, Qwen, OpenCode, Cline, Continue, Codebuff, Charm, Kilocode, Kimi, Autohand, Auggie, Rovo Dev, Mistral Vibe, Pi)
|
||||
|
||||
### Архитектура
|
||||
|
||||
Per-service TypeScript классы + auto-discovery. Самый близкий к нашему стеку.
|
||||
|
||||
**Ключевые файлы**:
|
||||
|
||||
```
|
||||
src/main/services/
|
||||
CodexService.ts — Manages Codex CLI child processes + log streaming
|
||||
CodexSessionService.ts — Session management for Codex
|
||||
ClaudeConfigService.ts — Claude-specific configuration
|
||||
ClaudeHookService.ts — Claude hooks integration
|
||||
AgentEventService.ts — Agent lifecycle events
|
||||
TaskLifecycleService.ts — Task state machine
|
||||
WorkspaceProviderService.ts — Provider workspace management
|
||||
TerminalConfigParser.ts — CLI terminal config detection
|
||||
ptyManager.ts — PTY session management (node-pty)
|
||||
ptyIpc.ts — PTY IPC communication
|
||||
ConnectionsService.ts — Connection management
|
||||
RepositoryManager.ts — Git repository management
|
||||
ProjectSettingsService.ts
|
||||
DatabaseService.ts — SQLite (drizzle)
|
||||
AutoUpdateService.ts
|
||||
__tests__/ — Tests
|
||||
fs/ — File system services
|
||||
git-core/ — Git operations
|
||||
mcp/ — MCP protocol
|
||||
skills/ — Skills system
|
||||
ssh/ — SSH remote development
|
||||
```
|
||||
|
||||
### Как добавить провайдера (из документации)
|
||||
|
||||
1. Include: provider name, CLI invocation command, auth notes, setup steps
|
||||
2. Team wires up provider selection in UI and adds to Integrations matrix
|
||||
3. Providers auto-detected when CLI is in PATH
|
||||
|
||||
### Spawn-паттерн
|
||||
|
||||
- `node:child_process.spawn()` для CLI агентов
|
||||
- `node-pty` для terminal sessions
|
||||
- Per-service классы (CodexService, ClaudeConfigService)
|
||||
- `TerminalConfigParser` для auto-detection CLI в PATH
|
||||
- `AgentEventService` для lifecycle events (running/waiting/completed/error)
|
||||
- SQLite (drizzle ORM) для персистенции
|
||||
|
||||
### Ключевые особенности
|
||||
|
||||
- **Auto-discovery**: провайдеры детектятся автоматически по наличию CLI в PATH
|
||||
- **Native deps**: sqlite3, node-pty, keytar (rebuilt per Electron version)
|
||||
- **Worktree isolation**: каждый агент в своём git worktree
|
||||
- **SSH remote**: агенты могут работать на удалённых машинах через SSH/SFTP
|
||||
- **Best-of-N**: запуск нескольких агентов на одну задачу, выбор лучшего
|
||||
|
||||
### Оценка
|
||||
|
||||
| Метрика | Значение |
|
||||
|---------|----------|
|
||||
| LOC adapter layer | ~1500-2000 (services + pty) |
|
||||
| Паттерн | Per-service classes + auto-discovery |
|
||||
| Сложность добавления агента | Средняя (новый service file) |
|
||||
| Можно переиспользовать код? | Потенциально ДА (MIT, TypeScript, Electron) |
|
||||
| Можно скопировать паттерн? | ДА — очень близко к нашему стеку |
|
||||
| Надёжность подхода | 7/10 (less structured than vibe-kanban) |
|
||||
|
||||
---
|
||||
|
||||
## 3. Dorothy (Charlie85270)
|
||||
|
||||
**Repo**: [github.com/Charlie85270/Dorothy](https://github.com/Charlie85270/Dorothy)
|
||||
**Язык**: TypeScript (Electron + Next.js)
|
||||
**Лицензия**: MIT
|
||||
**Stars**: ~3K
|
||||
**Поддерживаемые агенты**: Claude Code (primarily), расширяется
|
||||
|
||||
### Архитектура
|
||||
|
||||
Самый простой подход — node-pty напрямую, без абстракции adapter layer.
|
||||
|
||||
```
|
||||
electron/
|
||||
agent-manager.ts — Agent lifecycle & parallel execution (node-pty)
|
||||
pty-manager.ts — Terminal session multiplexing
|
||||
window-manager.ts — Window management
|
||||
services/
|
||||
telegram-bot
|
||||
slack-bot
|
||||
kanban-automation
|
||||
mcp-server-launcher
|
||||
api-server
|
||||
mcp-orchestrator/ — Super Agent MCP server
|
||||
mcp-kanban/ — Kanban automation MCP
|
||||
```
|
||||
|
||||
### Spawn-паттерн
|
||||
|
||||
- `node-pty` — каждый агент в изолированной PTY-сессии
|
||||
- Статус определяется парсингом stdout patterns (running/waiting/completed/error)
|
||||
- N параллельных агентов с отдельными проектами
|
||||
- Super Agent (мета-агент) контролирует другие через MCP tools
|
||||
- Cron-based scheduling для повторяющихся задач
|
||||
- Skills system для extensibility
|
||||
|
||||
### Ключевые особенности
|
||||
|
||||
- **Нет абстракции агентов**: привязан к Claude Code, нет interface для разных CLI
|
||||
- **Kanban**: задачи → колонки → automatic agent assignment по skills
|
||||
- **Automations**: GitHub PR/issue polling → agent spawning
|
||||
- **Remote control**: Telegram/Slack bot для управления
|
||||
|
||||
### Оценка
|
||||
|
||||
| Метрика | Значение |
|
||||
|---------|----------|
|
||||
| LOC adapter layer | ~500-800 (agent-manager + pty-manager) |
|
||||
| Паттерн | Direct node-pty, no abstraction |
|
||||
| Сложность добавления агента | Высокая (нет interface) |
|
||||
| Можно переиспользовать код? | Да (MIT), но мало что полезного |
|
||||
| Можно скопировать паттерн? | НЕТ — слишком примитивный |
|
||||
| Надёжность подхода | 5/10 |
|
||||
|
||||
---
|
||||
|
||||
## 4. Superset (superset-sh)
|
||||
|
||||
**Repo**: [github.com/superset-sh/superset](https://github.com/superset-sh/superset)
|
||||
**Язык**: TypeScript (Electron, monorepo Turborepo + Bun)
|
||||
**Лицензия**: Elastic License 2.0 (ELv2) — НЕ open-source!
|
||||
**Stars**: ~7.8K
|
||||
**Поддерживаемые агенты**: Claude Code, Codex, Aider, Copilot, Cursor Agent, Gemini CLI, OpenCode + custom
|
||||
|
||||
### Архитектура
|
||||
|
||||
Monorepo с 6 apps. Multi-process Electron с 5 entry points:
|
||||
|
||||
```
|
||||
apps/desktop/src/
|
||||
main/
|
||||
index.ts — Main app entry
|
||||
terminal-host/
|
||||
index.ts — Persistent daemon for terminal sessions
|
||||
pty-subprocess.ts — PTY handler (node-pty)
|
||||
git-task-worker.ts — Worker thread for Git ops
|
||||
host-service/
|
||||
index.ts — Local HTTP server
|
||||
|
||||
packages/
|
||||
@superset/trpc — tRPC routers
|
||||
@superset/ui — Shared React components
|
||||
@superset/local-db — SQLite (Drizzle)
|
||||
@superset/db — PostgreSQL (Neon, cloud sync)
|
||||
```
|
||||
|
||||
### Spawn-паттерн
|
||||
|
||||
- **Terminal Host daemon**: persistent subprocess managing terminal sessions
|
||||
- **PTY subprocess**: node-pty forked on-demand
|
||||
- **Git Worker**: heavy git ops offloaded to worker_threads
|
||||
- **tRPC over Electron IPC**: renderer ↔ main communication
|
||||
- **Worktree isolation**: каждая задача в своём git worktree с уникальным branch
|
||||
- **Port allocation**: SUPERSET_PORT_BASE + 20 портов на workspace
|
||||
|
||||
### Ключевые особенности
|
||||
|
||||
- **Multi-process**: 5 entry points, daemon-based terminal management
|
||||
- **Dual DB**: local SQLite + cloud PostgreSQL (ElectricSQL sync)
|
||||
- **Better Auth**: OAuth deep links для десктопа
|
||||
- **.superset/config.json**: workspace setup/teardown scripts
|
||||
|
||||
### Оценка
|
||||
|
||||
| Метрика | Значение |
|
||||
|---------|----------|
|
||||
| LOC adapter layer | Неизвестно (code not browsable) |
|
||||
| Паттерн | Multi-process + terminal-host daemon |
|
||||
| Сложность добавления агента | Неизвестно |
|
||||
| Можно переиспользовать код? | НЕТ (Elastic License 2.0) |
|
||||
| Можно скопировать паттерн? | Частично (terminal-host daemon idea) |
|
||||
| Надёжность подхода | 8/10 (production, enterprise users) |
|
||||
|
||||
---
|
||||
|
||||
## CLI Agent Programmatic Spawn Reference
|
||||
|
||||
### Claude Code
|
||||
|
||||
```bash
|
||||
claude --input-format stream-json --output-format stream-json --verbose
|
||||
```
|
||||
|
||||
- **Bidirectional NDJSON protocol** over stdin/stdout
|
||||
- Message types: `initialize`, `user`, `control_response`
|
||||
- `--verbose` REQUIRED with stream-json
|
||||
- `--print` mode for one-shot (no multi-turn)
|
||||
- Session hooks do NOT run in `--print` mode
|
||||
- Official docs: [incomplete](https://github.com/anthropics/claude-code/issues/24594) — community reverse-engineered
|
||||
- VS Code extension spawns: `claude --output-format stream-json --verbose --input-format stream-json --max-thinking-tokens 0 --model default --permission-prompt-tool stdio`
|
||||
|
||||
### Codex (OpenAI)
|
||||
|
||||
```bash
|
||||
codex exec --json "prompt"
|
||||
```
|
||||
|
||||
- **JSONL output** (one event per line)
|
||||
- Event types: `thread.started`, `turn.started`, `turn.completed`, `turn.failed`, `item.*`
|
||||
- Item types: agent_message, reasoning, command_exec, file_change, mcp_tool_call
|
||||
- `--output-schema` for structured final output
|
||||
- `codex exec resume --json` for session resumption
|
||||
- **App-server mode**: `codex app-server` — stateful JSON-RPC over stdio
|
||||
- Auth: `CODEX_API_KEY` env var for non-interactive
|
||||
- Schema BREAKING CHANGES between versions (item_type → type, assistant_message → agent_message)
|
||||
|
||||
### Gemini CLI (Google)
|
||||
|
||||
```bash
|
||||
gemini -p "prompt" --output-format json
|
||||
# or streaming:
|
||||
gemini -p "prompt" --output-format stream-json
|
||||
```
|
||||
|
||||
- `-p` flag for non-interactive headless mode
|
||||
- `--output-format json` — full response + stats
|
||||
- `--output-format stream-json` — real-time JSONL events
|
||||
- `--yolo` — auto-approve all tool calls
|
||||
- `--experimental-acp` — Agent Communication Protocol (used by vibe-kanban)
|
||||
- **Known issues**: response field may contain markdown-wrapped JSON instead of clean JSON
|
||||
- Stdin piping supported for additional context
|
||||
|
||||
### Amp (Sourcegraph)
|
||||
|
||||
```bash
|
||||
amp --execute "prompt" --stream-json
|
||||
```
|
||||
|
||||
- `--stream-json` — JSONL output (REQUIRES `--execute`)
|
||||
- `--stream-json-input` — JSONL input via stdin (REQUIRES `--stream-json`)
|
||||
- `--stream-json-thinking` — includes thinking blocks (extends schema)
|
||||
- **Claude Code compatible format** (mostly)
|
||||
- Multi-turn: `amp threads continue [thread-id]` + `--stream-json-input`
|
||||
- Auth: `AMP_API_KEY` env var for CI/CD
|
||||
- Elixir SDK exists as reference: spawns CLI + parses stream-json
|
||||
|
||||
### Goose (Block)
|
||||
|
||||
```bash
|
||||
goose run -t "prompt"
|
||||
# or from file:
|
||||
goose run -i instructions.md
|
||||
```
|
||||
|
||||
- `goose run` — non-interactive one-shot mode
|
||||
- `--output-format json` — [feature request #4419, marked Done](https://github.com/block/goose/issues/4419)
|
||||
- `--format json` — for session/recipe listing
|
||||
- Max 10 concurrent subagents (hard-coded)
|
||||
- 5 min default timeout, 25 max turns
|
||||
- `GOOSE_SUBAGENT_MAX_TURNS` env override
|
||||
|
||||
---
|
||||
|
||||
## Сравнительная таблица
|
||||
|
||||
| | Vibe Kanban | Emdash | Dorothy | Superset |
|
||||
|---|---|---|---|---|
|
||||
| **Язык** | Rust | TypeScript | TypeScript | TypeScript |
|
||||
| **Лицензия** | Apache-2.0 | MIT | MIT | ELv2 |
|
||||
| **Используют готовую библиотеку?** | Нет | Нет | Нет | Нет |
|
||||
| **Паттерн** | trait + enum_dispatch | Per-service classes | Direct node-pty | Multi-process daemon |
|
||||
| **Абстракция агентов** | `StandardCodingAgentExecutor` trait | Per-service (CodexService, etc.) | Нет | Terminal-host daemon |
|
||||
| **Количество агентов** | 10+ | 22+ | 1 (Claude) | 8+ |
|
||||
| **Сложность добавления** | ~150-200 LOC | ~300-500 LOC | Hard (no interface) | Unknown |
|
||||
| **LOC adapter layer** | ~2000-3000 | ~1500-2000 | ~500-800 | Unknown |
|
||||
| **Auto-discovery** | Да (executor_discovery) | Да (PATH detection) | Нет | Unknown |
|
||||
| **MCP support** | Passthrough per agent | Да | MCP servers | Да |
|
||||
| **ACP protocol** | Да (shared harness) | Нет | Нет | Нет |
|
||||
| **Type generation** | ts-rs (Rust → TS) | N/A | N/A | N/A |
|
||||
| **Isolation** | Git worktrees | Git worktrees | Separate projects | Git worktrees |
|
||||
| **Можно reuse код?** | Нет (Rust) | Да (MIT, TS) | Да (MIT) | Нет (ELv2) |
|
||||
|
||||
---
|
||||
|
||||
## Выводы и рекомендации для Claude Agent Teams UI
|
||||
|
||||
### 1. Какой паттерн взять за основу?
|
||||
|
||||
**Рекомендация: гибрид vibe-kanban + emdash подходов**
|
||||
|
||||
От vibe-kanban взять:
|
||||
- **Interface (trait) + per-agent implementation** — TypeScript interface вместо Rust trait
|
||||
- **CommandBuilder pattern** — построение команды через builder с overrides
|
||||
- **ExecutionEnv** — управление env vars + repo context
|
||||
- **Profile system** — DEFAULT/APPROVALS варианты per agent
|
||||
- **enum-dispatch idea** — в TS реализуется через discriminated union + factory
|
||||
|
||||
От Emdash взять:
|
||||
- **Auto-discovery** — детекция CLI в PATH
|
||||
- **Per-service approach** — но с общим interface
|
||||
- **node-pty integration** — для terminal sessions
|
||||
|
||||
### 2. Предлагаемый TypeScript interface
|
||||
|
||||
```typescript
|
||||
interface AgentExecutor {
|
||||
readonly agentType: AgentType; // discriminated union tag
|
||||
|
||||
spawn(params: SpawnParams): Promise<SpawnedAgent>;
|
||||
spawnFollowUp(params: FollowUpParams): Promise<SpawnedAgent>;
|
||||
spawnReview?(params: ReviewParams): Promise<SpawnedAgent>;
|
||||
|
||||
discover(): Promise<DiscoveredOptions>;
|
||||
isAvailable(): Promise<boolean>;
|
||||
|
||||
normalizeOutput(raw: string): string;
|
||||
parseEvent(line: string): AgentEvent | null;
|
||||
}
|
||||
|
||||
interface SpawnParams {
|
||||
workDir: string;
|
||||
prompt: string;
|
||||
env: ExecutionEnv;
|
||||
model?: string;
|
||||
approvalMode: 'auto' | 'supervised';
|
||||
mcpConfig?: string;
|
||||
}
|
||||
|
||||
interface SpawnedAgent {
|
||||
process: ChildProcess;
|
||||
sessionId: string;
|
||||
stdout: ReadableStream<AgentEvent>;
|
||||
stderr: ReadableStream<string>;
|
||||
kill(): Promise<void>;
|
||||
sendMessage(msg: string): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Что НЕ стоит делать
|
||||
|
||||
- **Не использовать node-pty напрямую** (как Dorothy) — нет абстракции, сложно масштабировать
|
||||
- **Не строить на Rust** (как vibe-kanban) — у нас TypeScript стек, overhead не оправдан
|
||||
- **Не копировать multi-process daemon** (как Superset) — over-engineering для нашего случая
|
||||
- **Не привязываться к одному протоколу** — у каждого CLI свой формат (stream-json, --json, --stream-json)
|
||||
|
||||
### 4. Приоритет агентов для поддержки
|
||||
|
||||
| Приоритет | Агент | Протокол | Сложность |
|
||||
|-----------|-------|----------|-----------|
|
||||
| P0 | Claude Code | stream-json bidirectional | Уже есть |
|
||||
| P1 | Codex | `exec --json` JSONL | Средняя |
|
||||
| P1 | Gemini CLI | `--output-format stream-json` | Средняя |
|
||||
| P2 | Amp | `--execute --stream-json` | Средняя (CC-compatible) |
|
||||
| P2 | Goose | `run -t` + `--output-format json` | Средняя |
|
||||
| P3 | OpenCode | TBD | Исследовать |
|
||||
| P3 | Cursor Agent | TBD | Исследовать |
|
||||
|
||||
---
|
||||
|
||||
## Источники
|
||||
|
||||
- [Vibe Kanban (BloopAI)](https://github.com/BloopAI/vibe-kanban) — Apache-2.0, 23K stars
|
||||
- [Vibe Kanban AGENTS.md](https://github.com/BloopAI/vibe-kanban/blob/main/AGENTS.md)
|
||||
- [Vibe Kanban executors crate](https://github.com/BloopAI/vibe-kanban/tree/main/crates/executors/src/executors)
|
||||
- [Vibe Kanban PR #1759 — Qoder executor pattern](https://github.com/BloopAI/vibe-kanban/pull/1759)
|
||||
- [Emdash (General Action)](https://github.com/generalaction/emdash) — MIT, 6K stars
|
||||
- [Emdash Providers Documentation](https://docs.emdash.sh/providers)
|
||||
- [Emdash AGENTS.md](https://github.com/generalaction/emdash/blob/main/AGENTS.md)
|
||||
- [Dorothy (Charlie85270)](https://github.com/Charlie85270/Dorothy) — MIT, 3K stars
|
||||
- [Superset (superset-sh)](https://github.com/superset-sh/superset) — ELv2, 7.8K stars
|
||||
- [Superset DeepWiki Architecture](https://deepwiki.com/superset-sh/superset/1.1-architecture-overview)
|
||||
- [Codex CLI Reference](https://developers.openai.com/codex/cli/reference)
|
||||
- [Codex Non-Interactive Mode](https://developers.openai.com/codex/noninteractive)
|
||||
- [Codex JSON output issues](https://github.com/openai/codex/issues/2288)
|
||||
- [Gemini CLI Headless Mode](https://google-gemini.github.io/gemini-cli/docs/cli/headless.html)
|
||||
- [Gemini CLI JSON issues](https://github.com/google-gemini/gemini-cli/issues/9009)
|
||||
- [Amp Streaming JSON](https://ampcode.com/news/streaming-json)
|
||||
- [Amp CLI Manual](https://ampcode.com/manual)
|
||||
- [Goose CLI Commands](https://block.github.io/goose/docs/guides/goose-cli-commands/)
|
||||
- [Goose JSON output request #4419](https://github.com/block/goose/issues/4419)
|
||||
- [Claude Code stream-json docs gap #24594](https://github.com/anthropics/claude-code/issues/24594)
|
||||
- [Claude Code Automation Skill (LobeHub)](https://lobehub.com/it/skills/coreyja-dotfiles-claude-code-automation)
|
||||
639
docs/research/inter-agent-communication-standards.md
Normal file
639
docs/research/inter-agent-communication-standards.md
Normal file
|
|
@ -0,0 +1,639 @@
|
|||
# Inter-Agent Communication Standards: How Different AI Agents Can Talk to Each Other
|
||||
|
||||
**Date:** 2026-03-25
|
||||
**Status:** Research complete
|
||||
**Goal:** Determine the best way for AI agents (Claude, Codex, Gemini) to communicate with each other
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Executive Summary](#executive-summary)
|
||||
2. [Protocol Landscape Overview](#protocol-landscape-overview)
|
||||
3. [A2A (Agent-to-Agent Protocol)](#1-a2a--agent-to-agent-protocol)
|
||||
4. [ACP (Agent Communication Protocol) by IBM/BeeAI](#2-acp--agent-communication-protocol-by-ibmbeeai)
|
||||
5. [Agent Client Protocol (ACP) by Zed](#3-agent-client-protocol-acp-by-zed)
|
||||
6. [MCP for Inter-Agent Communication](#4-mcp-for-inter-agent-communication)
|
||||
7. [Agent Network Protocol (ANP)](#5-agent-network-protocol-anp)
|
||||
8. [MCP Agent Mail](#6-mcp-agent-mail)
|
||||
9. [File-Based Inbox Pattern](#7-file-based-inbox-pattern-claude-code-agent-teams)
|
||||
10. [SQLite/Redis Message Bus](#8-sqliteredis-message-bus)
|
||||
11. [Cross-Provider Orchestration Tools](#9-cross-provider-orchestration-tools)
|
||||
12. [Comparison Matrix](#comparison-matrix)
|
||||
13. [Recommendations for Electron App](#recommendations-for-our-electron-app)
|
||||
14. [Sources](#sources)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
На март 2026 года НЕ существует единого универсального стандарта для межагентной коммуникации между разными провайдерами (Claude, Codex, Gemini). Однако экосистема быстро консолидируется вокруг нескольких протоколов:
|
||||
|
||||
| Уровень | Протокол | Назначение |
|
||||
|---------|----------|------------|
|
||||
| Tool access | **MCP** (Anthropic) | Агент <-> инструменты/данные |
|
||||
| Agent-to-Agent | **A2A** (Google/Linux Foundation) | Агент <-> агент (сетевой) |
|
||||
| Editor-to-Agent | **ACP** (Zed) | Редактор <-> CLI-агент |
|
||||
| Local coordination | **File-based inbox** (Claude Code) | Агент <-> агент (локальный) |
|
||||
| Local coordination | **MCP Agent Mail** | Агент <-> агент (MCP + SQLite + Git) |
|
||||
|
||||
**Ключевые выводы:**
|
||||
|
||||
1. **A2A** -- самый зрелый протокол для agent-to-agent, но он HTTP/server-based и плохо подходит для чисто локального Electron-приложения без встроенного сервера.
|
||||
2. **File-based inbox** (как в Claude Code Agent Teams) -- самый простой и проверенный паттерн для локальной коммуникации. Работает в Electron без проблем.
|
||||
3. **MCP Agent Mail** -- наиболее feature-rich локальное решение (идентичности, mailboxes, file leases, searchable threads), но Python-based.
|
||||
4. **MCP** сам по себе эволюционирует в сторону inter-agent communication (AWS, Microsoft активно контрибьютят).
|
||||
5. **OpenCode** -- единственный инструмент, который реально запускает Claude + Codex + Gemini в одной команде через unified inbox pattern.
|
||||
|
||||
---
|
||||
|
||||
## Protocol Landscape Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Agent Network Protocol │
|
||||
│ (ANP - open internet, P2P, DID) │
|
||||
└──────────────────┬──────────────────┘
|
||||
│
|
||||
┌──────────────────┴──────────────────┐
|
||||
│ Agent-to-Agent Protocol (A2A) │
|
||||
│ (Google/LF, HTTP, JSON-RPC, tasks) │
|
||||
└──────────────────┬──────────────────┘
|
||||
│
|
||||
┌────────────────────────────┼────────────────────────────┐
|
||||
│ │ │
|
||||
┌─────────┴─────────┐ ┌─────────────┴─────────────┐ ┌─────────┴─────────┐
|
||||
│ MCP (Anthropic) │ │ Agent Client Protocol │ │ File-based inbox │
|
||||
│ Agent <-> Tools │ │ (Zed, editor <-> agent) │ │ (Claude Code local)│
|
||||
└───────────────────┘ └───────────────────────────┘ └───────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. A2A -- Agent-to-Agent Protocol
|
||||
|
||||
**Создатель:** Google, теперь под Linux Foundation
|
||||
**Статус:** v0.3.0 (Draft v1.0), 150+ организаций-участников
|
||||
**GitHub:** [a2aproject/A2A](https://github.com/a2aproject/A2A) -- 500+ stars (JS SDK)
|
||||
|
||||
### Как работает
|
||||
|
||||
1. Каждый агент публикует **Agent Card** (JSON) по адресу `/.well-known/agent.json` -- имя, навыки, endpoint, auth
|
||||
2. Клиент-агент отправляет **задачу** серверу-агенту через JSON-RPC 2.0 over HTTPS
|
||||
3. Задача проходит жизненный цикл: `submitted` -> `working` -> `completed`/`canceled`
|
||||
4. Поддерживается streaming через SSE (Server-Sent Events)
|
||||
5. Результат задачи -- **артефакт** (текст, изображения, файлы)
|
||||
|
||||
### TypeScript SDK
|
||||
|
||||
```bash
|
||||
npm install @a2a-js/sdk
|
||||
# Для Express-интеграции:
|
||||
npm install express
|
||||
```
|
||||
|
||||
Пакет: [`@a2a-js/sdk`](https://www.npmjs.com/package/@a2a-js/sdk) v0.3.10
|
||||
- 88 зависимых проектов на npm
|
||||
- Поддержка Express, gRPC, in-memory task store
|
||||
- Полные типы TypeScript
|
||||
|
||||
**Минимальный сервер (Express):**
|
||||
```typescript
|
||||
import { AgentCard, AgentExecutor, DefaultRequestHandler, InMemoryTaskStore } from '@a2a-js/sdk';
|
||||
import { agentCardHandler, jsonRpcHandler } from '@a2a-js/sdk/server/express';
|
||||
import express from 'express';
|
||||
|
||||
const card: AgentCard = {
|
||||
name: 'MyAgent',
|
||||
description: 'Example agent',
|
||||
protocolVersion: '0.3.0',
|
||||
url: 'http://localhost:4000/a2a/jsonrpc',
|
||||
skills: [{ id: 'hello', name: 'Hello', description: 'Says hello' }],
|
||||
capabilities: {},
|
||||
defaultInputModes: ['text/plain'],
|
||||
defaultOutputModes: ['text/plain'],
|
||||
};
|
||||
|
||||
class MyExecutor implements AgentExecutor {
|
||||
async execute(context) {
|
||||
context.eventBus.publish({ type: 'message', message: { role: 'agent', parts: [{ type: 'text', text: 'Hello!' }] } });
|
||||
context.eventBus.finished();
|
||||
}
|
||||
}
|
||||
|
||||
const handler = new DefaultRequestHandler(card, new InMemoryTaskStore(), new MyExecutor());
|
||||
const app = express();
|
||||
app.get('/a2a/agent-card', agentCardHandler(handler));
|
||||
app.post('/a2a/jsonrpc', jsonRpcHandler(handler));
|
||||
app.listen(4000);
|
||||
```
|
||||
|
||||
### Оценка для Electron
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Зрелость протокола | 8/10 -- v0.3, Linux Foundation, 150+ организаций |
|
||||
| TypeScript поддержка | 9/10 -- официальный SDK, полные типы |
|
||||
| Electron-совместимость | 5/10 -- требует HTTP-сервер, придётся встраивать Express в main process |
|
||||
| Локальная работа | 4/10 -- спроектирован для сетевого взаимодействия, localhost возможен но overhead |
|
||||
| Кросс-провайдер | 9/10 -- протокол-агностик по дизайну |
|
||||
|
||||
### Вердикт
|
||||
|
||||
A2A -- правильный протокол для **распределённых сетевых** мультиагентных систем. Для локального Electron-приложения это overkill, но если планируется поддержка **удалённых агентов** в будущем -- имеет смысл держать в архитектуре.
|
||||
|
||||
---
|
||||
|
||||
## 2. ACP -- Agent Communication Protocol by IBM/BeeAI
|
||||
|
||||
**Создатель:** IBM Research / BeeAI
|
||||
**Статус:** MERGED WITH A2A под Linux Foundation. Активная разработка свёрнута.
|
||||
**GitHub:** [i-am-bee/acp](https://github.com/i-am-bee/acp)
|
||||
|
||||
### Как работает
|
||||
|
||||
- REST-native (не JSON-RPC как A2A) -- стандартные HTTP-конвенции
|
||||
- Не требует SDK -- можно использовать через curl/Postman
|
||||
- Async по умолчанию (fire-and-forget с taskId, poll/subscribe для прогресса)
|
||||
- Sync также поддерживается (простой HTTP POST)
|
||||
- Offline discovery -- метаданные агента встроены в пакет распространения
|
||||
|
||||
### TypeScript SDK
|
||||
|
||||
```bash
|
||||
npm install @anthropic-ai/beeai-framework # TypeScript starter
|
||||
```
|
||||
|
||||
BeeAI Framework предоставляет TypeScript-клиент для ACP.
|
||||
|
||||
### Оценка для Electron
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Зрелость | 3/10 -- merged into A2A, активная разработка прекращена |
|
||||
| TypeScript | 6/10 -- клиентский SDK есть |
|
||||
| Electron | 5/10 -- REST-based, аналогично A2A |
|
||||
| Рекомендация | НЕ использовать, мигрировать на A2A |
|
||||
|
||||
### Вердикт
|
||||
|
||||
**Устаревший.** Объединён с A2A. Использовать только если уже есть код на ACP -- в таком случае мигрировать на A2A.
|
||||
|
||||
---
|
||||
|
||||
## 3. Agent Client Protocol (ACP) by Zed
|
||||
|
||||
**ВНИМАНИЕ:** Это ДРУГОЙ протокол с тем же акронимом ACP. Не путать с IBM ACP.
|
||||
|
||||
**Создатель:** Zed Industries
|
||||
**Статус:** Активный, ACP Registry запущен (2026)
|
||||
**GitHub:** [agentclientprotocol/agent-client-protocol](https://github.com/agentclientprotocol/agent-client-protocol)
|
||||
**Сайт:** [agentclientprotocol.com](https://agentclientprotocol.com/)
|
||||
|
||||
### Как работает
|
||||
|
||||
- Стандартизирует связь **редактор <-> CLI-агент** (аналогично LSP для языковых серверов)
|
||||
- JSON-RPC over stdio (локальные агенты как subprocess)
|
||||
- JSON-RPC over HTTP/WebSocket (удалённые агенты)
|
||||
- Переиспользует JSON-представления из MCP где возможно
|
||||
- Добавляет UX-специфичные типы (diff display, file edits)
|
||||
|
||||
### Поддерживаемые агенты и редакторы
|
||||
|
||||
**Агенты:**
|
||||
- Claude Code (через Zed SDK adapter)
|
||||
- Codex CLI
|
||||
- Gemini CLI (reference implementation)
|
||||
- OpenCode
|
||||
- Goose (Block/Square)
|
||||
- GitHub Copilot CLI
|
||||
- Kiro CLI
|
||||
|
||||
**Редакторы:**
|
||||
- Zed (нативная поддержка)
|
||||
- JetBrains IDEs (скоро)
|
||||
- Neovim (CodeCompanion, avante.nvim)
|
||||
- Emacs (agent-shell)
|
||||
- VS Code (расширение ACP Client)
|
||||
|
||||
### Оценка для Electron
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Зрелость | 7/10 -- активный, registry, множество интеграций |
|
||||
| TypeScript | 7/10 -- JSON-RPC, спецификация есть |
|
||||
| Electron | 8/10 -- stdio-based отлично работает с child_process |
|
||||
| Назначение | Editor <-> Agent, НЕ agent <-> agent |
|
||||
|
||||
### Вердикт
|
||||
|
||||
ACP (Zed) -- **идеален для связи нашего Electron UI с CLI-агентами**. Но это протокол editor<->agent, не agent<->agent. Для межагентной коммуникации нужен другой протокол поверх.
|
||||
|
||||
---
|
||||
|
||||
## 4. MCP для Inter-Agent Communication
|
||||
|
||||
**Создатель:** Anthropic
|
||||
**Статус:** Активно развивается в сторону agent-to-agent (2026 roadmap)
|
||||
|
||||
### Как это работает для inter-agent
|
||||
|
||||
MCP изначально создан для tool integration, но его архитектура позволяет agent-to-agent:
|
||||
|
||||
1. **Агент A запускает MCP-сервер**, объявляя свои capabilities как tools
|
||||
2. **Агент B подключается как MCP-клиент** и вызывает tools агента A
|
||||
3. Streaming через SSE для real-time обновлений
|
||||
4. Session resumability для долгих задач
|
||||
5. Multi-turn interactions через elicitation
|
||||
|
||||
### Паттерн "Agent as MCP Server"
|
||||
|
||||
```
|
||||
Agent A (MCP Client) ──────► Agent B (MCP Server)
|
||||
│ │
|
||||
│ call tool "analyze" │
|
||||
├─────────────────────────►│
|
||||
│ │ runs analysis
|
||||
│ streaming results │
|
||||
│◄─────────────────────────┤
|
||||
```
|
||||
|
||||
### Кто продвигает
|
||||
|
||||
- **AWS** активно контрибьютит в inter-agent MCP, работает с LangGraph, CrewAI, LlamaIndex
|
||||
- **Microsoft** показала, что A2A-коммуникацию можно построить на MCP
|
||||
- **Block (Square)** -- 1000+ инженеров используют MCP-координацию (Goose)
|
||||
|
||||
### TypeScript SDK
|
||||
|
||||
```bash
|
||||
npm install @modelcontextprotocol/sdk zod
|
||||
```
|
||||
|
||||
Официальный SDK: [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
|
||||
|
||||
### Оценка для Electron
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Зрелость для inter-agent | 5/10 -- изначально не для этого, но быстро эволюционирует |
|
||||
| TypeScript | 10/10 -- официальный SDK, отличная поддержка |
|
||||
| Electron | 9/10 -- stdio transport, уже используется в нашем приложении |
|
||||
| Кросс-провайдер | 8/10 -- все провайдеры поддерживают MCP |
|
||||
|
||||
### Вердикт
|
||||
|
||||
MCP -- **наиболее практичный выбор** для нашего Electron-приложения. Мы уже используем MCP. Паттерн "agent as MCP server" позволяет любому агенту объявить tools/resources, а другой агент подключается как клиент. Roadmap 2026 явно включает agent-to-agent capabilities.
|
||||
|
||||
---
|
||||
|
||||
## 5. Agent Network Protocol (ANP)
|
||||
|
||||
**Создатель:** Open-source community
|
||||
**Статус:** Draft, white paper на arXiv
|
||||
**GitHub:** [agent-network-protocol/AgentNetworkProtocol](https://github.com/agent-network-protocol/AgentNetworkProtocol)
|
||||
**Сайт:** [agent-network-protocol.com](https://agent-network-protocol.com/)
|
||||
|
||||
### Как работает
|
||||
|
||||
Трёхуровневая архитектура:
|
||||
1. **Identity & Encrypted Communication** -- W3C DID (Decentralized Identifiers), end-to-end encryption
|
||||
2. **Meta-Protocol Layer** -- агенты САМИ договариваются о протоколе коммуникации
|
||||
3. **Application Protocol** -- JSON-LD для описания capabilities
|
||||
|
||||
Позиционирование: "HTTP для агентного интернета". Peer-to-peer, без центральных серверов.
|
||||
|
||||
### Оценка для Electron
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Зрелость | 2/10 -- draft, ранняя стадия |
|
||||
| TypeScript | 2/10 -- нет SDK |
|
||||
| Electron | 3/10 -- P2P, сложная интеграция |
|
||||
| Рекомендация | Следить, НЕ использовать сейчас |
|
||||
|
||||
### Вердикт
|
||||
|
||||
ANP -- интересная vision для **открытого агентного интернета** (peer-to-peer discovery, DID), но слишком рано для продакшна. Может стать актуален через 1-2 года.
|
||||
|
||||
---
|
||||
|
||||
## 6. MCP Agent Mail
|
||||
|
||||
**Создатель:** Jeff Emanuel (Dicklesworthstone)
|
||||
**Статус:** Активный, первый open-source agent coordination tool (октябрь 2025)
|
||||
**GitHub:** [Dicklesworthstone/mcp_agent_mail](https://github.com/Dicklesworthstone/mcp_agent_mail)
|
||||
**Rust version:** [Dicklesworthstone/mcp_agent_mail_rust](https://github.com/Dicklesworthstone/mcp_agent_mail_rust)
|
||||
**Сайт:** [mcpagentmail.com](https://mcpagentmail.com/)
|
||||
|
||||
### Как работает
|
||||
|
||||
- MCP-сервер, предоставляющий **34 tool** для координации агентов
|
||||
- Каждый агент получает **идентичность** (memorable name: GreenCastle, BlueLake)
|
||||
- **Inbox/Outbox** -- асинхронные mailbox для сообщений
|
||||
- **Advisory File Reservations** -- агенты объявляют file leases (exclusive/shared) на globs
|
||||
- **Searchable threads** -- FTS через SQLite
|
||||
- **Git backing** -- все сообщения и артефакты в Git для аудита
|
||||
- SQLite для индексации, Git как source of truth
|
||||
|
||||
### Cross-Provider Support
|
||||
|
||||
Работает с Claude Code, Codex, Gemini CLI, Factory Droid -- любой MCP-совместимый клиент.
|
||||
|
||||
### Технические детали
|
||||
|
||||
- Python-based сервер (FastMCP)
|
||||
- Rust-реимплементация доступна (127.0.0.1:8765, TUI console)
|
||||
- Не npm-пакет, установка через bash-скрипт
|
||||
- Local-first, no cloud dependencies
|
||||
|
||||
### Оценка для Electron
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Зрелость | 7/10 -- production-used, хорошо документирован |
|
||||
| TypeScript | 3/10 -- Python/Rust server, TS клиент через MCP SDK |
|
||||
| Electron | 6/10 -- можно запустить как sidecar process, но Python/Rust зависимость |
|
||||
| Feature-richness | 9/10 -- identities, mailboxes, file leases, FTS, Git audit |
|
||||
|
||||
### Вердикт
|
||||
|
||||
Самое feature-rich решение для координации агентов. **Проблема**: Python/Rust dependency. Для нашего Electron-приложения можно:
|
||||
- Запустить как sidecar process
|
||||
- Или реализовать ключевые идеи (mailbox, file leases) на TypeScript нативно
|
||||
|
||||
---
|
||||
|
||||
## 7. File-Based Inbox Pattern (Claude Code Agent Teams)
|
||||
|
||||
**Создатель:** Anthropic (Claude Code)
|
||||
**Статус:** Production, Claude Code v2.1.32+
|
||||
|
||||
### Как работает
|
||||
|
||||
Наиболее простой и проверенный паттерн:
|
||||
|
||||
```
|
||||
~/.claude/teams/{team-name}/
|
||||
├── config.json # member registry
|
||||
└── inboxes/
|
||||
├── lead.json # lead's inbox
|
||||
├── frontend-dev.json # teammate inbox
|
||||
└── backend-dev.json # teammate inbox
|
||||
```
|
||||
|
||||
1. Отправитель **appends** JSON-объект в inbox-файл получателя
|
||||
2. Получатель **polls** свой inbox-файл между turns
|
||||
3. Формат сообщения: `{ from, text, timestamp, read }`
|
||||
4. Broadcast = запись одного сообщения во ВСЕ inbox-файлы
|
||||
|
||||
### Особенности
|
||||
|
||||
- Zero dependencies -- только fs
|
||||
- Inspectable -- `cat` любой inbox файл в реальном времени
|
||||
- File I/O масштабируется для 3-5 агентов
|
||||
- Нет real-time delivery -- получатель увидит сообщение только после текущего turn
|
||||
- Ownership: каждый агент читает только СВОЙ inbox
|
||||
|
||||
### Inbox/Outbox Pattern (улучшенный)
|
||||
|
||||
```
|
||||
agent-a/
|
||||
├── inbox.json # входящие сообщения
|
||||
├── outbox.json # исходящие (для аудита)
|
||||
└── current-task.json
|
||||
|
||||
agent-b/
|
||||
├── inbox.json
|
||||
├── outbox.json
|
||||
└── current-task.json
|
||||
```
|
||||
|
||||
Правила координации:
|
||||
- Агент пишет ТОЛЬКО в свой outbox и чужие inbox
|
||||
- Агент читает ТОЛЬКО свой inbox и current-task
|
||||
- Boot Sequence: при старте читать inbox.json, resume из current-task.json
|
||||
|
||||
### Оценка для Electron
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Зрелость | 9/10 -- production в Claude Code |
|
||||
| TypeScript | 10/10 -- чистый fs/path, тривиальная реализация |
|
||||
| Electron | 10/10 -- идеально, никаких зависимостей |
|
||||
| Масштабируемость | 5/10 -- до ~10 агентов, потом I/O bottleneck |
|
||||
| Feature-richness | 4/10 -- только messaging, нет identities/leases/FTS |
|
||||
|
||||
### Вердикт
|
||||
|
||||
**Лучший выбор для немедленного использования.** Мы УЖЕ используем этот паттерн в нашем приложении. Для межагентной коммуникации между разными провайдерами -- это самый простой путь: агенты любого провайдера пишут/читают JSON-файлы.
|
||||
|
||||
---
|
||||
|
||||
## 8. SQLite/Redis Message Bus
|
||||
|
||||
### SQLite Message Bus
|
||||
|
||||
Паттерн из сообщества: Flask + SQLite message bus для ~16 агентов.
|
||||
|
||||
**Особенности:**
|
||||
- HTTP API для отправки/получения сообщений
|
||||
- Broadcast messaging (omit "to" field)
|
||||
- Reply chains через `reply_to`
|
||||
- Priority levels (normal/high/urgent)
|
||||
- Read receipts
|
||||
- `journal_mode=WAL` для конкурентного доступа
|
||||
- Auto-archiving старых сообщений
|
||||
|
||||
### Redis Approaches
|
||||
|
||||
| Подход | Плюсы | Минусы |
|
||||
|--------|-------|--------|
|
||||
| Redis Pub/Sub | Real-time, low latency | Ephemeral -- сообщения теряются |
|
||||
| Redis Streams | Persistent, consumer groups | Требует Redis server |
|
||||
| redis-bus | Autodiscovery, cache | Legacy (Python 2.7) |
|
||||
|
||||
### Оценка для Electron
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| SQLite bus | 7/10 -- хорошо для Electron (better-sqlite3 уже есть) |
|
||||
| Redis | 3/10 -- требует отдельный server, overkill для desktop |
|
||||
| TypeScript | 8/10 (SQLite) / 6/10 (Redis) |
|
||||
| Масштабируемость | 8/10 (SQLite WAL) / 9/10 (Redis) |
|
||||
|
||||
### Вердикт
|
||||
|
||||
**SQLite message bus** -- отличный апгрейд с file-based inbox, если нужна persistence, FTS, priority, read receipts. `better-sqlite3` уже хорошо работает в Electron. Redis -- overkill для локального desktop-приложения.
|
||||
|
||||
---
|
||||
|
||||
## 9. Cross-Provider Orchestration Tools
|
||||
|
||||
### OpenCode -- True Multi-Model Agent Teams
|
||||
|
||||
OpenCode -- единственный инструмент, который **реально запускает Claude + Codex + Gemini в одной команде**.
|
||||
|
||||
**Архитектура:**
|
||||
- Event-driven inbox (не polling как Claude Code)
|
||||
- Per-agent JSONL файлы: `{ id, from, text, timestamp, read }`
|
||||
- Session injection для delivery (не file polling)
|
||||
- Shared task list с claiming
|
||||
|
||||
**Отличия от Claude Code:**
|
||||
- Multi-model support (Claude, GPT, Gemini в одной команде)
|
||||
- Peer-to-peer messaging (не только через lead)
|
||||
- Event-driven (не polling)
|
||||
- Append-only JSONL (не JSON array)
|
||||
- Всё in-process (locks в памяти)
|
||||
|
||||
### sub-agents-skills
|
||||
|
||||
GitHub: [shinpr/sub-agents-skills](https://github.com/shinpr/sub-agents-skills)
|
||||
|
||||
Позволяет использовать Codex, Claude Code, Gemini CLI как sub-agents из любого parent session. Cross-LLM делегация задач.
|
||||
|
||||
### ZenFlow (Zencoder)
|
||||
|
||||
Structured handoffs между Claude и Gemini с quality gates. Не open-source.
|
||||
|
||||
### CC Switch
|
||||
|
||||
Unified management: proxy Claude/Codex/Gemini, unified MCP panel, markdown editor с cross-app sync для CLAUDE.md/AGENTS.md/GEMINI.md.
|
||||
|
||||
---
|
||||
|
||||
## Comparison Matrix
|
||||
|
||||
| | A2A | MCP (inter-agent) | ACP (Zed) | File Inbox | MCP Agent Mail | SQLite Bus |
|
||||
|---|---|---|---|---|---|---|
|
||||
| **Зрелость** | 8/10 | 5/10 | 7/10 | 9/10 | 7/10 | 6/10 |
|
||||
| **TS SDK** | 9/10 | 10/10 | 7/10 | 10/10 | 3/10 | 8/10 |
|
||||
| **Electron-ready** | 5/10 | 9/10 | 8/10 | 10/10 | 6/10 | 7/10 |
|
||||
| **Cross-provider** | 9/10 | 8/10 | 9/10 | 10/10 | 9/10 | 10/10 |
|
||||
| **No server needed** | No | Partial | Yes (stdio) | Yes | No | Yes |
|
||||
| **Real-time** | Yes (SSE) | Yes (SSE) | Yes | No (polling) | No | Polling |
|
||||
| **Persistence** | Optional | No | No | File-based | Git+SQLite | SQLite |
|
||||
| **File coordination** | No | No | No | No | Yes (leases) | No |
|
||||
| **Identity system** | Agent Cards | No | No | No | Yes | No |
|
||||
| **Сложность** | High | Medium | Medium | Very Low | High | Low |
|
||||
|
||||
---
|
||||
|
||||
## Recommendations for Our Electron App
|
||||
|
||||
### Немедленно (Phase 1) -- File-Based Inbox
|
||||
|
||||
**Надёжность: 9/10 | Уверенность: 10/10**
|
||||
|
||||
Мы уже используем file-based inbox для Claude Code Agent Teams. Этот же паттерн работает для ЛЮБОГО CLI-агента (Codex, Gemini CLI). Агенту не нужно знать протокол -- он просто читает/пишет JSON-файлы.
|
||||
|
||||
```
|
||||
~/.claude_teams/{team-name}/inboxes/
|
||||
├── claude-lead.json
|
||||
├── codex-worker.json
|
||||
├── gemini-researcher.json
|
||||
```
|
||||
|
||||
**Что нужно для cross-provider:**
|
||||
1. Unified inbox format (уже есть: `{ from, text, timestamp, read }`)
|
||||
2. Agent spawner для каждого CLI (Claude Code, Codex CLI, Gemini CLI)
|
||||
3. Каждый агент получает system prompt с инструкцией читать/писать inbox files
|
||||
4. Task board (shared JSON files с flock)
|
||||
|
||||
### Среднесрочно (Phase 2) -- SQLite Message Bus
|
||||
|
||||
**Надёжность: 8/10 | Уверенность: 8/10**
|
||||
|
||||
Upgrade с file-based на SQLite для:
|
||||
- Persistence и searchable history
|
||||
- Priority levels и read receipts
|
||||
- Better concurrency (WAL mode)
|
||||
- FTS для поиска по сообщениям
|
||||
|
||||
`better-sqlite3` уже отлично работает в Electron.
|
||||
|
||||
### Долгосрочно (Phase 3) -- MCP-Based Inter-Agent
|
||||
|
||||
**Надёжность: 6/10 | Уверенность: 6/10**
|
||||
|
||||
Когда MCP roadmap 2026 реализует agent-to-agent capabilities:
|
||||
- Каждый агент запускает MCP-сервер со своими capabilities
|
||||
- Другие агенты подключаются как MCP-клиенты
|
||||
- Streaming, session management, tool negotiation из коробки
|
||||
- @modelcontextprotocol/sdk уже в нашем стеке
|
||||
|
||||
### Если потребуются удалённые агенты (Phase 4) -- A2A
|
||||
|
||||
**Надёжность: 7/10 | Уверенность: 5/10**
|
||||
|
||||
A2A имеет смысл только если:
|
||||
- Нужна коммуникация с агентами на других машинах
|
||||
- Интеграция с enterprise-системами (Salesforce, SAP агенты)
|
||||
- Cloud-hosted агенты
|
||||
|
||||
В этом случае: встроить Express-сервер в Electron main process, использовать @a2a-js/sdk.
|
||||
|
||||
### Конкретный ответ на вопрос: "Как заставить Claude поговорить с Codex?"
|
||||
|
||||
**Самый простой работающий способ прямо сейчас:**
|
||||
|
||||
1. Spawn Claude Code CLI как child_process
|
||||
2. Spawn Codex CLI как child_process
|
||||
3. Оба читают/пишут в общую директорию inbox-файлов
|
||||
4. System prompt для каждого включает инструкцию: "To communicate with other agents, write to their inbox file at {path}"
|
||||
5. Наше Electron-приложение выступает оркестратором: следит за inbox-файлами, доставляет сообщения через stdin, обновляет UI
|
||||
|
||||
Это РОВНО то, что делает Claude Code Agent Teams, и ровно то, что OpenCode расширил для multi-provider.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
### Протоколы и спецификации
|
||||
- [A2A Protocol Official Site](https://a2a-protocol.org/latest/)
|
||||
- [A2A GitHub Repository](https://github.com/a2aproject/A2A)
|
||||
- [A2A JS SDK](https://github.com/a2aproject/a2a-js) -- [@a2a-js/sdk npm](https://www.npmjs.com/package/@a2a-js/sdk)
|
||||
- [Agent Client Protocol (Zed)](https://agentclientprotocol.com/) -- [GitHub](https://github.com/agentclientprotocol/agent-client-protocol)
|
||||
- [ACP Registry](https://zed.dev/blog/acp-registry)
|
||||
- [Agent Communication Protocol (IBM/BeeAI)](https://github.com/i-am-bee/acp) -- [IBM Research](https://research.ibm.com/projects/agent-communication-protocol)
|
||||
- [Agent Network Protocol](https://agent-network-protocol.com/) -- [GitHub](https://github.com/agent-network-protocol/AgentNetworkProtocol)
|
||||
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
|
||||
|
||||
### Анонсы и статьи
|
||||
- [Google: Announcing A2A](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/)
|
||||
- [Google Cloud: A2A Getting an Upgrade](https://cloud.google.com/blog/products/ai-machine-learning/agent2agent-protocol-is-getting-an-upgrade)
|
||||
- [Linux Foundation: A2A Project Launch](https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents)
|
||||
- [IBM: What is A2A?](https://www.ibm.com/think/topics/agent2agent-protocol)
|
||||
- [IBM: What is ACP?](https://www.ibm.com/think/topics/agent-communication-protocol)
|
||||
- [AWS: Inter-Agent Communication on MCP](https://aws.amazon.com/blogs/opensource/open-protocols-for-agent-interoperability-part-1-inter-agent-communication-on-mcp/)
|
||||
- [Microsoft: A2A on MCP](https://developer.microsoft.com/blog/can-you-build-agent2agent-communication-on-mcp-yes)
|
||||
- [Auth0: MCP vs A2A](https://auth0.com/blog/mcp-vs-a2a/)
|
||||
- [Developer's Guide to AI Agent Protocols](https://developers.googleblog.com/developers-guide-to-ai-agent-protocols/)
|
||||
|
||||
### Claude Code Agent Teams
|
||||
- [Official Docs](https://code.claude.com/docs/en/agent-teams)
|
||||
- [Reverse-Engineering Claude Code Agent Teams](https://dev.to/nwyin/reverse-engineering-claude-code-agent-teams-architecture-and-protocol-o49)
|
||||
- [How They Work Under the Hood](https://www.claudecodecamp.com/p/claude-code-agent-teams-how-they-work-under-the-hood)
|
||||
|
||||
### Cross-Provider Orchestration
|
||||
- [OpenCode Agent Teams](https://dev.to/uenyioha/porting-claude-codes-agent-teams-to-opencode-4hol)
|
||||
- [sub-agents-skills](https://github.com/shinpr/sub-agents-skills)
|
||||
- [ZenFlow Multi-Agent Orchestration](https://docs.zencoder.ai/user-guides/guides/multi-agent-orchestration-in-zenflow)
|
||||
- [Zed: External Agents](https://zed.dev/docs/ai/external-agents)
|
||||
|
||||
### Agent Coordination
|
||||
- [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) -- [Site](https://mcpagentmail.com/)
|
||||
- [MCP Agent Mail Rust](https://github.com/Dicklesworthstone/mcp_agent_mail_rust)
|
||||
- [Inbox/Outbox Pattern](https://earezki.com/ai-news/2026-03-09-the-inbox-outbox-pattern-how-ai-agents-coordinate-without-stepping-on-each-other/)
|
||||
- [Multi-Agent Communication Patterns](https://dev.to/aureus_c_b3ba7f87cc34d74d49/multi-agent-communication-patterns-that-actually-work-50kp)
|
||||
- [Agent Message Bus (SQLite)](https://dev.to/linou518/agent-message-bus-communication-infrastructure-for-16-ai-agents-18af)
|
||||
|
||||
### Google ADK
|
||||
- [ADK with A2A](https://google.github.io/adk-docs/a2a/)
|
||||
- [ADK Docs](https://google.github.io/adk-docs/agents/models/google-gemini/)
|
||||
|
||||
### Surveys
|
||||
- [Survey of Agent Interoperability Protocols (arXiv)](https://arxiv.org/abs/2505.02279)
|
||||
- [Top 5 Open Protocols for Multi-Agent AI Systems](https://onereach.ai/blog/power-of-multi-agent-ai-open-protocols/)
|
||||
- [10 Modern AI Agent Protocols](https://www.ssonetwork.com/intelligent-automation/columns/ai-agent-protocols-10-modern-standards-shaping-the-agentic-era)
|
||||
689
docs/research/minimal-adapter-design.md
Normal file
689
docs/research/minimal-adapter-design.md
Normal file
|
|
@ -0,0 +1,689 @@
|
|||
# Minimal CLI Agent Adapter Design
|
||||
|
||||
**Дата**: 2026-03-25
|
||||
**Статус**: Research / Design proposal
|
||||
|
||||
## Цель
|
||||
|
||||
Определить МИНИМАЛЬНО достаточный адаптер для запуска нескольких CLI-агентов (Claude, Codex, Gemini, Goose, OpenCode) из нашего Electron-приложения. Без over-engineering, без "велосипедов".
|
||||
|
||||
---
|
||||
|
||||
## 1. Что мы уже имеем
|
||||
|
||||
### childProcess.ts (221 LOC)
|
||||
Уже содержит два ключевых примитива:
|
||||
- **`spawnCli(binaryPath, args, options)`** — spawn с Windows EINVAL fallback
|
||||
- **`execCli(binaryPath, args, options)`** — exec для одноразовых команд
|
||||
- **`killProcessTree(child, signal)`** — kill с Windows taskkill fallback
|
||||
- **`CLI_ENV_DEFAULTS`** — env-переменные для Claude (CLAUDE_HOOK_JUDGE_MODE)
|
||||
|
||||
### TeamProvisioningService.ts (~8000+ LOC)
|
||||
Монстр, который делает ВСЁ:
|
||||
- Spawn через `spawnCli()`
|
||||
- Конструирование args (`--input-format stream-json`, `--output-format stream-json`, `--mcp-config`, `--verbose`, etc.)
|
||||
- Парсинг stream-json stdout (newline-delimited JSON)
|
||||
- Stdin messaging (SDKUserMessage format)
|
||||
- MCP config merge (через TeamMcpConfigBuilder)
|
||||
- Filesystem monitoring, stall detection, auth retry, etc.
|
||||
|
||||
### ScheduledTaskExecutor.ts (~200 LOC)
|
||||
Отдельный, более чистый spawn-path для scheduled tasks:
|
||||
- Тоже `spawnCli()` + `--output-format stream-json`
|
||||
- Парсинг stdout для summary extraction
|
||||
- Простой lifecycle: spawn -> wait -> collect result
|
||||
|
||||
### TeamMcpConfigBuilder.ts (229 LOC)
|
||||
Генерирует MCP config JSON-файл, мержит с user-серверами из `~/.claude.json`.
|
||||
|
||||
### Общий паттерн spawn (из TeamProvisioningService):
|
||||
```typescript
|
||||
const spawnArgs = [
|
||||
'--input-format', 'stream-json',
|
||||
'--output-format', 'stream-json',
|
||||
'--verbose',
|
||||
'--setting-sources', 'user,project,local',
|
||||
'--mcp-config', mcpConfigPath,
|
||||
'--disallowedTools', 'TeamDelete,TodoWrite',
|
||||
...(skipPermissions ? ['--dangerously-skip-permissions'] : []),
|
||||
...(model ? ['--model', model] : []),
|
||||
];
|
||||
child = spawnCli(claudePath, spawnArgs, {
|
||||
cwd, env, stdio: ['pipe', 'pipe', 'pipe'],
|
||||
});
|
||||
// stdin: send JSON messages
|
||||
child.stdin.write(JSON.stringify({
|
||||
type: 'user',
|
||||
message: { role: 'user', content: [{ type: 'text', text: prompt }] }
|
||||
}) + '\n');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Что РЕАЛЬНО отличается между CLI-агентами
|
||||
|
||||
### Сводная таблица (исследование март 2026)
|
||||
|
||||
| Аспект | Claude Code | Codex (OpenAI) | Gemini CLI | Goose (Block) | OpenCode |
|
||||
|--------|-------------|-----------------|------------|---------------|----------|
|
||||
| **Binary** | `claude` | `codex` | `gemini` | `goose` | `opencode` |
|
||||
| **Programmatic mode** | `--input-format stream-json --output-format stream-json` | `codex exec --json` (NDJSON events) | `--output-format json` (headless) | `goose run --output-format stream-json` | `opencode run --format json` |
|
||||
| **Stdin messaging** | stream-json protocol (SDKUserMessage) | Нет stdin — одноразовый exec | Нет stdin — одноразовый | Нет stdin — одноразовый `run` | Нет stdin — pipe prompt или `--attach` |
|
||||
| **Output protocol** | NDJSON (type: user/assistant/result/control_request/system) | NDJSON events | JSON (структура неизвестна) | NDJSON (text/json/stream-json) | JSON events |
|
||||
| **MCP config** | `--mcp-config /path/to/file.json` | `config.toml` (`codex mcp add`) | `settings.json` (`gemini mcp add`) | `--with-extension "cmd"` (runtime) | Config file (opencode.json) |
|
||||
| **MCP config format** | `{ mcpServers: { name: { command, args } } }` | TOML (встроенная команда `codex mcp`) | JSON settings.json `{ mcpServers: {...} }` | CLI flags per extension | JSON config |
|
||||
| **Kill semantics** | SIGKILL (team) / SIGTERM (scheduled) | SIGTERM | SIGTERM | SIGTERM | SIGTERM |
|
||||
| **Keep-alive** | Да (stream-json stdin/stdout loop) | Нет (exec = one-shot) | Нет (headless = one-shot) | Нет (run = one-shot) | Возможно (`--attach` к serve) |
|
||||
| **Team/multi-agent** | Нативные Agent Teams (TeamCreate, SendMessage) | Нет встроенного | Нет встроенного | Нет встроенного | Subagents через Task tool |
|
||||
| **Prompt flag** | Stdin (stream-json) или `-p` (one-shot) | `codex exec "prompt"` (positional) | `-p "prompt"` или pipe | `goose run -t "prompt"` или `-i file` | `opencode run "prompt"` (positional) |
|
||||
|
||||
### Источники
|
||||
- [Codex CLI Reference](https://developers.openai.com/codex/cli/reference) — `codex exec --json`, NDJSON events
|
||||
- [Codex MCP Docs](https://developers.openai.com/codex/mcp) — config.toml based MCP
|
||||
- [Gemini CLI MCP Docs](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) — settings.json, `gemini mcp add`
|
||||
- [Goose CLI Commands](https://block.github.io/goose/docs/guides/goose-cli-commands/) — `--output-format stream-json`, `--with-extension`
|
||||
- [Goose --output-format issue #4419](https://github.com/block/goose/issues/4419) — json/stream-json Done
|
||||
- [OpenCode CLI Docs](https://opencode.ai/docs/cli/) — `run --format json`
|
||||
- [OpenCode Agents Docs](https://opencode.ai/docs/agents/) — subagents, Task tool
|
||||
|
||||
---
|
||||
|
||||
## 3. Ключевой вывод: ГДЕ реальная сложность
|
||||
|
||||
### Что тривиально (просто конфиг):
|
||||
- **Binary name** — строка
|
||||
- **Prompt flag** — `-p`, `-t`, позиционный arg, или stdin
|
||||
- **Output format flag** — `--output-format stream-json`, `--json`, `--format json`
|
||||
- **Model flag** — `--model`, `-m`, `--provider/--model`
|
||||
- **Permission flags** — `--dangerously-skip-permissions`, `--full-auto`, `--yolo`
|
||||
- **Kill signal** — SIGKILL vs SIGTERM
|
||||
|
||||
### Что НЕ тривиально (требует адаптера):
|
||||
1. **Stdin protocol** — ТОЛЬКО Claude имеет persistent stdin loop (stream-json). Все остальные — one-shot (запустил, получил результат, процесс завершился). Это ФУНДАМЕНТАЛЬНОЕ отличие.
|
||||
2. **Output parsing** — NDJSON формат похож, но структура объектов разная. Claude: `{type: "assistant", message: {...}}`. Codex: свой формат events. Goose: свой. Gemini: свой.
|
||||
3. **MCP config injection** — Claude: `--mcp-config file.json`. Codex: нужно `codex mcp add` заранее или config.toml. Gemini: нужно `gemini mcp add` или settings.json. Goose: `--with-extension` per runtime.
|
||||
|
||||
### Честная оценка: что из 8000 LOC TeamProvisioningService нужно для других CLI?
|
||||
|
||||
**НЕ нужно** (Claude-specific, 80% кода):
|
||||
- stream-json stdin messaging loop
|
||||
- `control_request` protocol (tool approval)
|
||||
- Teammate spawn tracking (`memberSpawnStatuses`)
|
||||
- Agent Teams protocol (TeamCreate, SendMessage, TaskCreate)
|
||||
- Post-compact context recovery
|
||||
- Cross-team messaging relay
|
||||
- Lead activity state machine
|
||||
- Filesystem monitoring для team files (config.json, inboxes/, tasks/)
|
||||
- Auth retry через respawn
|
||||
|
||||
**Нужно** (общий ~20% skeleton):
|
||||
- Binary resolution (`ClaudeBinaryResolver` -> обобщённый)
|
||||
- Shell env resolution (`resolveInteractiveShellEnv`)
|
||||
- MCP config generation и injection
|
||||
- Process spawn + stdio pipes
|
||||
- stdout/stderr collection
|
||||
- Kill + cleanup
|
||||
- Timeout/stall detection
|
||||
- Progress reporting
|
||||
|
||||
---
|
||||
|
||||
## 4. Три варианта дизайна
|
||||
|
||||
### Option A: Config-driven (одна функция + конфиг)
|
||||
|
||||
**~120 LOC total** (config object + spawnAgent function + output normalizer)
|
||||
|
||||
```typescript
|
||||
// src/main/utils/agentConfig.ts (~60 LOC)
|
||||
|
||||
export type AgentType = 'claude' | 'codex' | 'gemini' | 'goose' | 'opencode';
|
||||
|
||||
export type OutputProtocol = 'stream-json' | 'ndjson-events' | 'json-batch';
|
||||
|
||||
/** How to inject the user prompt into the CLI */
|
||||
export type PromptMode =
|
||||
| { type: 'stdin-stream-json' } // Claude: persistent stdin loop
|
||||
| { type: 'flag'; flag: string } // -p "prompt", -t "prompt"
|
||||
| { type: 'positional' } // codex exec "prompt"
|
||||
| { type: 'stdin-pipe' }; // echo "prompt" | opencode run
|
||||
|
||||
export interface AgentConfig {
|
||||
/** Binary name (resolved via PATH or explicit path) */
|
||||
bin: string;
|
||||
/** How to pass the prompt */
|
||||
promptMode: PromptMode;
|
||||
/** CLI flags for programmatic output */
|
||||
outputArgs: string[];
|
||||
/** How stdout should be parsed */
|
||||
outputProtocol: OutputProtocol;
|
||||
/** How to inject MCP servers */
|
||||
mcpInjection:
|
||||
| { type: 'flag'; flag: string; format: 'claude-json' } // --mcp-config file.json
|
||||
| { type: 'runtime-flag'; flag: string } // --with-extension "cmd"
|
||||
| { type: 'config-file'; path: string; format: 'toml' | 'json' } // write to config
|
||||
| { type: 'cli-command'; command: string[] }; // codex mcp add ...
|
||||
/** Signal to use for killing */
|
||||
killSignal: NodeJS.Signals;
|
||||
/** Extra env vars */
|
||||
env?: Record<string, string>;
|
||||
/** Whether the process stays alive for multi-turn (only Claude) */
|
||||
persistent: boolean;
|
||||
}
|
||||
|
||||
export const AGENT_CONFIGS: Record<AgentType, AgentConfig> = {
|
||||
claude: {
|
||||
bin: 'claude',
|
||||
promptMode: { type: 'stdin-stream-json' },
|
||||
outputArgs: ['--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose'],
|
||||
outputProtocol: 'stream-json',
|
||||
mcpInjection: { type: 'flag', flag: '--mcp-config', format: 'claude-json' },
|
||||
killSignal: 'SIGKILL',
|
||||
env: { CLAUDE_HOOK_JUDGE_MODE: 'true' },
|
||||
persistent: true,
|
||||
},
|
||||
codex: {
|
||||
bin: 'codex',
|
||||
promptMode: { type: 'positional' },
|
||||
outputArgs: ['exec', '--json'],
|
||||
outputProtocol: 'ndjson-events',
|
||||
mcpInjection: { type: 'config-file', path: '~/.codex/config.toml', format: 'toml' },
|
||||
killSignal: 'SIGTERM',
|
||||
persistent: false,
|
||||
},
|
||||
gemini: {
|
||||
bin: 'gemini',
|
||||
promptMode: { type: 'flag', flag: '-p' },
|
||||
outputArgs: ['--output-format', 'json'],
|
||||
outputProtocol: 'json-batch',
|
||||
mcpInjection: { type: 'cli-command', command: ['gemini', 'mcp', 'add'] },
|
||||
killSignal: 'SIGTERM',
|
||||
persistent: false,
|
||||
},
|
||||
goose: {
|
||||
bin: 'goose',
|
||||
promptMode: { type: 'flag', flag: '-t' },
|
||||
outputArgs: ['run', '--output-format', 'stream-json'],
|
||||
outputProtocol: 'stream-json',
|
||||
mcpInjection: { type: 'runtime-flag', flag: '--with-extension' },
|
||||
killSignal: 'SIGTERM',
|
||||
persistent: false,
|
||||
},
|
||||
opencode: {
|
||||
bin: 'opencode',
|
||||
promptMode: { type: 'positional' },
|
||||
outputArgs: ['run', '--format', 'json'],
|
||||
outputProtocol: 'json-batch',
|
||||
mcpInjection: { type: 'config-file', path: '.opencode.json', format: 'json' },
|
||||
killSignal: 'SIGTERM',
|
||||
persistent: false,
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/main/utils/agentSpawn.ts (~60 LOC)
|
||||
|
||||
import { spawnCli, killProcessTree } from './childProcess';
|
||||
import { AGENT_CONFIGS, type AgentType, type AgentConfig } from './agentConfig';
|
||||
|
||||
export interface AgentSpawnOptions {
|
||||
type: AgentType;
|
||||
prompt: string;
|
||||
cwd: string;
|
||||
env?: NodeJS.ProcessEnv;
|
||||
model?: string;
|
||||
mcpConfigPath?: string; // pre-built MCP config file (for Claude-style --mcp-config)
|
||||
extraArgs?: string[];
|
||||
}
|
||||
|
||||
export interface SpawnedAgent {
|
||||
child: import('child_process').ChildProcess;
|
||||
config: AgentConfig;
|
||||
kill: () => void;
|
||||
/** Send message (only works for persistent agents like Claude) */
|
||||
send?: (text: string) => void;
|
||||
}
|
||||
|
||||
export function spawnAgent(options: AgentSpawnOptions): SpawnedAgent {
|
||||
const config = AGENT_CONFIGS[options.type];
|
||||
const args: string[] = [...config.outputArgs];
|
||||
|
||||
// Inject MCP config
|
||||
if (options.mcpConfigPath && config.mcpInjection.type === 'flag') {
|
||||
args.push(config.mcpInjection.flag, options.mcpConfigPath);
|
||||
}
|
||||
|
||||
// Extra args
|
||||
if (options.extraArgs) {
|
||||
args.push(...options.extraArgs);
|
||||
}
|
||||
|
||||
// Inject prompt based on mode
|
||||
switch (config.promptMode.type) {
|
||||
case 'flag':
|
||||
args.push(config.promptMode.flag, options.prompt);
|
||||
break;
|
||||
case 'positional':
|
||||
args.push(options.prompt);
|
||||
break;
|
||||
case 'stdin-stream-json':
|
||||
case 'stdin-pipe':
|
||||
// Handled after spawn
|
||||
break;
|
||||
}
|
||||
|
||||
const child = spawnCli(config.bin, args, {
|
||||
cwd: options.cwd,
|
||||
env: { ...(options.env ?? process.env), ...(config.env ?? {}) },
|
||||
stdio: config.persistent ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'pipe', 'pipe'],
|
||||
});
|
||||
|
||||
// Send prompt via stdin if needed
|
||||
if (config.promptMode.type === 'stdin-stream-json' && child.stdin?.writable) {
|
||||
const msg = JSON.stringify({
|
||||
type: 'user',
|
||||
message: { role: 'user', content: [{ type: 'text', text: options.prompt }] },
|
||||
});
|
||||
child.stdin.write(msg + '\n');
|
||||
} else if (config.promptMode.type === 'stdin-pipe' && child.stdin) {
|
||||
child.stdin.write(options.prompt);
|
||||
child.stdin.end();
|
||||
}
|
||||
|
||||
return {
|
||||
child,
|
||||
config,
|
||||
kill: () => killProcessTree(child, config.killSignal),
|
||||
send: config.persistent
|
||||
? (text: string) => {
|
||||
if (!child.stdin?.writable) return;
|
||||
const msg = JSON.stringify({
|
||||
type: 'user',
|
||||
message: { role: 'user', content: [{ type: 'text', text }] },
|
||||
});
|
||||
child.stdin.write(msg + '\n');
|
||||
}
|
||||
: undefined,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
**Плюсы:**
|
||||
- Минимум кода (~120 LOC в двух файлах)
|
||||
- Нет классов, нет наследования, нет интерфейсов
|
||||
- Новый CLI = добавить запись в AGENT_CONFIGS
|
||||
- Легко тестировать (pure config + one function)
|
||||
- Не ломает существующий код — TeamProvisioningService может использовать или не использовать
|
||||
|
||||
**Минусы:**
|
||||
- Output parsing НЕ покрыт (каждый CLI имеет свою структуру NDJSON)
|
||||
- MCP config injection для Codex/Gemini требует отдельной логики (write to config.toml, run `gemini mcp add`)
|
||||
- `persistent: true` (Claude) vs one-shot (все остальные) — фундаментально разный lifecycle
|
||||
|
||||
**Надёжность: 7/10** — Покрывает spawn, но не parsing.
|
||||
**Уверенность: 8/10** — Config-based подход проверен в ScheduledTaskExecutor.
|
||||
|
||||
---
|
||||
|
||||
### Option B: Thin interface + implementations
|
||||
|
||||
**~200 LOC total** (interface + claude adapter + generic one-shot adapter)
|
||||
|
||||
```typescript
|
||||
// src/main/adapters/AgentAdapter.ts (~30 LOC)
|
||||
|
||||
import type { ChildProcess } from 'child_process';
|
||||
|
||||
export interface AgentOutput {
|
||||
type: 'text' | 'tool_use' | 'tool_result' | 'thinking' | 'result' | 'error' | 'raw';
|
||||
content: string;
|
||||
raw?: unknown;
|
||||
}
|
||||
|
||||
export interface AgentAdapter {
|
||||
readonly agentType: string;
|
||||
readonly persistent: boolean;
|
||||
|
||||
/** Build CLI args for spawning */
|
||||
buildArgs(prompt: string, options: { model?: string; mcpConfigPath?: string; extraArgs?: string[] }): string[];
|
||||
|
||||
/** Parse a single line/chunk of stdout into normalized output */
|
||||
parseOutput(line: string): AgentOutput | null;
|
||||
|
||||
/** Send a follow-up message (only for persistent agents) */
|
||||
sendMessage?(child: ChildProcess, text: string): void;
|
||||
|
||||
/** Which signal to use for kill */
|
||||
killSignal: NodeJS.Signals;
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/main/adapters/ClaudeAdapter.ts (~60 LOC)
|
||||
export class ClaudeAdapter implements AgentAdapter {
|
||||
readonly agentType = 'claude';
|
||||
readonly persistent = true;
|
||||
readonly killSignal = 'SIGKILL' as const;
|
||||
|
||||
buildArgs(prompt: string, options) {
|
||||
const args = [
|
||||
'--input-format', 'stream-json',
|
||||
'--output-format', 'stream-json',
|
||||
'--verbose',
|
||||
];
|
||||
if (options.mcpConfigPath) args.push('--mcp-config', options.mcpConfigPath);
|
||||
if (options.model) args.push('--model', options.model);
|
||||
args.push(...(options.extraArgs ?? []));
|
||||
return args;
|
||||
// prompt sent via sendMessage(), not in args
|
||||
}
|
||||
|
||||
parseOutput(line: string): AgentOutput | null {
|
||||
try {
|
||||
const obj = JSON.parse(line);
|
||||
if (obj.type === 'assistant') return { type: 'text', content: /* extract */, raw: obj };
|
||||
if (obj.type === 'result') return { type: 'result', content: obj.result?.text ?? '', raw: obj };
|
||||
return { type: 'raw', content: line, raw: obj };
|
||||
} catch { return null; }
|
||||
}
|
||||
|
||||
sendMessage(child: ChildProcess, text: string) {
|
||||
if (!child.stdin?.writable) return;
|
||||
child.stdin.write(JSON.stringify({
|
||||
type: 'user',
|
||||
message: { role: 'user', content: [{ type: 'text', text }] },
|
||||
}) + '\n');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/main/adapters/OneShotAdapter.ts (~80 LOC)
|
||||
// Generic one-shot adapter configurable for Codex, Goose, Gemini, OpenCode
|
||||
|
||||
export interface OneShotConfig {
|
||||
agentType: string;
|
||||
subcommand?: string; // 'exec', 'run', etc.
|
||||
outputFlag: string[]; // ['--json'], ['--output-format', 'stream-json'], etc.
|
||||
promptFlag?: string; // '-p', '-t', or undefined for positional
|
||||
mcpFlag?: string; // '--with-extension' for goose
|
||||
killSignal?: NodeJS.Signals;
|
||||
}
|
||||
|
||||
export class OneShotAdapter implements AgentAdapter {
|
||||
readonly persistent = false;
|
||||
readonly agentType: string;
|
||||
readonly killSignal: NodeJS.Signals;
|
||||
private config: OneShotConfig;
|
||||
|
||||
constructor(config: OneShotConfig) {
|
||||
this.config = config;
|
||||
this.agentType = config.agentType;
|
||||
this.killSignal = config.killSignal ?? 'SIGTERM';
|
||||
}
|
||||
|
||||
buildArgs(prompt: string, options) {
|
||||
const args: string[] = [];
|
||||
if (this.config.subcommand) args.push(this.config.subcommand);
|
||||
args.push(...this.config.outputFlag);
|
||||
if (options.mcpConfigPath && this.config.mcpFlag) {
|
||||
args.push(this.config.mcpFlag, options.mcpConfigPath);
|
||||
}
|
||||
args.push(...(options.extraArgs ?? []));
|
||||
if (this.config.promptFlag) {
|
||||
args.push(this.config.promptFlag, prompt);
|
||||
} else {
|
||||
args.push(prompt); // positional
|
||||
}
|
||||
return args;
|
||||
}
|
||||
|
||||
parseOutput(line: string): AgentOutput | null {
|
||||
try {
|
||||
const obj = JSON.parse(line);
|
||||
return { type: 'raw', content: line, raw: obj };
|
||||
} catch { return null; }
|
||||
}
|
||||
}
|
||||
|
||||
// Pre-built instances:
|
||||
export const codexAdapter = new OneShotAdapter({
|
||||
agentType: 'codex', subcommand: 'exec', outputFlag: ['--json'], killSignal: 'SIGTERM',
|
||||
});
|
||||
export const gooseAdapter = new OneShotAdapter({
|
||||
agentType: 'goose', subcommand: 'run', outputFlag: ['--output-format', 'stream-json'],
|
||||
promptFlag: '-t', mcpFlag: '--with-extension',
|
||||
});
|
||||
export const geminiAdapter = new OneShotAdapter({
|
||||
agentType: 'gemini', outputFlag: ['--output-format', 'json'], promptFlag: '-p',
|
||||
});
|
||||
export const opencodeAdapter = new OneShotAdapter({
|
||||
agentType: 'opencode', subcommand: 'run', outputFlag: ['--format', 'json'],
|
||||
});
|
||||
```
|
||||
|
||||
**Плюсы:**
|
||||
- `parseOutput()` даёт место для нормализации вывода каждого CLI
|
||||
- Чёткое разделение: Claude (persistent) vs all others (one-shot)
|
||||
- `OneShotAdapter` — generic, покрывает 4 из 5 CLI одним классом
|
||||
- Новый CLI = `new OneShotAdapter({ ... })` (одна строка)
|
||||
|
||||
**Минусы:**
|
||||
- Интерфейс + 2 класса — чуть больше "архитектуры" чем нужно прямо сейчас
|
||||
- `parseOutput()` для не-Claude CLI будет пустышкой (return raw) пока не изучим их NDJSON формат
|
||||
- Всё ещё не решает MCP injection для Codex (config.toml) и Gemini (settings.json)
|
||||
|
||||
**Надёжность: 8/10** — Хороший баланс между простотой и расширяемостью.
|
||||
**Уверенность: 7/10** — Interface-based подход стандартен, но `parseOutput` рискует стать "мёртвым кодом" на начальном этапе.
|
||||
|
||||
---
|
||||
|
||||
### Option C: Расширить childProcess.ts (минимальные изменения) **(Recommended)**
|
||||
|
||||
**~50 LOC additions** к существующему файлу + **~30 LOC** отдельный config
|
||||
|
||||
```typescript
|
||||
// Добавить в src/main/utils/childProcess.ts (~25 LOC)
|
||||
|
||||
export type AgentType = 'claude' | 'codex' | 'gemini' | 'goose' | 'opencode';
|
||||
|
||||
export interface AgentSpawnResult {
|
||||
child: ChildProcess;
|
||||
send?: (text: string) => void;
|
||||
kill: () => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Spawn any supported CLI agent. Thin wrapper over spawnCli that
|
||||
* handles binary name, output-format flags, and prompt injection.
|
||||
*/
|
||||
export function spawnAgent(
|
||||
type: AgentType,
|
||||
binaryPath: string,
|
||||
prompt: string,
|
||||
options: SpawnOptions & { mcpConfigPath?: string; extraArgs?: string[] } = {}
|
||||
): AgentSpawnResult {
|
||||
const cfg = AGENT_SPAWN_CONFIGS[type];
|
||||
const args = [...cfg.baseArgs];
|
||||
if (options.mcpConfigPath && cfg.mcpFlag) {
|
||||
args.push(cfg.mcpFlag, options.mcpConfigPath);
|
||||
}
|
||||
if (options.extraArgs) args.push(...options.extraArgs);
|
||||
if (cfg.promptFlag) args.push(cfg.promptFlag, prompt);
|
||||
else if (!cfg.stdinPrompt) args.push(prompt);
|
||||
|
||||
const child = spawnCli(binaryPath, args, {
|
||||
...options,
|
||||
env: { ...(options.env ?? process.env), ...(cfg.env ?? {}) },
|
||||
stdio: ['pipe', 'pipe', 'pipe'],
|
||||
});
|
||||
|
||||
// Inject prompt via stdin if needed
|
||||
if (cfg.stdinPrompt && child.stdin?.writable) {
|
||||
const msg = cfg.stdinPrompt === 'stream-json'
|
||||
? JSON.stringify({ type: 'user', message: { role: 'user', content: [{ type: 'text', text: prompt }] } }) + '\n'
|
||||
: prompt;
|
||||
child.stdin.write(msg);
|
||||
if (cfg.stdinPrompt === 'pipe') child.stdin.end();
|
||||
}
|
||||
|
||||
return {
|
||||
child,
|
||||
send: cfg.stdinPrompt === 'stream-json'
|
||||
? (text: string) => {
|
||||
if (!child.stdin?.writable) return;
|
||||
child.stdin.write(JSON.stringify({
|
||||
type: 'user',
|
||||
message: { role: 'user', content: [{ type: 'text', text }] },
|
||||
}) + '\n');
|
||||
}
|
||||
: undefined,
|
||||
kill: () => killProcessTree(child, cfg.killSignal),
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/main/utils/agentConfigs.ts (~30 LOC)
|
||||
|
||||
interface AgentSpawnConfig {
|
||||
baseArgs: string[];
|
||||
promptFlag?: string; // undefined = positional arg
|
||||
stdinPrompt?: 'stream-json' | 'pipe';
|
||||
mcpFlag?: string;
|
||||
killSignal: NodeJS.Signals;
|
||||
env?: Record<string, string>;
|
||||
}
|
||||
|
||||
export const AGENT_SPAWN_CONFIGS: Record<string, AgentSpawnConfig> = {
|
||||
claude: {
|
||||
baseArgs: ['--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose'],
|
||||
stdinPrompt: 'stream-json',
|
||||
mcpFlag: '--mcp-config',
|
||||
killSignal: 'SIGKILL',
|
||||
env: { CLAUDE_HOOK_JUDGE_MODE: 'true' },
|
||||
},
|
||||
codex: {
|
||||
baseArgs: ['exec', '--json'],
|
||||
killSignal: 'SIGTERM',
|
||||
},
|
||||
gemini: {
|
||||
baseArgs: ['--output-format', 'json'],
|
||||
promptFlag: '-p',
|
||||
killSignal: 'SIGTERM',
|
||||
},
|
||||
goose: {
|
||||
baseArgs: ['run', '--output-format', 'stream-json'],
|
||||
promptFlag: '-t',
|
||||
mcpFlag: '--with-extension',
|
||||
killSignal: 'SIGTERM',
|
||||
},
|
||||
opencode: {
|
||||
baseArgs: ['run', '--format', 'json'],
|
||||
killSignal: 'SIGTERM',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
**Плюсы:**
|
||||
- Абсолютный минимум нового кода (~55 LOC)
|
||||
- Не создаёт новую абстракцию — расширяет существующую
|
||||
- TeamProvisioningService может постепенно мигрировать (или нет)
|
||||
- Новый CLI = 5 строк в конфиге
|
||||
- Binary resolution остаётся на вызывающей стороне (как сейчас с ClaudeBinaryResolver)
|
||||
- Output parsing — ответственность вызывающего кода (не навязываем)
|
||||
|
||||
**Минусы:**
|
||||
- Не покрывает output parsing (сознательно)
|
||||
- Не покрывает MCP config injection для Codex/Gemini
|
||||
- childProcess.ts станет чуть толще (~275 LOC вместо 221)
|
||||
- Нет типизации вывода (каждый consumer парсит сам)
|
||||
|
||||
**Надёжность: 7/10** — Минимально, но достаточно для spawn.
|
||||
**Уверенность: 9/10** — Расширение существующего утилитного файла — самый безопасный путь.
|
||||
|
||||
---
|
||||
|
||||
## 5. Сравнительная таблица
|
||||
|
||||
| Критерий | Option A (config+fn) | Option B (interface) | Option C (extend existing) |
|
||||
|----------|---------------------|---------------------|---------------------------|
|
||||
| **LOC** | ~120 | ~200 | ~55 |
|
||||
| **Новых файлов** | 2 | 3 | 1 |
|
||||
| **Output parsing** | Нет | Да (заглушка) | Нет |
|
||||
| **MCP injection** | Описано, не реализовано | Описано, не реализовано | Описано, не реализовано |
|
||||
| **Расширяемость** | Хорошая (конфиг) | Отличная (интерфейс) | Хорошая (конфиг) |
|
||||
| **Breaks existing?** | Нет | Нет | Нет |
|
||||
| **Time to implement** | 1 час | 2 часа | 30 мин |
|
||||
| **"Велосипед"?** | Нет, это конфиг | Нет, но чуть преждевременно | Нет, это 55 строк клея |
|
||||
|
||||
---
|
||||
|
||||
## 6. Рекомендация
|
||||
|
||||
### Начать с Option C (extend childProcess.ts), при необходимости вырастить в Option A
|
||||
|
||||
**Почему:**
|
||||
|
||||
1. **55 LOC — это не велосипед.** Это минимальный config-driven dispatcher. Любой проект, интегрирующий несколько CLI, пишет ровно это. Нет смысла тянуть зависимость ради 55 строк.
|
||||
|
||||
2. **Output parsing — отдельная задача.** Парсинг NDJSON от Codex/Gemini/Goose — это ~50-100 LOC на каждый CLI, и его не нужно решать сейчас. Когда понадобится — это будет Option B (interface с `parseOutput()`), но не раньше.
|
||||
|
||||
3. **MCP injection — тоже отдельная задача.** Для Claude у нас уже есть TeamMcpConfigBuilder. Для Goose — это просто `--with-extension`. Для Codex/Gemini — нужно писать в их config files. Это 3 отдельных утилиты, не общий адаптер.
|
||||
|
||||
4. **Persistent vs one-shot — фундаментально разный lifecycle.** Claude (stream-json loop) живёт долго и получает новые сообщения. Все остальные — fire-and-forget. Эту разницу нельзя "спрятать" за единым интерфейсом без того чтобы интерфейс не стал дырявой абстракцией.
|
||||
|
||||
### Эволюционный путь:
|
||||
|
||||
```
|
||||
Этап 1 (сейчас): Option C — spawnAgent() в childProcess.ts + agentConfigs.ts
|
||||
55 LOC, покрывает spawn для всех 5 CLI
|
||||
|
||||
Этап 2 (когда добавим 2-й CLI): Вынести в отдельный файл если childProcess.ts станет перегруженным
|
||||
Может стать Option A (~120 LOC)
|
||||
|
||||
Этап 3 (когда нужен output parsing): Добавить parseOutput() per agent
|
||||
Может стать Option B (~200 LOC)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Честный ответ: "велосипед" или нет?
|
||||
|
||||
**Нет, это НЕ велосипед.** Вот почему:
|
||||
|
||||
1. **Нет готовой библиотеки.** Не существует npm-пакета "universal-cli-agent-spawner". Каждый из этих CLI — молодой продукт (2025-2026), с собственным протоколом. Никто ещё не написал унификатор.
|
||||
|
||||
2. **55-200 LOC клея — это норма.** Для сравнения:
|
||||
- Docker SDK для Node.js: ~300 LOC для spawn docker CLI
|
||||
- Terraform CDK: ~200 LOC для spawn terraform binary
|
||||
- VS Code extensions: ~150 LOC для spawn language server
|
||||
|
||||
3. **Наш существующий spawnCli() — уже 65 LOC** клея для одного Claude CLI. Расширить его до 5 CLI за +55 LOC — это линейное масштабирование, не экспоненциальное.
|
||||
|
||||
4. **Реальный "велосипед" начался бы** если бы мы писали:
|
||||
- Свой MCP client (~500+ LOC)
|
||||
- Свой NDJSON parser с backpressure (~200 LOC)
|
||||
- Свой process supervisor с restart policies (~400 LOC)
|
||||
- Свой auth token manager per CLI (~300 LOC)
|
||||
|
||||
Мы этого НЕ делаем. Мы пишем config map + одну функцию.
|
||||
|
||||
5. **Большую часть сложности (8000 LOC TeamProvisioningService) мы уже написали** для Claude — и она Claude-specific. Адаптер для других CLI будет использовать ~5% от этого кода.
|
||||
|
||||
---
|
||||
|
||||
## 8. Что НЕ включать в адаптер
|
||||
|
||||
Явно НЕ входит в scope минимального адаптера:
|
||||
- Output parsing/normalization (отдельный слой)
|
||||
- Team protocol (Agent Teams — Claude-only)
|
||||
- MCP config generation (отдельный builder per CLI)
|
||||
- Binary auto-discovery/installation (отдельный resolver per CLI)
|
||||
- Auth management (каждый CLI сам)
|
||||
- Session persistence (каждый CLI сам)
|
||||
- Stall/timeout detection (caller responsibility)
|
||||
- Progress reporting (caller responsibility)
|
||||
|
||||
Это всё валидная функциональность, но она живёт ВЫШЕ адаптера, в orchestration layer (TeamProvisioningService или его аналог).
|
||||
542
docs/research/multi-agent-communication-tools.md
Normal file
542
docs/research/multi-agent-communication-tools.md
Normal file
|
|
@ -0,0 +1,542 @@
|
|||
# Multi-Agent CLI Orchestrators with Inter-Agent Communication
|
||||
|
||||
> Research date: 2026-03-25
|
||||
> Focus: tools where Agent A (Claude) can send a message to Agent B (Codex/Gemini), NOT just "fan-out same task to multiple agents"
|
||||
|
||||
## TL;DR
|
||||
|
||||
Ни один инструмент не является зрелым "фундаментом" для замены нашего стека. Все проекты в этом пространстве молоды (< 6 месяцев), быстро меняют API, и ни один не имеет production-grade inter-agent communication для РАЗНЫХ провайдеров CLI-агентов уровня, который мы уже реализовали для Claude Code Agent Teams.
|
||||
|
||||
**Лидеры по inter-agent communication:**
|
||||
|
||||
| Tool | Stars | Inter-Agent Msg | Multi-Provider | Kanban | Наша оценка |
|
||||
|------|-------|----------------|----------------|--------|------------|
|
||||
| Ruflo | 25,709 | SQLite + JSON | Claude + Codex | Нет | Hype-driven, раздутые цифры |
|
||||
| Composio AO | 5,390 | CI feedback routing | Claude, Codex, Aider | Нет | Planner-executor, не P2P |
|
||||
| Claude Octopus | 2,069 | Consensus gate 75% | 8 providers | Нет | Plugin, не orchestrator |
|
||||
| mcp_agent_mail | 1,842 | MCP + SQLite inbox | Any MCP client | Нет | Протокол, не UI |
|
||||
| claude_code_bridge | 1,855 | Real-time collab | Claude, Codex, Gemini | Нет | Terminal split-pane |
|
||||
| Overstory | 1,123 | SQLite mail (WAL) | 11 runtimes | Нет | Closest to real P2P |
|
||||
| agtx | 693 | Session switching | Claude, Codex, Gemini, OpenCode, Cursor | Kanban-like | Autonomous, но молодой |
|
||||
| AI Maestro | 556 | AMP protocol | Claude, Codex, any | Kanban! | Multi-machine, но TypeScript mesh |
|
||||
| parallel-code | 407 | Нет (изоляция) | Claude, Codex, Gemini | Diff viewer | Параллельное, не collaborative |
|
||||
| CAO (AWS) | 344 | SQLite inbox + MCP | Q CLI, Claude, Codex | Нет | AWS-backed, но ранняя стадия |
|
||||
| MCO | 249 | Fan-out, не P2P | 5 CLIs | Нет | Dispatch layer, не messaging |
|
||||
| hcom | 164 | File-based hooks | Claude, Codex, Gemini, OpenCode | Нет | Lightweight, hooks-only |
|
||||
| MetaSwarm | 148 | Skills-based | Claude, Gemini, Codex | Нет | Self-improving framework |
|
||||
| CAS | 69 | Через MCP server | Claude Code only | Нет | Claude-only, раннее |
|
||||
| kodo | 46 | Verification cycle | Claude, Codex, Gemini | Нет | SWE-bench verified |
|
||||
|
||||
---
|
||||
|
||||
## 1. CAS (Coding Agent System)
|
||||
|
||||
- **Repo:** https://github.com/codingagentsystem/cas
|
||||
- **Stars:** 69
|
||||
- **Language:** Rust
|
||||
- **License:** MIT
|
||||
- **Created:** 2026-01-05
|
||||
|
||||
### Что это
|
||||
Supervisor + Workers модель для Claude Code. Factory mode оркестрирует несколько Claude Code инстансов в параллельных git worktree. MCP server дает агентам persistent memory, task tracking, rules, skills через SQLite + FTS.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- Нет прямого inter-agent messaging между агентами
|
||||
- Communication идет через supervisor (hub-and-spoke)
|
||||
- Workers не общаются друг с другом напрямую
|
||||
- Coordinator раздает задачи, workers возвращают результаты
|
||||
|
||||
### Multi-Provider Support
|
||||
- **ТОЛЬКО Claude Code** — нет поддержки Codex, Gemini, Goose и др.
|
||||
|
||||
### Вердикт
|
||||
Не подходит как фундамент. Claude-only, маленькое коммьюнити (69 stars), нет inter-agent messaging, нет multi-provider. Persistent memory через MCP server — интересная идея, но не уникальная.
|
||||
|
||||
---
|
||||
|
||||
## 2. AWS CLI Agent Orchestrator (CAO)
|
||||
|
||||
- **Repo:** https://github.com/awslabs/cli-agent-orchestrator
|
||||
- **Stars:** 344
|
||||
- **Language:** Python
|
||||
- **License:** Apache 2.0 (AWS)
|
||||
- **Created:** 2025-07-29
|
||||
|
||||
### Что это
|
||||
Иерархическая система оркестрации CLI AI агентов от AWS Labs. Три паттерна: Handoff (синхронный transfer), Assign (async spawn), Send Message (прямая коммуникация).
|
||||
|
||||
### Inter-Agent Communication
|
||||
- **Send Message** — прямые сообщения между существующими агентами
|
||||
- **SQLite inbox system** — асинхронная доставка сообщений с FIFO ordering
|
||||
- **File-watching** — определяет когда terminal idle и доставляет pending messages
|
||||
- **MCP tools** — `handoff`, `assign`, `send_message` для координации
|
||||
- **REST API** — cao-server на `localhost:9889`
|
||||
|
||||
### Multi-Provider Support
|
||||
- Amazon Q CLI, Claude Code, Codex CLI (через провайдер с API key)
|
||||
- Каждый агент в изолированной tmux сессии
|
||||
|
||||
### Что хорошо
|
||||
- AWS-backed = стабильная поддержка
|
||||
- Реальный inter-agent messaging через SQLite inbox
|
||||
- Profile-based agent isolation
|
||||
- Cron-like scheduled runs
|
||||
|
||||
### Что плохо
|
||||
- 344 stars — ранняя стадия
|
||||
- Зависимость на tmux
|
||||
- Python-based (не наш стек)
|
||||
- Нет UI/dashboard
|
||||
|
||||
### Вердикт
|
||||
Наиболее продуманный подход к inter-agent messaging через SQLite inbox. Но ранняя стадия, нет UI, Python-only. Send Message паттерн — это то, что нам нужно, но реализация привязана к tmux sessions.
|
||||
|
||||
---
|
||||
|
||||
## 3. Overstory
|
||||
|
||||
- **Repo:** https://github.com/jayminwest/overstory
|
||||
- **Stars:** 1,123
|
||||
- **Language:** TypeScript (Bun)
|
||||
- **License:** MIT
|
||||
- **Created:** 2026-02-12
|
||||
|
||||
### Что это
|
||||
Превращает coding session в multi-agent team. Workers в git worktree через tmux. SQLite mail system для координации. FIFO merge queue с 4-tier conflict resolution.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- **SQLite mail system** (WAL mode, ~1-5ms/query) — ключевая фича
|
||||
- **8 typed protocol messages:** `worker_done`, `merge_ready`, `merged`, `merge_failed`, `escalation`, `health_check`, `dispatch`, `assign`
|
||||
- **Type-safe API:** `sendProtocol<T>()` и `parsePayload<T>()`
|
||||
- **Broadcast:** группы `@all`, `@builders` и др.
|
||||
- **`overstory mail`** CLI: send/check/list/read/reply
|
||||
|
||||
### Multi-Provider Support
|
||||
- **11 runtime adapters:** Claude Code, Pi, Gemini CLI, Aider, Goose, Amp и др.
|
||||
- Pluggable `AgentRuntime` interface
|
||||
|
||||
### Что хорошо
|
||||
- Самый развитый SQLite mail system среди всех инструментов
|
||||
- Type-safe protocol messages — близко к нашему подходу с inbox files
|
||||
- 11 runtime adapters — реальная мультипровайдерность
|
||||
- TypeScript/Bun — совместимый стек
|
||||
|
||||
### Что плохо
|
||||
- Зависимость на tmux + Bun (не Node/Electron)
|
||||
- "Compounding error rates, cost amplification, debugging complexity" — сами предупреждают
|
||||
- Нет UI — всё CLI
|
||||
- 1,123 stars за 1.5 месяца — быстрый рост, но незрелый
|
||||
|
||||
### Вердикт
|
||||
Ближайший по архитектуре к нашему подходу (SQLite mail ~ наш inbox system). Протокольные сообщения с типами, broadcast — всё это у нас уже есть. Мог бы быть полезен как reference для protocol design, но не как фундамент.
|
||||
|
||||
---
|
||||
|
||||
## 4. Composio Agent Orchestrator
|
||||
|
||||
- **Repo:** https://github.com/ComposioHQ/agent-orchestrator
|
||||
- **Stars:** 5,390
|
||||
- **Language:** TypeScript
|
||||
- **License:** MIT
|
||||
- **Created:** 2026-02-13
|
||||
|
||||
### Что это
|
||||
Planner-Executor модель для fleet of parallel coding agents. Orchestrator — сам AI agent который читает codebase, decompose features, мониторит progress. Plugin system с 8 swappable slots.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- **НЕ peer-to-peer messaging** — orchestrator agent роутит feedback
|
||||
- CI failures → injection back в agent session
|
||||
- Review comments → routing в правильный agent с контекстом
|
||||
- Self-improvement loop: logs → retrospectives → adjustments
|
||||
|
||||
### Multi-Provider Support
|
||||
- Claude Code, Codex, Aider
|
||||
- Runtime-agnostic: tmux, Docker
|
||||
- Tracker-agnostic: GitHub, Linear
|
||||
|
||||
### Что хорошо
|
||||
- 5,390 stars — самый популярный в категории
|
||||
- TypeScript — наш стек
|
||||
- Self-improvement system — уникальная фича
|
||||
- Plugin architecture — гибко
|
||||
|
||||
### Что плохо
|
||||
- Нет P2P inter-agent messaging — всё через orchestrator
|
||||
- Agent A не может напрямую послать сообщение Agent B
|
||||
- Orchestrator = single point of failure
|
||||
- 1.5 месяца от creation — очень молодой
|
||||
|
||||
### Вердикт
|
||||
Самый popular, но inter-agent communication = feedback routing через orchestrator, а не direct messaging. Это принципиально другой паттерн, чем наш. Полезен как reference для planner-executor, но не для P2P communication.
|
||||
|
||||
---
|
||||
|
||||
## 5. hcom (Hook-Comms)
|
||||
|
||||
- **Repo:** https://github.com/aannoo/hcom
|
||||
- **Stars:** 164
|
||||
- **Language:** Rust
|
||||
- **Created:** 2025-07-21
|
||||
|
||||
### Что это
|
||||
Lightweight CLI для inter-agent messaging через hooks. Agents могут message, watch, spawn друг друга across terminals.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- **`send`** — отправка сообщений между agents
|
||||
- **`listen`** — блокирующее ожидание с фильтрами (agent, type, status, sender, intent)
|
||||
- **`events`** — event stream с подписками
|
||||
- **`bundle`** — structured context packages для handoffs
|
||||
- **`transcript`** — чтение conversation другого агента
|
||||
- **TUI dashboard** для мониторинга
|
||||
|
||||
### Multi-Provider Support
|
||||
- Claude Code, Gemini CLI, Codex, OpenCode
|
||||
- Hooks integration для Gemini CLI
|
||||
|
||||
### Что хорошо
|
||||
- Минимальный, специализированный tool для inter-agent messaging
|
||||
- Работает с любым CLI agent через hooks
|
||||
- `listen` с фильтрами — мощный примитив
|
||||
|
||||
### Что плохо
|
||||
- 164 stars — маленькое коммьюнити
|
||||
- Rust — другой стек
|
||||
- Нет task management, нет orchestration — только messaging
|
||||
- Зависимость на hooks mechanism
|
||||
|
||||
### Вердикт
|
||||
Интересный lightweight подход к messaging, но это only messaging layer без orchestration. Можно изучить как reference для protocol design, но не как фундамент.
|
||||
|
||||
---
|
||||
|
||||
## 6. AI Maestro
|
||||
|
||||
- **Repo:** https://github.com/23blocks-OS/ai-maestro
|
||||
- **Stars:** 556
|
||||
- **Language:** TypeScript
|
||||
- **License:** MIT
|
||||
- **Created:** 2025-10-10
|
||||
|
||||
### Что это
|
||||
Dashboard для управления агентами across multiple machines. Agent Messaging Protocol (AMP). Skills system. Code Graph. Memory.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- **Agent Messaging Protocol (AMP)** — email-like communication
|
||||
- Priority levels, message types, cryptographic signatures, push notifications
|
||||
- Отдельный open-source протокол: https://github.com/agentmessaging/protocol
|
||||
- **Peer mesh network** — multi-machine без central server
|
||||
- **External gateways:** Slack, Discord, Email, WhatsApp
|
||||
|
||||
### Multi-Provider Support
|
||||
- Claude Code, Aider, Cursor, Copilot, OpenCode, Codex CLI, Gemini CLI
|
||||
- 30+ compatible agents через Skills
|
||||
|
||||
### Kanban Board
|
||||
- **ДА!** Полный Kanban с drag-and-drop, dependencies, 5 status columns
|
||||
- Teams + War Rooms
|
||||
|
||||
### Что хорошо
|
||||
- **Kanban board** — единственный конкурент с Kanban!
|
||||
- AMP protocol — formalized inter-agent messaging
|
||||
- Multi-machine support — уникально
|
||||
- TypeScript — наш стек
|
||||
- External messaging gateways
|
||||
|
||||
### Что плохо
|
||||
- 556 stars — умеренная популярность
|
||||
- AMP protocol ещё развивается
|
||||
- tmux dependency
|
||||
- "80+ agents across multiple computers" — выглядит как over-engineering
|
||||
|
||||
### Вердикт
|
||||
**Самый близкий конкурент** по feature set: Kanban + inter-agent messaging + multi-provider + TypeScript. AMP protocol — интересный formalized подход. Стоит внимательно изучить. Однако peer mesh network и multi-machine — это другой масштаб, чем наш local-first подход.
|
||||
|
||||
---
|
||||
|
||||
## 7. ORCH
|
||||
|
||||
- **Website:** https://www.orch.one/
|
||||
- **Stars:** N/A (repo не найден / приватный на момент исследования)
|
||||
- **License:** MIT
|
||||
|
||||
### Что это
|
||||
CLI runtime для управления Claude Code, Codex, Cursor как typed agent teams. State machine, event bus, TUI.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- **Typed event bus** — 31 event type, agents emit events, orchestrator reacts
|
||||
- **Inter-agent messaging** — direct messages, broadcasts, injected в prompts
|
||||
- **Agent Teams** — group agents under lead, broadcast context
|
||||
- **State machine:** todo -> in_progress -> review -> done
|
||||
|
||||
### Multi-Provider Support
|
||||
- 5 adapters: Claude, OpenCode (Gemini, DeepSeek via OpenRouter), Codex, Cursor, Shell
|
||||
|
||||
### Что хорошо
|
||||
- Event bus architecture — decoupled communication
|
||||
- State machine — production-quality
|
||||
- 5 adapters из коробки
|
||||
- Headless daemon mode (`orch serve`)
|
||||
|
||||
### Что плохо
|
||||
- GitHub repo не найден или приватный — нельзя оценить реальный код
|
||||
- Event bus = centralized, не P2P
|
||||
- Нет UI кроме TUI
|
||||
|
||||
### Вердикт
|
||||
Архитектурно интересный (event bus + state machine), но невозможно оценить зрелость кода без доступа к repo. Event bus — это скорее pub/sub, чем direct messaging.
|
||||
|
||||
---
|
||||
|
||||
## 8. Ruflo
|
||||
|
||||
- **Repo:** https://github.com/ruvnet/ruflo
|
||||
- **Stars:** 25,709
|
||||
- **Language:** TypeScript
|
||||
- **License:** MIT
|
||||
- **Created:** 2025-06-02
|
||||
|
||||
### Что это
|
||||
"The leading agent orchestration platform for Claude." Multi-agent swarms, autonomous workflows, RAG integration. Ранее Claude-Flow.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- SQLite для memory persistence
|
||||
- JSON-based coordination protocols для inter-agent messaging
|
||||
- Compaction lifecycle → archive context to SQLite
|
||||
|
||||
### Multi-Provider Support
|
||||
- Claude Code + Codex integration
|
||||
|
||||
### Что хорошо
|
||||
- 25K stars — самый популярный в нише
|
||||
- Comprehensive feature set
|
||||
|
||||
### Что плохо
|
||||
- 25K stars за < 10 месяцев — подозрительно (возможен бот-boost)
|
||||
- "v3 introduces self-learning neural capabilities" — marketing buzzwords
|
||||
- Сравнения с конкурентами в README — red flag
|
||||
- Claude-centric, minimal real multi-provider
|
||||
|
||||
### Вердикт
|
||||
Hype-driven проект с подозрительно высокими stars. Inter-agent communication через SQLite + JSON — базовый уровень. Не стоит использовать как фундамент из-за quality concerns.
|
||||
|
||||
---
|
||||
|
||||
## 9. MCO (Multi-CLI Orchestrator)
|
||||
|
||||
- **Repo:** https://github.com/mco-org/mco
|
||||
- **Stars:** 249
|
||||
- **Language:** Python
|
||||
- **Created:** 2026-02-26
|
||||
|
||||
### Что это
|
||||
Neutral dispatch layer. Отправляет prompts на несколько CLI agents параллельно, агрегирует результаты.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- **НЕТ real inter-agent messaging**
|
||||
- Fan-out same prompt → collect results → aggregate
|
||||
- Structured code review с findings schema
|
||||
|
||||
### Multi-Provider Support
|
||||
- Claude Code, Codex CLI, Gemini CLI, OpenCode, Qwen Code
|
||||
|
||||
### Вердикт
|
||||
Dispatch/aggregation, не collaboration. Agent A не знает о Agent B. Полезен для multi-perspective review, но это не inter-agent communication.
|
||||
|
||||
---
|
||||
|
||||
## 10. mcp_agent_mail
|
||||
|
||||
- **Repo:** https://github.com/Dicklesworthstone/mcp_agent_mail
|
||||
- **Stars:** 1,842
|
||||
- **Language:** Python
|
||||
- **Created:** 2025-10-23
|
||||
|
||||
### Что это
|
||||
Mail-like coordination layer для coding agents. FastMCP server + Git + SQLite.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- **Inbox/outbox** per agent
|
||||
- **Searchable message history**
|
||||
- **File lease system** — voluntary file reservation
|
||||
- **Memorable identities** для agents
|
||||
- HTTP-only FastMCP server
|
||||
|
||||
### Multi-Provider Support
|
||||
- Any MCP-compatible client
|
||||
|
||||
### Что хорошо
|
||||
- 1,842 stars — солидное коммьюнити
|
||||
- Clean abstraction: mail metaphor для agent communication
|
||||
- File leases — unique feature для conflict prevention
|
||||
|
||||
### Что плохо
|
||||
- Python + FastMCP — другой стек
|
||||
- Только communication layer, не orchestrator
|
||||
- Нет task management, нет UI
|
||||
|
||||
### Вердикт
|
||||
Лучший standalone inter-agent communication protocol. File leases — интересная идея для нас. Но это protocol library, не ready-to-use tool.
|
||||
|
||||
---
|
||||
|
||||
## 11. agtx
|
||||
|
||||
- **Repo:** https://github.com/fynnfluegge/agtx
|
||||
- **Stars:** 693
|
||||
- **Language:** Rust
|
||||
- **Created:** 2026-02-08
|
||||
|
||||
### Что это
|
||||
Multi-session AI coding terminal manager. Autonomous orchestration с spec-driven workflow.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- Session switching с context awareness
|
||||
- Gemini -> research | Claude -> implement | Codex -> review
|
||||
- Kanban board в TUI
|
||||
|
||||
### Multi-Provider Support
|
||||
- Claude, Codex, Gemini, OpenCode, Cursor
|
||||
|
||||
### Вердикт
|
||||
Autonomous orchestration с role-based agent dispatch. Kanban-like TUI. Но Rust стек и нет rich inter-agent messaging.
|
||||
|
||||
---
|
||||
|
||||
## 12. claude_code_bridge (ccb)
|
||||
|
||||
- **Repo:** https://github.com/bfly123/claude_code_bridge
|
||||
- **Stars:** 1,855
|
||||
- **Language:** Python
|
||||
- **Created:** 2025-10-25
|
||||
|
||||
### Что это
|
||||
Real-time multi-AI collaboration. Split-pane terminal. Persistent context.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- Real-time collaboration между Claude, Codex, Gemini
|
||||
- Persistent context sharing
|
||||
- WYSIWYG split-pane terminal
|
||||
|
||||
### Вердикт
|
||||
Terminal-based collaboration, не programmatic API. Интересен как UX reference, но не как foundation.
|
||||
|
||||
---
|
||||
|
||||
## 13. Claude Octopus
|
||||
|
||||
- **Repo:** https://github.com/nyldn/claude-octopus
|
||||
- **Stars:** 2,069
|
||||
- **Language:** Shell
|
||||
- **Created:** 2026-01-15
|
||||
|
||||
### Что это
|
||||
Multi-LLM orchestration plugin для Claude Code. 8 providers, consensus gates.
|
||||
|
||||
### Inter-Agent Communication
|
||||
- 75% consensus gate — providers должны согласиться
|
||||
- Parallel (research), sequential (problem scoping), adversarial (review) modes
|
||||
|
||||
### Multi-Provider Support
|
||||
- Codex, Gemini, Claude, Perplexity, OpenRouter, Copilot, Qwen, Ollama
|
||||
|
||||
### Вердикт
|
||||
Plugin для Claude Code, не standalone orchestrator. Consensus mechanism — интересно, но это не direct messaging.
|
||||
|
||||
---
|
||||
|
||||
## Сравнительная таблица: типы Inter-Agent Communication
|
||||
|
||||
| Pattern | Tools | Описание |
|
||||
|---------|-------|----------|
|
||||
| **SQLite Inbox/Mail** | CAO, Overstory, mcp_agent_mail | Асинхронная доставка через SQLite, FIFO, typed messages |
|
||||
| **Event Bus** | ORCH | Typed events, pub/sub, decoupled |
|
||||
| **AMP Protocol** | AI Maestro | Email-like, priorities, crypto signatures, mesh network |
|
||||
| **Hooks/File-based** | hcom | File watches + hooks для inter-terminal messaging |
|
||||
| **Orchestrator Routing** | Composio AO | Central agent роутит feedback, не P2P |
|
||||
| **Fan-out/Aggregate** | MCO, Claude Octopus | Dispatch same task, collect results — не communication |
|
||||
| **Session Switching** | agtx, ccb | Context handoff между sessions — implicit communication |
|
||||
|
||||
---
|
||||
|
||||
## Ключевые выводы
|
||||
|
||||
### 1. Kanban есть ТОЛЬКО у AI Maestro
|
||||
Из всех исследованных инструментов, только AI Maestro (556 stars) имеет полноценный Kanban board с drag-and-drop. Это подтверждает нашу уникальность. Также agtx имеет kanban-like TUI, но без GUI.
|
||||
|
||||
### 2. Реальный P2P inter-agent messaging — редкость
|
||||
Большинство инструментов используют hub-and-spoke (orchestrator в центре). Реальный P2P:
|
||||
- **Overstory** — SQLite mail с typed protocol
|
||||
- **CAO** — SQLite inbox + Send Message
|
||||
- **AI Maestro** — AMP protocol + mesh
|
||||
- **hcom** — hooks-based messaging
|
||||
- **mcp_agent_mail** — MCP inbox/outbox
|
||||
|
||||
### 3. Ни один инструмент не является зрелым фундаментом
|
||||
- Все проекты < 6 месяцев (кроме Ruflo и CAO)
|
||||
- API быстро меняются
|
||||
- Большинство зависят на tmux
|
||||
- Нет production-grade error handling
|
||||
|
||||
### 4. Наш подход (Claude Code Agent Teams + Electron UI) остается уникальным
|
||||
- **Inbox-based messaging** через файлы — мы уже реализовали
|
||||
- **Kanban board** — мы единственные с полноценным GUI
|
||||
- **Electron app** — никто больше не делает desktop app для agent orchestration (кроме parallel-code)
|
||||
- **Team lifecycle management** — наш уровень detail (config.json, session management, DM) не имеет аналогов
|
||||
|
||||
### 5. Что стоит изучить/заимствовать
|
||||
|
||||
| Идея | Источник | Применимость для нас |
|
||||
|------|----------|---------------------|
|
||||
| SQLite mail protocol messages (8 types) | Overstory | Можно формализовать наши inbox message types |
|
||||
| File leases для conflict prevention | mcp_agent_mail | Полезно для multi-agent file editing |
|
||||
| AMP protocol (priorities, signatures) | AI Maestro | Можно добавить priorities в наш inbox |
|
||||
| Event bus architecture | ORCH | Для decoupled communication в Electron |
|
||||
| Self-improvement loop | Composio AO | Agent learning from past sessions |
|
||||
| Consensus gates | Claude Octopus | Multi-provider code review |
|
||||
| Pluggable AgentRuntime interface | Overstory | Для будущей multi-provider поддержки |
|
||||
|
||||
---
|
||||
|
||||
## Рекомендация
|
||||
|
||||
**НЕ использовать ни один из этих инструментов как фундамент.** Причины:
|
||||
|
||||
1. **Наш стек уникален** (Electron + React + TypeScript + Zustand) — ни один tool не совместим
|
||||
2. **Наша архитектура inbox messaging уже работает** и протестирована
|
||||
3. **Kanban board** — наше ключевое преимущество, которого нет у конкурентов
|
||||
4. **Зрелость кода** у всех инструментов низкая (< 6 месяцев)
|
||||
5. **Dependency risk** — tmux, Bun, Python, Rust — чужой стек
|
||||
|
||||
**Что имеет смысл:**
|
||||
- Изучить **Overstory** как reference для typed protocol messages
|
||||
- Изучить **mcp_agent_mail** для file lease механизма
|
||||
- Изучить **AI Maestro** как ближайшего конкурента (Kanban + AMP)
|
||||
- Следить за **CAO (AWS)** — AWS backing значит долгосрочную поддержку
|
||||
- Рассмотреть **AgentRuntime interface** из Overstory для будущей multi-provider поддержки
|
||||
|
||||
---
|
||||
|
||||
## Источники
|
||||
|
||||
- [CAS - codingagentsystem/cas](https://github.com/codingagentsystem/cas)
|
||||
- [CAS Website](https://cas.dev/)
|
||||
- [AWS CLI Agent Orchestrator](https://github.com/awslabs/cli-agent-orchestrator)
|
||||
- [AWS Blog - Introducing CAO](https://aws.amazon.com/blogs/opensource/introducing-cli-agent-orchestrator-transforming-developer-cli-tools-into-a-multi-agent-powerhouse/)
|
||||
- [CAO Message Queueing - DeepWiki](https://deepwiki.com/awslabs/cli-agent-orchestrator/3.4-message-queueing-and-inbox-system)
|
||||
- [Overstory](https://github.com/jayminwest/overstory)
|
||||
- [Composio Agent Orchestrator](https://github.com/ComposioHQ/agent-orchestrator)
|
||||
- [hcom](https://github.com/aannoo/hcom)
|
||||
- [AI Maestro](https://github.com/23blocks-OS/ai-maestro)
|
||||
- [AMP Protocol](https://github.com/agentmessaging/protocol)
|
||||
- [ORCH](https://www.orch.one/)
|
||||
- [MCO](https://github.com/mco-org/mco)
|
||||
- [Ruflo](https://github.com/ruvnet/ruflo)
|
||||
- [mcp_agent_mail](https://github.com/Dicklesworthstone/mcp_agent_mail)
|
||||
- [agtx](https://github.com/fynnfluegge/agtx)
|
||||
- [claude_code_bridge](https://github.com/bfly123/claude_code_bridge)
|
||||
- [Claude Octopus](https://github.com/nyldn/claude-octopus)
|
||||
- [parallel-code](https://github.com/johannesjo/parallel-code)
|
||||
- [MetaSwarm](https://github.com/dsifry/metaswarm)
|
||||
- [kodo](https://github.com/ikamensh/kodo)
|
||||
- [Awesome Agent Orchestrators](https://github.com/andyrewlee/awesome-agent-orchestrators)
|
||||
- [Zed Editor - External Agents / ACP](https://zed.dev/docs/ai/external-agents)
|
||||
480
docs/research/opencode-deep-dive.md
Normal file
480
docs/research/opencode-deep-dive.md
Normal file
|
|
@ -0,0 +1,480 @@
|
|||
# OpenCode Deep Dive — Comprehensive Analysis (March 2026)
|
||||
|
||||
## Executive Summary
|
||||
|
||||
OpenCode — open-source AI coding agent от Anomaly (ex-SST), ~126K GitHub stars, 800+ контрибьюторов, 5M MAU. Написан на TypeScript (Bun) + Go (TUI), MIT license. Поддерживает 75+ LLM-провайдеров через Models.dev. Архитектура client/server с persistent sessions. Agent Teams — community-implemented (не core), file-based JSONL inbox, peer-to-peer messaging, multi-provider teams (Claude+Codex+Gemini доказано). Главный конкурент Claude Code в terminal-agent пространстве.
|
||||
|
||||
**Claim verification:**
|
||||
- "95K+ stars" — **занижено**, на март 2026 ~126-129K stars
|
||||
- "75+ providers" — **подтверждено**, через Models.dev + AI SDK
|
||||
- "Multi-agent team support" — **частично**: agent teams реализованы community (opencode-ensemble plugin + PR #12730-12732), НЕ core feature, но доказали работу Claude+Codex+Gemini вместе
|
||||
|
||||
---
|
||||
|
||||
## 1. What IS OpenCode?
|
||||
|
||||
### Основные факты
|
||||
|
||||
| Параметр | Значение |
|
||||
|----------|----------|
|
||||
| **Название** | OpenCode |
|
||||
| **Организация** | Anomaly (ex-SST / Serverless Stack) |
|
||||
| **GitHub** | [anomalyco/opencode](https://github.com/anomalyco/opencode) |
|
||||
| **Сайт** | [opencode.ai](https://opencode.ai/) |
|
||||
| **Stars** | ~126-129K (март 2026) |
|
||||
| **Contributors** | 800+ |
|
||||
| **Commits** | 10,000+ |
|
||||
| **MAU** | 5M+ developers |
|
||||
| **License** | MIT |
|
||||
| **Языки** | TypeScript (Bun) — backend, Go — TUI, Zig — OpenTUI core |
|
||||
| **Дата запуска** | 19 июня 2025 |
|
||||
| **Версии** | Terminal CLI, Desktop App (beta), IDE extensions |
|
||||
|
||||
### Кто создал
|
||||
|
||||
**Founders:**
|
||||
1. **Jay V (CEO)** — задает стратегию, enterprise sales. Университет Waterloo.
|
||||
2. **Frank Wang (CTO)** — техническая архитектура. Model-agnostic дизайн с нуля. Университет Waterloo.
|
||||
3. **Dax Raad** — public face, подкасты, Twitter. Ex-Amazon, ex-Ironbay. Присоединился к SST в 2021.
|
||||
4. **Adam Elmore** — AWS Hero, indie hacker, AWS FM podcast host.
|
||||
|
||||
**Происхождение:** Jay и Frank создали Anomaly, затем Serverless Stack (SST) — прошли Y Combinator, привлекли инвестиции от основателей PayPal, LinkedIn, Yelp, YouTube. SST набрал 25K stars, стал прибыльным в 2025. Во время SST команда строила terminal-first UIs и даже запустила Terminal — подписку на кофе через терминал ($100K продаж в первый год).
|
||||
|
||||
### Скандальная история: Fork и Split (2025)
|
||||
|
||||
- Оригинальный OpenCode создал **Kujtim Hoxha** на Go с Bubble Tea TUI
|
||||
- **Charm** (компания, создатель Bubble Tea) приобрела проект, наняла Kujtim
|
||||
- Dax Raad и Adam Doty (из SST) были major contributors, им не понравился ход
|
||||
- Обвинения: Charm переписал git history, удалил контрибуции, забанил критиков
|
||||
- **Результат:** Charm переименовал свою версию в **Crush**, а Dax/Adam сохранили бренд OpenCode под SST (anomalyco)
|
||||
- Fork полностью переписан с Go на **TypeScript + Bun** для использования Vercel AI SDK
|
||||
|
||||
### Скандал с Anthropic (январь 2026)
|
||||
|
||||
- Ранние версии OpenCode подделывали HTTP-заголовок `claude-code-20250219`, выдавая себя за Claude Code
|
||||
- 9 января 2026 Anthropic заблокировал сторонние tools от использования Claude OAuth
|
||||
- 19 февраля 2026 Anthropic обновил Terms of Service, запретив OAuth токены Free/Pro/Max в third-party tools
|
||||
- OpenCode удалил весь Claude OAuth код в тот же день
|
||||
- Запустили **OpenCode Zen** (pay-as-you-go gateway) и **OpenCode Black** ($200/мес, enterprise)
|
||||
- **18,000 новых stars за 2 недели** — controversy привлекла внимание
|
||||
|
||||
---
|
||||
|
||||
## 2. Поддержка 75+ провайдеров
|
||||
|
||||
**Подтверждено.** OpenCode использует [Models.dev](https://models.dev) + Vercel AI SDK для поддержки 75+ LLM-провайдеров.
|
||||
|
||||
### Ключевые провайдеры
|
||||
|
||||
| Провайдер | Детали |
|
||||
|-----------|--------|
|
||||
| OpenAI (GPT, Codex) | API key |
|
||||
| Anthropic (Claude) | API key (после блокировки OAuth) |
|
||||
| Google Gemini | API key + Vertex AI |
|
||||
| AWS Bedrock | IAM credentials |
|
||||
| Groq | API key |
|
||||
| Azure OpenAI | Enterprise endpoint |
|
||||
| OpenRouter | Pre-loaded models |
|
||||
| Ollama (local) | `opencode --model ollama/qwen2.5-coder:32b` |
|
||||
| GitHub Copilot | Copilot subscription (Pro+ для некоторых моделей) |
|
||||
| ChatGPT Plus/Pro | OAuth login |
|
||||
| Cloudflare AI Gateway | Unified billing, no per-provider keys |
|
||||
| SAP AI Core | 40+ models, enterprise platform |
|
||||
| GitLab | Agent Platform (18.8+) |
|
||||
| Deepseek | API key |
|
||||
| Local models | Any OpenAI-compatible endpoint |
|
||||
|
||||
### Как это работает
|
||||
|
||||
```
|
||||
User → OpenCode → AI SDK → Models.dev → Provider API → LLM Response
|
||||
```
|
||||
|
||||
- Models.dev — реестр моделей с метаданными
|
||||
- AI SDK (от Vercel) — универсальный SDK для вызова разных провайдеров
|
||||
- `/connect` команда — добавление credentials
|
||||
- `/models` команда — список доступных моделей
|
||||
- Config: можно назначить разные модели для разных agent-ролей (plan vs build)
|
||||
|
||||
### Монетизация через провайдеров
|
||||
|
||||
| Tier | Цена | Описание |
|
||||
|------|-------|----------|
|
||||
| Free | $0 | BYO API key или local models (Ollama) |
|
||||
| OpenCode Zen | Pay-per-token | Curated gateway, pass-through pricing |
|
||||
| OpenCode Black | $200/мес | Enterprise, multi-provider (sold out) |
|
||||
|
||||
---
|
||||
|
||||
## 3. Agent Teams: Multi-Agent Support
|
||||
|
||||
### Статус: Community-Implemented, NOT Core Feature
|
||||
|
||||
Важное уточнение: Agent Teams в OpenCode — это **community contribution**, а не встроенная core-фича (в отличие от Claude Code).
|
||||
|
||||
- **GitHub Issue [#12661](https://github.com/anomalyco/opencode/issues/12661)** — Feature request для native agent teams
|
||||
- **PRs #12730-12732** (dev branch) — community implementation (core, tools & routes, TUI)
|
||||
- **[opencode-ensemble](https://github.com/hueyexe/opencode-ensemble)** — SDK plugin для agent teams
|
||||
- **[opencode-workspace](https://github.com/kdcokenny/opencode-workspace)** — multi-agent orchestration harness
|
||||
|
||||
### Архитектура Agent Teams (community implementation)
|
||||
|
||||
#### Messaging: Two-Layer System
|
||||
|
||||
```
|
||||
Layer 1: Inbox (Source of Truth)
|
||||
team_inbox/<projectId>/<teamName>/<agentName>.jsonl
|
||||
Каждая строка: { id, from, text, timestamp, read }
|
||||
|
||||
Layer 2: Session Injection (Delivery)
|
||||
Message → injected as synthetic user message → LLM видит и обрабатывает
|
||||
```
|
||||
|
||||
**Ключевые отличия от Claude Code:**
|
||||
|
||||
| Аспект | Claude Code | OpenCode |
|
||||
|--------|-------------|----------|
|
||||
| Storage | JSON array (O(N) writes) | JSONL append-only (O(1)) |
|
||||
| Messaging | Polling JSON files | Event-driven auto-wake |
|
||||
| Communication | Leader-centric routing | Full mesh peer-to-peer |
|
||||
| Multi-model | Single provider only | Multiple providers per team |
|
||||
| Process model | 3 backends (in-process, tmux, iTerm2) | Single process |
|
||||
| State tracking | Implicit | Two-level state machines |
|
||||
|
||||
#### State Machines (Dual)
|
||||
|
||||
**Member Status (5 states):** `ready` → `busy` → `shutdown_requested` → `shutdown` (terminal), `error`
|
||||
- Guards: `guard: true` (prevents race conditions), `force: true` (crash recovery)
|
||||
|
||||
**Execution Status (10 states):** Fine-grained prompt loop position tracking
|
||||
|
||||
#### Peer-to-Peer Messaging
|
||||
|
||||
Любой teammate может отправить сообщение любому другому по имени — не только через lead. Lead фокусируется на orchestration, а не routing.
|
||||
|
||||
#### Sub-Agent Isolation
|
||||
|
||||
Team tools (`team_create`, `team_spawn`, `team_message`) запрещены для sub-agents через deny rules + tool visibility hiding. Sub-agents — одноразовые workers, их output не должен попадать в coordination channel.
|
||||
|
||||
### Доказано: Claude + Codex + Gemini в одной команде
|
||||
|
||||
**Тест 1: Architecture Drama (3 провайдера)**
|
||||
- GPT-5.3 Codex + Gemini 2.5 Pro + Claude Sonnet 4
|
||||
- Координация через один message bus
|
||||
- Claiming tasks из shared list
|
||||
- "Arguing about architecture" через peer-to-peer messaging
|
||||
|
||||
**Тест 2: Super Bowl Prediction (4 Claude Opus)**
|
||||
- Stats analyst + Betting analyst + Matchup analyst + Injury scout
|
||||
- Full-mesh topology
|
||||
- Atomic task claiming под concurrent access
|
||||
|
||||
**Тест 3: NFL Research (2 Gemini)**
|
||||
- Обнаружена проблема: Gemini генерировал ~50 одинаковых "task complete" сообщений в цикле
|
||||
|
||||
### Ограничения
|
||||
|
||||
- Agent teams пока на dev branch, не в stable release
|
||||
- Нет multi-caller support в core — субагент не знает, кто с ним говорит (кроме Parent)
|
||||
- Gemini имеет проблемы с message loop
|
||||
- Recovery при crash: нет auto-restart, user должен re-engage teammates
|
||||
|
||||
---
|
||||
|
||||
## 4. Architecture Deep Dive
|
||||
|
||||
### Двухъязычная система
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────┐
|
||||
│ User runs `opencode` │
|
||||
│ (single Bun-compiled binary) │
|
||||
└──────────────────┬───────────────────────────┘
|
||||
│
|
||||
┌────────▼─────────┐
|
||||
│ Bun Process │
|
||||
│ (TypeScript) │──── HTTP Server (API + SSE events)
|
||||
│ - LLM calls │ ▲
|
||||
│ - Tool exec │ │ OpenAPI SDK
|
||||
│ - Sessions │ │ (auto-generated by Stainless)
|
||||
│ - LSP client │ ┌────┴──────┐
|
||||
│ - Plugin system │ │ Go TUI │
|
||||
│ - MCP client │ │ (Client) │
|
||||
└──────────────────┘ └────────────┘
|
||||
│
|
||||
(Migrating to OpenTUI:
|
||||
Zig core + React/Solid/Vue)
|
||||
```
|
||||
|
||||
### Backend (TypeScript + Bun)
|
||||
|
||||
- **Runtime:** Bun (fast JavaScript runtime)
|
||||
- **Build:** `bun build .. --compile` — single executable
|
||||
- **HTTP Server:** API + SSE events для real-time updates
|
||||
- **Storage:** SQLite для persistent data
|
||||
- **LLM Communication:** Через Vercel AI SDK
|
||||
- **Tool Execution:** LLM решает когда вызвать tool, SDK вызывает `execute` функцию
|
||||
- **LSP Integration:** Отправляет `textDocument/didChange`, получает diagnostics, кормит LLM
|
||||
- **40+ event types:** Через GlobalBus, доставка через SSE
|
||||
|
||||
### Frontend (Go TUI → OpenTUI)
|
||||
|
||||
- **Текущий:** Go с Bubble Tea framework
|
||||
- **Мигрирует на:** [OpenTUI](https://github.com/anomalyco/opentui) — Zig core + TypeScript bindings
|
||||
- **OpenTUI:** React/SolidJS/Vue reconcilers, Bun exclusive (Node/Deno в процессе)
|
||||
- **Persistent sessions:** Сервер в background, TUI реконнектится после disconnect/sleep
|
||||
|
||||
### Client-Server Protocol
|
||||
|
||||
- **OpenAPI spec** → auto-generated SDK через Stainless
|
||||
- **3 official SDKs:** TypeScript, Go, Python
|
||||
- **SSE** для real-time events (40+ event types)
|
||||
- **Zero dependencies** в SDK
|
||||
|
||||
### Desktop App
|
||||
|
||||
- Beta на macOS, Windows, Linux
|
||||
- Также есть community [OpenGUI](https://dev.to/akemmanuel/i-built-a-native-desktop-gui-for-opencode-in-4-days-with-ai-p44) — Electron + React
|
||||
|
||||
### IDE Extensions
|
||||
|
||||
VS Code, Cursor, Zed, Windsurf, VSCodium + GitHub и GitLab integrations.
|
||||
|
||||
---
|
||||
|
||||
## 5. Built-in Tools
|
||||
|
||||
| Tool | Описание |
|
||||
|------|----------|
|
||||
| Shell | Выполнение bash команд |
|
||||
| Edit | Exact string replacement в файлах |
|
||||
| Write | Создание/перезапись файлов |
|
||||
| Read | Чтение файлов |
|
||||
| Grep | Regex поиск по codebase |
|
||||
| LSP | Code intelligence: definitions, references, hover, call hierarchy |
|
||||
|
||||
### Agents
|
||||
|
||||
| Agent | Доступ | Назначение |
|
||||
|-------|--------|------------|
|
||||
| **Build** (default) | Full access | Development work |
|
||||
| **Plan** | Read-only | Analysis, planning |
|
||||
| **Review** | Read-only + docs | Code review |
|
||||
| **Debug** | Bash + Read | Investigation |
|
||||
| **Docs** | File ops, no shell | Documentation |
|
||||
| **@general** | Subagent | Complex search/multistep |
|
||||
|
||||
---
|
||||
|
||||
## 6. MCP Support
|
||||
|
||||
**Полная поддержка MCP как client.** Feature request для MCP server mode ([#3306](https://github.com/sst/opencode/issues/3306)).
|
||||
|
||||
### Типы MCP серверов
|
||||
|
||||
1. **Local MCP Servers** — stdio-based communication, запускаются как local processes
|
||||
2. **Remote MCP Servers** — HTTP + OAuth 2.0 (Dynamic Client Registration RFC 7591)
|
||||
|
||||
### Конфигурация
|
||||
|
||||
```json
|
||||
// opencode.json
|
||||
{
|
||||
"mcp": {
|
||||
"sentry": {
|
||||
"command": "npx",
|
||||
"args": ["@sentry/mcp-server"],
|
||||
"env": { "SENTRY_AUTH_TOKEN": "{env:SENTRY_TOKEN}" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- Поддержка `{env:VAR}` и `{file:path}` для секретов
|
||||
- `enabled: false` для временного отключения
|
||||
- Auto-OAuth flow для remote servers
|
||||
- Tools автоматически доступны LLM наряду с built-in tools
|
||||
|
||||
### Предупреждение о Context
|
||||
|
||||
MCP tools добавляют контекст. GitHub MCP server, например, может быстро превысить context limit. Рекомендуется осторожность при выборе MCP серверов.
|
||||
|
||||
---
|
||||
|
||||
## 7. Plugin System & Extensibility
|
||||
|
||||
### Plugin Sources
|
||||
|
||||
1. **Directory plugins:** `.opencode/plugins/` (project) или `~/.config/opencode/plugins/` (global)
|
||||
2. **NPM packages:** в opencode.json, auto-install через Bun
|
||||
|
||||
### Hook Types
|
||||
|
||||
| Hook | Описание |
|
||||
|------|----------|
|
||||
| `tool.execute.before/after` | Перехват tool calls |
|
||||
| `session.created/updated` | Session lifecycle |
|
||||
| `message.*` | Message events |
|
||||
| `event` | System events (`session.idle`, `session.created`, etc.) |
|
||||
| `experimental.session.compacting` | Inject context before compaction |
|
||||
| `chat.message` | Modify messages before LLM |
|
||||
|
||||
### Custom Tools
|
||||
|
||||
Plugin tools можно определить — они доступны LLM наряду с built-in tools. Если имя совпадает с built-in, plugin tool имеет приоритет.
|
||||
|
||||
### Notable Community Plugins
|
||||
|
||||
- **EnvSitter** — блокирует чтение `.env*` файлов
|
||||
- **Agent Ensemble** — agent teams orchestration
|
||||
- **Persistent Memory** — self-editable memory blocks (как Letta)
|
||||
- **Annotation UI** — перехватывает plan mode, открывает browser UI
|
||||
- **Worktree Isolation** — git worktree per agent
|
||||
|
||||
---
|
||||
|
||||
## 8. What Can We Learn From It?
|
||||
|
||||
### Архитектурные идеи для Claude Agent Teams UI
|
||||
|
||||
1. **Client/Server разделение** — persistent sessions, reconnect после disconnect. Наш Electron-подход можно дополнить server mode для remote access.
|
||||
|
||||
2. **JSONL append-only inbox** — O(1) writes vs O(N) JSON array. **Мы уже используем JSONL для session files**, но team inbox в Claude Code — JSON array. Можно предложить Anthropic JSONL формат.
|
||||
|
||||
3. **Event-driven vs Polling** — OpenCode использует SSE + event bus вместо file polling. Мы используем file watching с debounce (100ms). Event-driven подход быстрее и чище.
|
||||
|
||||
4. **Peer-to-Peer messaging** — в Claude Code все идет через lead. OpenCode показывает, что full-mesh topology работает. **Мы уже отключили relay для teammate DMs** (см. CLAUDE.md), что близко к peer-to-peer.
|
||||
|
||||
5. **Two-level state machines** — member status (coarse) + execution status (fine). Может улучшить наш UI для отображения состояния agents.
|
||||
|
||||
6. **Plugin system** — hooks для tool.execute, session events, compaction. Потенциал для нашего MCP integration.
|
||||
|
||||
7. **Multi-provider teams** — самая уникальная фича. Claude Code не может этого. Для нашего UI это не актуально (мы визуализируем Claude Code teams), но показывает направление рынка.
|
||||
|
||||
8. **Auto-wake** — когда teammate отправляет сообщение idle agent'у, он автоматически "просыпается". В Claude Code нужен manual re-engage.
|
||||
|
||||
---
|
||||
|
||||
## 9. Competitor or Integration Partner?
|
||||
|
||||
### Как конкурент нашему продукту
|
||||
|
||||
| Аспект | OpenCode | Claude Agent Teams UI (мы) |
|
||||
|--------|----------|---------------------------|
|
||||
| **Что это** | Coding agent | UI для управления agent teams |
|
||||
| **Kanban** | Нет (только community: opencode-kanban, VibeKanban) | Встроенный kanban board |
|
||||
| **Code Review** | Нет diff view в TUI | Diff view per task |
|
||||
| **Team Management** | CLI-based, нет visual management | Visual kanban + real-time status |
|
||||
| **Notifications** | Нет | Встроенные уведомления |
|
||||
| **Session Analysis** | Базовый | Deep analysis (bash, reasoning, subagents) |
|
||||
| **Context Monitoring** | Нет | Token usage по категориям |
|
||||
| **Direct Messaging** | Через CLI | Visual DM interface |
|
||||
|
||||
**Вывод: OpenCode — НЕ прямой конкурент.** Они coding agent, мы — UI для управления agent teams. OpenCode больше конкурирует с Claude Code CLI, а не с нашим UI.
|
||||
|
||||
### Как потенциальный integration partner
|
||||
|
||||
OpenCode имеет **полноценный SDK** (TypeScript, Go, Python) и **SSE events**. Теоретически мы могли бы:
|
||||
|
||||
1. **Добавить OpenCode backend** — управлять OpenCode sessions через их SDK вместо/параллельно Claude Code
|
||||
2. **Визуализировать OpenCode teams** — их agent teams используют JSONL inbox, мы могли бы парсить
|
||||
3. **Multi-agent kanban** — один kanban для Claude Code + OpenCode agents
|
||||
4. **Cross-provider orchestration** — использовать наш UI для управления mixed teams (Claude через Claude Code, GPT/Gemini через OpenCode)
|
||||
|
||||
**Риски интеграции:**
|
||||
- OpenCode agent teams — community feature, не stable API
|
||||
- Совершенно другая архитектура (HTTP SDK vs CLI process management)
|
||||
- Потребуется значительная работа по адаптации
|
||||
|
||||
---
|
||||
|
||||
## 10. Unique Features vs Claude Code
|
||||
|
||||
| Feature | OpenCode | Claude Code |
|
||||
|---------|----------|-------------|
|
||||
| **Model freedom** | 75+ providers, local models | Only Anthropic |
|
||||
| **Open source** | MIT license, full source | Closed source |
|
||||
| **Desktop app** | Beta (macOS/Win/Linux) | Нет |
|
||||
| **IDE extensions** | VS Code, Cursor, Zed, Windsurf | Нет (только CLI) |
|
||||
| **Plugin system** | Hooks, custom tools, npm plugins | Hooks (bash-based) |
|
||||
| **Persistent sessions** | Client/server, reconnect | Нет |
|
||||
| **Agent types** | Build/Plan/Review/Debug/Docs + custom | One agent + subagents |
|
||||
| **SDK** | TypeScript/Go/Python, OpenAPI spec | Нет public SDK |
|
||||
| **LSP integration** | Built-in, feeds diagnostics to LLM | Нет |
|
||||
| **Agent Teams** | Community (multi-provider!) | Native (single provider) |
|
||||
| **Context compaction** | Supports plugin hook | Automatic |
|
||||
| **Pricing** | Free + BYO API key | $20/mo Claude Pro minimum |
|
||||
| **Accuracy** | Varies by model | SWE-bench Pro 57.5% |
|
||||
| **Adoption** | 5M MAU, 126K stars | 4% of GitHub commits, 135K/day |
|
||||
|
||||
### Что уникально у OpenCode
|
||||
|
||||
1. **Model agnosticism** — designed from day one, не afterthought
|
||||
2. **Client/server architecture** — sessions persist, remote control possible
|
||||
3. **Multi-provider agent teams** — Claude+Codex+Gemini в одной команде
|
||||
4. **Plugin ecosystem** — rich hook system, npm packages, custom tools
|
||||
5. **3 official SDKs** — TypeScript, Go, Python
|
||||
6. **OpenTUI** — собственный TUI framework на Zig
|
||||
|
||||
### Что уникально у Claude Code (и у нас)
|
||||
|
||||
1. **Native agent teams** — core feature, не community plugin
|
||||
2. **SWE-bench accuracy** — лучшие результаты на бенчмарках
|
||||
3. **4% GitHub commits** — доминирует в реальном использовании
|
||||
4. **Stream-json protocol** — надежный IPC для agent coordination
|
||||
5. **Kanban board** (наш UI) — НИКТО не имеет визуального kanban для agent teams
|
||||
|
||||
---
|
||||
|
||||
## Summary & Key Takeaways
|
||||
|
||||
### Факты (verified)
|
||||
|
||||
- OpenCode — реальный и крупный проект: ~126-129K stars, 800+ contributors, 5M MAU
|
||||
- 75+ providers — подтверждено через Models.dev + AI SDK
|
||||
- MIT license — подтверждено
|
||||
- Agent teams с multi-provider — доказано (community implementation)
|
||||
- TypeScript (Bun) + Go + Zig architecture — подтверждено
|
||||
- MCP client support — полноценный
|
||||
- Desktop app + IDE extensions — beta, но работает
|
||||
- Plugin system — rich, с hooks и custom tools
|
||||
|
||||
### Риски и concerns
|
||||
|
||||
- Agent teams — community feature, не stable, на dev branch
|
||||
- Скандал с Anthropic OAuth — показывает этические вопросы
|
||||
- Fork controversy — community split может повлиять на долгосрочную стабильность
|
||||
- Gemini message loop bug — multi-provider teams нестабильны
|
||||
- OpenCode Black ($200/мес) sold out — бизнес-модель не ясна
|
||||
|
||||
### Relevance для нашего продукта
|
||||
|
||||
- **Прямая конкуренция: НЕТ** — мы UI для team management, они coding agent
|
||||
- **Косвенная конкуренция: ДА** — community tools (opencode-kanban, VibeKanban) пытаются решить ту же проблему
|
||||
- **Потенциал интеграции: СРЕДНИЙ** — SDK доступен, но архитектура сильно отличается
|
||||
- **Наше преимущество сохраняется:** Kanban board для agent teams нет НИ У КОГО, включая OpenCode
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [anomalyco/opencode (GitHub)](https://github.com/anomalyco/opencode)
|
||||
- [opencode.ai](https://opencode.ai/)
|
||||
- [OpenCode Docs](https://opencode.ai/docs/)
|
||||
- [Building Agent Teams in OpenCode (DEV Community)](https://dev.to/uenyioha/porting-claude-codes-agent-teams-to-opencode-4hol)
|
||||
- [How OpenCode went from zero to titan (Dev Genius)](https://blog.devgenius.io/how-opencode-went-from-zero-to-titan-in-eight-months-dcdcd8ff5572)
|
||||
- [OpenCode background story (TFN)](https://techfundingnews.com/opencode-the-background-story-on-the-most-popular-open-source-coding-agent-in-the-world/)
|
||||
- [How Coding Agents Actually Work: Inside OpenCode](https://cefboud.com/posts/coding-agents-internals-opencode-deepdive/)
|
||||
- [OpenCode vs Claude Code (MorphLLM)](https://www.morphllm.com/comparisons/opencode-vs-claude-code)
|
||||
- [OpenCode vs Claude Code (DataCamp)](https://www.datacamp.com/blog/opencode-vs-claude-code)
|
||||
- [OpenCode vs Anthropic Legal Controversy](https://www.shareuhack.com/en/posts/opencode-anthropic-legal-controversy-2026)
|
||||
- [OpenCode MCP Servers docs](https://opencode.ai/docs/mcp-servers/)
|
||||
- [OpenCode Plugins docs](https://opencode.ai/docs/plugins/)
|
||||
- [OpenCode Agents docs](https://opencode.ai/docs/agents/)
|
||||
- [OpenCode Models docs](https://opencode.ai/docs/models/)
|
||||
- [OpenCode Providers docs](https://opencode.ai/docs/providers/)
|
||||
- [OpenTUI (GitHub)](https://github.com/anomalyco/opentui)
|
||||
- [opencode-ensemble (GitHub)](https://github.com/hueyexe/opencode-ensemble)
|
||||
- [opencode-kanban (GitHub)](https://github.com/qrafty-ai/opencode-kanban)
|
||||
- [Vibe Kanban](https://vibekanban.com/)
|
||||
- [awesome-opencode (GitHub)](https://github.com/awesome-opencode/awesome-opencode)
|
||||
284
docs/research/orchestrator-as-foundation.md
Normal file
284
docs/research/orchestrator-as-foundation.md
Normal file
|
|
@ -0,0 +1,284 @@
|
|||
# Оценка: внешний оркестратор как фундамент вместо собственного agent management
|
||||
|
||||
**Дата**: 2026-03-25
|
||||
**Вопрос**: стоит ли взять готовый multi-agent оркестратор и посадить наш Electron UI сверху, вместо того чтобы развивать собственный TeamProvisioningService?
|
||||
|
||||
---
|
||||
|
||||
## 1. Что мы бы заменяли (наш текущий стек)
|
||||
|
||||
### Собственная инфраструктура
|
||||
|
||||
| Компонент | Файлы | LOC | Что делает |
|
||||
|-----------|-------|-----|------------|
|
||||
| `TeamProvisioningService.ts` | 1 | ~8000 | Полный lifecycle команды: создание, запуск, stream-json протокол, preflight, stdin relay, tool approval, stall detection, cross-team messaging |
|
||||
| `agent-teams-controller/` | ~20 модулей | ~4050 | Kanban store, task management, review workflow, cross-team protocol, runtime helpers, message store, process store |
|
||||
| Остальные team сервисы | 38 файлов | ~13200 | TeamConfigReader, TeamInboxReader/Writer, TeamTaskReader/Writer, TeamKanbanManager, TeamMcpConfigBuilder, CascadeGuard, CrossTeamService, ReviewApplier, MemberStatsComputer, TeamBackupService и др. |
|
||||
| `childProcess.ts` | 1 | ~220 | spawnCli/execCli с Windows fallback, process tree kill |
|
||||
| MCP server tools | 8 файлов | ~500 | taskTools, kanbanTools, reviewTools, messageTools, processTools, runtimeTools, crossTeamTools |
|
||||
| **ИТОГО** | ~68 файлов | **~26000 LOC** | |
|
||||
|
||||
### Ключевые точки spawn (spawnCli вызовы)
|
||||
|
||||
- `TeamProvisioningService.ts` — 4 точки: create team, launch team, launch member, DM relay
|
||||
- `CliInstallerService.ts` — install CLI
|
||||
- `ScheduledTaskExecutor.ts` — scheduled tasks
|
||||
- `McpHealthDiagnosticsService.ts`, `PluginInstallService.ts`, `McpInstallService.ts` — execCli для MCP/plugin операций
|
||||
|
||||
### Что уникально в нашей реализации
|
||||
|
||||
1. **stream-json протокол** — двусторонний, lead читает stdin, teammates читают inbox
|
||||
2. **Tool approval system** — перехват tool_use запросов, auto-approve по правилам, UI промпт
|
||||
3. **Cross-team communication** — structured TaskRef, inbox files, cross-team MCP tools
|
||||
4. **Kanban + code review** — 5-column board, diff view, approve/request_changes workflow
|
||||
5. **MCP config builder** — передача `--mcp-config` с наследованием для teammates
|
||||
6. **SIGKILL-only kill** — предотвращение cleanup CLI, который удаляет team файлы
|
||||
7. **Context monitoring** — token usage tracking по категориям
|
||||
|
||||
---
|
||||
|
||||
## 2. Оценка кандидатов
|
||||
|
||||
### 2.1 MCO (mco-org/mco)
|
||||
|
||||
**GitHub**: https://github.com/mco-org/mco
|
||||
**Stars**: ~249 | **Лицензия**: MIT | **Язык**: TypeScript (CLI)
|
||||
**npm**: `@tt-a1i/mco`
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Используется как библиотека? | **НЕТ** — только CLI. Нет programmatic API для import. |
|
||||
| Inter-agent communication? | Частично — агенты диспатчат задачи через MCO CLI, но нет inbox/messaging системы |
|
||||
| MCP поддержка? | Да — может работать как MCP server |
|
||||
| Что бы мы СОХРАНИЛИ? | Всё UI, kanban, review, context tracking |
|
||||
| Что бы мы ЗАМЕНИЛИ? | Только dispatch логику (4 spawnCli точки), и то частично |
|
||||
| Effort интеграции | **Высокий** — MCO не даёт API, пришлось бы обёртывать CLI вызовы |
|
||||
| Риск зависимости | **Средний** — 249 stars, 1 основной автор |
|
||||
|
||||
**Вердикт**: MCO решает другую задачу (dispatch к разным CLI), а не управление командой. У нас уже есть более продвинутая система.
|
||||
- Надёжность решения: **3/10**
|
||||
- Уверенность в оценке: **8/10**
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Overstory (jayminwest/overstory)
|
||||
|
||||
**GitHub**: https://github.com/jayminwest/overstory
|
||||
**Stars**: ~1100 | **Лицензия**: MIT | **Язык**: TypeScript (Bun-native)
|
||||
**npm**: `@os-eco/overstory-cli`
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Используется как библиотека? | Частично — есть pluggable AgentRuntime интерфейс, но **ТРЕБУЕТ BUN** (не Node.js/Electron) |
|
||||
| Inter-agent communication? | **Да** — SQLite mail system, 8 типов сообщений, WAL mode, broadcast |
|
||||
| MCP поддержка? | Упоминается, но без деталей |
|
||||
| Зависимости | **Bun v1.0+, tmux, git** — все три обязательны |
|
||||
| Что бы мы СОХРАНИЛИ? | UI, kanban, review, context tracking, MCP server |
|
||||
| Что бы мы ЗАМЕНИЛИ? | TeamProvisioningService, inbox system, process management |
|
||||
| Effort интеграции | **КРИТИЧЕСКИЙ** — Bun runtime несовместим с Electron (Node.js). Потребуется форк или полный переписывание на Node.js |
|
||||
| Риск зависимости | **Высокий** — 1 автор, Bun lock-in, tmux dependency |
|
||||
|
||||
**Вердикт**: Архитектурно интересен (SQLite mail, pluggable runtimes, watchdog), но **Bun dependency — dealbreaker** для Electron-приложения. tmux dependency тоже проблема (нет на Windows).
|
||||
- Надёжность решения: **2/10**
|
||||
- Уверенность в оценке: **9/10**
|
||||
|
||||
---
|
||||
|
||||
### 2.3 ComposioHQ/agent-orchestrator
|
||||
|
||||
**GitHub**: https://github.com/ComposioHQ/agent-orchestrator
|
||||
**Stars**: ~5400 | **Лицензия**: MIT | **Язык**: TypeScript (pnpm monorepo)
|
||||
**npm**: `@composio/ao` (CLI)
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Используется как библиотека? | **Условно** — monorepo с packages, но core не опубликован как отдельный npm пакет `@composio/ao-core`. Нет документации по programmatic API. |
|
||||
| Inter-agent communication? | **Нет прямой** — агенты изолированы в worktrees, координация через dashboard/server |
|
||||
| MCP поддержка? | Не упоминается |
|
||||
| Зависимости | tmux, Next.js dashboard (порт 3000) |
|
||||
| Plugin architecture | **Сильная** — 8 swappable slots (Runtime, Agent, Workspace, Tracker, SCM, Notifier, Terminal, Lifecycle) |
|
||||
| Что бы мы СОХРАНИЛИ? | Kanban UI, review, context tracking, cross-team messaging, MCP tools |
|
||||
| Что бы мы ЗАМЕНИЛИ? | Process spawning, workspace isolation |
|
||||
| Effort интеграции | **Высокий** — нет published API, потребуется fork monorepo, вырезание Next.js dashboard, адаптация под Electron IPC |
|
||||
| Риск зависимости | **Средний** — 5.4K stars, Composio (коммерческая компания) за спиной, но agent-orchestrator =/= их core business |
|
||||
|
||||
**Вердикт**: Самый продвинутый из кандидатов. Plugin architecture — то что нужно. НО: нет published programmatic API, нет inter-agent messaging (мы это уже имеем), требует tmux, и dashboard на Next.js конфликтует с нашим Electron. Интеграция = фактически форк.
|
||||
- Надёжность решения: **4/10**
|
||||
- Уверенность в оценке: **8/10**
|
||||
|
||||
---
|
||||
|
||||
### 2.4 MetaSwarm (dsifry/metaswarm)
|
||||
|
||||
**GitHub**: https://github.com/dsifry/metaswarm
|
||||
**Stars**: ~148 | **Лицензия**: MIT | **Язык**: TypeScript/JS (skills + commands)
|
||||
**npm**: `metaswarm` (npx installer)
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Используется как библиотека? | **НЕТ** — это framework из skills/commands/hooks, инжектируемый в CLAUDE.md. Не importable. |
|
||||
| Inter-agent communication? | Через Claude Code Team Mode (нативный) |
|
||||
| MCP поддержка? | Нет собственной — использует нативный Claude Code |
|
||||
| Что бы мы ЗАМЕНИЛИ? | Ничего — это workflow methodology, не runtime |
|
||||
| Effort интеграции | **Неприменимо** — это не backend, это набор CLAUDE.md инструкций и скриптов |
|
||||
| Риск зависимости | **Высокий** — 148 stars, 2 контрибьютора, последний коммит feb 2026 |
|
||||
|
||||
**Вердикт**: MetaSwarm — это не оркестратор в техническом смысле. Это structured workflow (skills, personas, phases), который инжектируется в prompt. Не подходит как backend.
|
||||
- Надёжность решения: **1/10**
|
||||
- Уверенность в оценке: **9/10**
|
||||
|
||||
---
|
||||
|
||||
### 2.5 ORCH (oxgeneral/ORCH)
|
||||
|
||||
**GitHub**: https://github.com/oxgeneral/ORCH (404 на момент проверки, возможно приватный)
|
||||
**Website**: https://www.orch.one
|
||||
**Stars**: Неизвестно | **Лицензия**: MIT | **Язык**: TypeScript
|
||||
**npm**: `@oxgeneral/orch` (GitHub Packages registry)
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Используется как библиотека? | **НЕТ** — CLI-only (`npm i -g @oxgeneral/orch`). Нет programmatic API. |
|
||||
| Inter-agent communication? | **Да** — direct messaging + broadcast + shared key-value store |
|
||||
| MCP поддержка? | Не упоминается |
|
||||
| State machine | task states: todo → in_progress → review → done |
|
||||
| Зависимости | git worktrees, TUI (терминал) |
|
||||
| Что бы мы ЗАМЕНИЛИ? | Process management, state machine, messaging |
|
||||
| Effort интеграции | **Высокий** — CLI-only, GitHub Packages registry (не стандартный npm), GitHub 404 |
|
||||
| Риск зависимости | **КРИТИЧЕСКИЙ** — GitHub repo недоступен (404), 1 автор |
|
||||
|
||||
**Вердикт**: Архитектурно интересен (DDD, state machine, 987 тестов), но **GitHub repo 404** — красный флаг. CLI-only без programmatic API. Нельзя рассматривать как зависимость.
|
||||
- Надёжность решения: **1/10**
|
||||
- Уверенность в оценке: **7/10** (7 потому что repo недоступен, не можем полноценно проверить)
|
||||
|
||||
---
|
||||
|
||||
### 2.6 conductor-oss (charannyk06/conductor-oss)
|
||||
|
||||
**GitHub**: https://github.com/charannyk06/conductor-oss
|
||||
**Stars**: ~14 | **Лицензия**: MIT | **Язык**: Rust (backend) + TypeScript (Next.js frontend)
|
||||
**Adapters**: 10 (Claude Code, Codex, Gemini, Qwen, Amp, Cursor CLI, OpenCode, Droid, Copilot, CCR)
|
||||
|
||||
| Критерий | Оценка |
|
||||
|----------|--------|
|
||||
| Используется как библиотека? | **Частично** — Rust binary + HTTP API (port 4747). Можно использовать API. |
|
||||
| Inter-agent communication? | Через orchestrator server |
|
||||
| MCP поддержка? | **Да** — `mcp-server` команда, stdio transport |
|
||||
| Dashboard | Next.js (порт 3000) — конфликт с нашим Electron |
|
||||
| Что бы мы ЗАМЕНИЛИ? | Agent spawning, workspace isolation, adapter layer |
|
||||
| Что бы мы СОХРАНИЛИ? | Всё UI, kanban, review, messaging, context tracking |
|
||||
| Effort интеграции | **Средний-Высокий** — HTTP API есть, но Rust binary нужно распространять с Electron, Next.js dashboard лишний |
|
||||
| Риск зависимости | **КРИТИЧЕСКИЙ** — 14 stars, 1 автор, Rust dependency в TypeScript/Electron проекте |
|
||||
|
||||
**Вердикт**: HTTP API делает интеграцию возможной, 10 адаптеров впечатляют. НО: 14 stars, Rust sidecar binary для Electron — серьёзная сложность в packaging и distribution. Проект слишком молодой.
|
||||
- Надёжность решения: **2/10**
|
||||
- Уверенность в оценке: **8/10**
|
||||
|
||||
---
|
||||
|
||||
## 3. Сводная таблица
|
||||
|
||||
| Оркестратор | Stars | Library? | Inter-agent msg | MCP | Electron-совместим | Effort | Риск |
|
||||
|-------------|-------|----------|-----------------|-----|-------------------|--------|------|
|
||||
| **MCO** | 249 | CLI only | Partial | Yes | Partial | High | Medium |
|
||||
| **Overstory** | 1.1K | Bun only | SQLite mail | Partial | **NO (Bun)** | Critical | High |
|
||||
| **Composio AO** | 5.4K | No published API | No direct | No | Partial (tmux) | High | Medium |
|
||||
| **MetaSwarm** | 148 | No (skills) | Native CC | No | N/A | N/A | High |
|
||||
| **ORCH** | ? | CLI only | Yes | No | No (TUI) | High | **Critical** |
|
||||
| **conductor-oss** | 14 | HTTP API | Via server | Yes | Partial (Rust) | Medium-High | **Critical** |
|
||||
|
||||
---
|
||||
|
||||
## 4. Что конкретно нам дал бы внешний оркестратор
|
||||
|
||||
### Потенциальная ценность
|
||||
1. **Multi-runtime support** — запуск не только Claude Code, но и Codex, Gemini, Aider
|
||||
2. **Git worktree isolation** — у нас нет, но и не нужен (Claude Code сам управляет файлами)
|
||||
3. **Adapters pattern** — абстракция спавна разных CLI
|
||||
|
||||
### Что мы УЖЕ имеем и ни один оркестратор не даёт
|
||||
1. **stream-json bidirectional protocol** — уникальная интеграция с Claude Code Agent Teams
|
||||
2. **Tool approval UI** — перехват и approve/reject tool calls в реальном времени
|
||||
3. **Cross-team structured messaging** — TaskRef, zero-width metadata encoding
|
||||
4. **Kanban с code review** — diff view, approve/request_changes per task
|
||||
5. **Context monitoring** — 6-category token tracking
|
||||
6. **MCP server with 7 tool groups** — kanban, tasks, review, messages, processes, runtime, cross-team
|
||||
7. **Post-compact context recovery** — восстановление инструкций после compaction
|
||||
8. **SIGKILL team kill protocol** — предотвращение file cleanup
|
||||
9. **Cascading guard** — предотвращение cascade team deletion
|
||||
|
||||
---
|
||||
|
||||
## 5. Ключевой вопрос: стоит ли зависеть от внешнего оркестратора?
|
||||
|
||||
### Аргументы ЗА интеграцию
|
||||
- Multi-runtime support (Codex, Gemini, Aider) без написания адаптеров
|
||||
- Потенциально меньше кода для поддержки
|
||||
- Community contributions и bug fixes
|
||||
|
||||
### Аргументы ПРОТИВ (перевешивают)
|
||||
|
||||
1. **Ни один оркестратор не имеет programmatic library API для embedding в Electron**
|
||||
- Все либо CLI-only, либо CLI + собственный dashboard
|
||||
- Интеграция = обёртка над CLI вызовами или fork — то есть по сути мы сами пишем адаптер
|
||||
|
||||
2. **Наша интеграция глубже любого оркестратора**
|
||||
- stream-json протокол, tool approval, cross-team refs — этого нет НИ У КОГО
|
||||
- Мы бы потеряли эти фичи при переходе на внешний backend
|
||||
|
||||
3. **Несовместимость со стеком**
|
||||
- Bun (Overstory) vs Node.js/Electron
|
||||
- Rust sidecar (conductor-oss) — packaging nightmare
|
||||
- tmux (Composio, Overstory) — нет на Windows
|
||||
- Next.js dashboards — дублирование с нашим Electron UI
|
||||
|
||||
4. **Стоимость интеграции >= стоимость написания адаптера**
|
||||
- Даже для лучшего кандидата (Composio AO) нужен fork monorepo + выпиливание Next.js + адаптация под IPC
|
||||
- Это ~2-4 недели работы с непредсказуемым результатом
|
||||
- Наш собственный adapter layer для нового CLI = ~200-500 LOC (1-2 дня)
|
||||
|
||||
5. **Риск зависимости**
|
||||
- Большинство проектов < 6 месяцев, 1-2 автора
|
||||
- Composio AO (5.4K stars) — самый живой, но agent-orchestrator != core business Composio
|
||||
- Если проект умирает — мы на форке без community
|
||||
|
||||
---
|
||||
|
||||
## 6. Рекомендация
|
||||
|
||||
### Вердикт: **НЕ ИСПОЛЬЗОВАТЬ внешний оркестратор как фундамент**
|
||||
|
||||
Стоимость интеграции выше, чем написание собственного тонкого adapter layer.
|
||||
|
||||
### Что стоит ЗАИМСТВОВАТЬ (паттерны, не код)
|
||||
|
||||
| Паттерн | Источник | Применение у нас |
|
||||
|---------|----------|-----------------|
|
||||
| Plugin architecture (8 slots) | Composio AO | Вынести agent adapter в интерфейс `AgentRuntime` для будущей multi-runtime поддержки |
|
||||
| SQLite mail system | Overstory | Рассмотреть для замены JSON inbox files (производительность) |
|
||||
| State machine для tasks | ORCH | У нас уже есть kanban states, но можно формализовать transitions |
|
||||
| AgentRuntime interface | Overstory | `{ spawn, configure, detectReadiness, parseTranscript }` — хороший контракт |
|
||||
| Tiered watchdog | Overstory | Stall detection → AI triage → monitor agent |
|
||||
|
||||
### Рекомендуемый план
|
||||
|
||||
1. **Сейчас**: оставить текущую архитектуру, она работает и покрывает наш use case
|
||||
2. **Если нужен multi-runtime**: написать `AgentRuntime` интерфейс (~200 LOC) + адаптер для каждого CLI (~300-500 LOC)
|
||||
3. **Если нужна масштабируемость messaging**: рассмотреть миграцию с JSON inbox → SQLite WAL
|
||||
4. **Мониторить** Composio AO — если опубликуют `@composio/ao-core` как npm library с programmatic API, пересмотреть решение
|
||||
|
||||
- **Надёжность рекомендации**: 8/10
|
||||
- **Уверенность**: 9/10
|
||||
|
||||
---
|
||||
|
||||
## Источники
|
||||
|
||||
- [MCO (mco-org/mco)](https://github.com/mco-org/mco) — 249 stars, CLI-only orchestrator
|
||||
- [Overstory (jayminwest/overstory)](https://github.com/jayminwest/overstory) — 1.1K stars, Bun + SQLite + tmux
|
||||
- [Composio Agent Orchestrator](https://github.com/ComposioHQ/agent-orchestrator) — 5.4K stars, plugin architecture
|
||||
- [MetaSwarm (dsifry/metaswarm)](https://github.com/dsifry/metaswarm) — 148 stars, workflow framework
|
||||
- [ORCH (orch.one)](https://www.orch.one/) — CLI runtime, GitHub repo 404
|
||||
- [conductor-oss (markdown-native)](https://github.com/charannyk06/conductor-oss) — 14 stars, Rust + 10 adapters
|
||||
- [Awesome Agent Orchestrators](https://github.com/andyrewlee/awesome-agent-orchestrators) — каталог 80+ инструментов
|
||||
- [Composio Architecture Design](https://github.com/ComposioHQ/agent-orchestrator/blob/main/artifacts/architecture-design.md)
|
||||
376
docs/research/sdk-vs-cli-comparison.md
Normal file
376
docs/research/sdk-vs-cli-comparison.md
Normal file
|
|
@ -0,0 +1,376 @@
|
|||
# SDK vs CLI Direct Spawn: Honest Comparison
|
||||
|
||||
**Date:** 2026-03-25
|
||||
**Status:** Research complete
|
||||
**Verdict:** SDKs are NOT limiting — they ARE the CLI with a nicer API, plus extras. But there are real tradeoffs.
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
All three SDKs (Claude Agent SDK, Codex SDK, Gemini CLI SDK) **spawn the CLI as a child process** under the hood and communicate via stdin/stdout JSON protocol. The SDK IS the CLI — it just wraps `child_process.spawn()` with a typed API. There is **no functional limitation** vs direct spawn, because the SDK literally does the same thing. However, there is a **real performance overhead** (~12s per `query()` call for Claude) and some **CLI-only features** (Agent Teams for Claude) that require workarounds.
|
||||
|
||||
---
|
||||
|
||||
## 1. Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`)
|
||||
|
||||
### Architecture: How It Works Under the Hood
|
||||
|
||||
The SDK **bundles `cli.js`** directly inside the npm package. When you call `query()`, it spawns a Node.js process running this bundled CLI with `--input-format stream-json --output-format stream-json --verbose`. Communication is via NDJSON over stdin/stdout.
|
||||
|
||||
> "The SDK code actually bundles a cli.js file directly — which contains the entire Claude Code CLI."
|
||||
> — [Claude Agent SDK Pitfalls](https://liruifengv.com/posts/claude-agent-sdk-pitfalls-en/)
|
||||
|
||||
**Key insight:** The `spawnClaudeCodeProcess` option lets you provide a completely custom spawn function. Node's `ChildProcess` already satisfies the `SpawnedProcess` interface. This means you can override HOW the CLI is spawned — Docker, VM, remote, whatever.
|
||||
|
||||
### Complete Options Reference (from [official docs](https://platform.claude.com/docs/en/agent-sdk/typescript))
|
||||
|
||||
| Option | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `model` | `string` | Claude model to use |
|
||||
| `cwd` | `string` | Working directory |
|
||||
| `env` | `Record<string, string>` | Environment variables |
|
||||
| `systemPrompt` | `string \| preset` | Custom or `claude_code` preset |
|
||||
| `allowedTools` | `string[]` | Auto-approve tools |
|
||||
| `disallowedTools` | `string[]` | Deny tools (checked first, overrides everything) |
|
||||
| `mcpServers` | `Record<string, McpServerConfig>` | MCP server configs (stdio, SSE, HTTP, in-process SDK) |
|
||||
| `strictMcpConfig` | `boolean` | Only use MCP servers from this config |
|
||||
| `settingSources` | `SettingSource[]` | `["user", "project", "local"]` to match CLI behavior |
|
||||
| `permissionMode` | `PermissionMode` | `default`, `acceptEdits`, `bypassPermissions`, `plan`, `dontAsk` |
|
||||
| `canUseTool` | `Function` | Custom permission callback |
|
||||
| `agents` | `Record<string, AgentDefinition>` | Programmatic subagents |
|
||||
| `hooks` | `Partial<Record<HookEvent, ...>>` | Programmatic hook callbacks |
|
||||
| `plugins` | `SdkPluginConfig[]` | Load custom plugins |
|
||||
| `maxTurns` | `number` | Max agentic turns |
|
||||
| `maxBudgetUsd` | `number` | Budget cap |
|
||||
| `effort` | `'low'\|'medium'\|'high'\|'max'` | Thinking depth |
|
||||
| `thinking` | `ThinkingConfig` | Adaptive thinking config |
|
||||
| `betas` | `SdkBeta[]` | Beta features (e.g., `context-1m-2025-08-07`) |
|
||||
| `includePartialMessages` | `boolean` | Stream partial responses |
|
||||
| `outputFormat` | `{ type: 'json_schema', schema }` | Structured output |
|
||||
| `spawnClaudeCodeProcess` | `Function` | Custom spawn function |
|
||||
| `pathToClaudeCodeExecutable` | `string` | Custom CLI path |
|
||||
| `executable` | `'bun'\|'deno'\|'node'` | JS runtime |
|
||||
| `executableArgs` | `string[]` | Runtime args |
|
||||
| **`extraArgs`** | **`Record<string, string\|null>`** | **ANY arbitrary CLI flags** |
|
||||
| `debug` | `boolean` | Debug mode |
|
||||
| `debugFile` | `string` | Debug log file |
|
||||
| `sandbox` | `SandboxSettings` | Sandbox config |
|
||||
| `persistSession` | `boolean` | Disable session persistence |
|
||||
| `resume` | `string` | Resume session by ID |
|
||||
| `forkSession` | `boolean` | Fork on resume |
|
||||
| `enableFileCheckpointing` | `boolean` | File change tracking |
|
||||
| `fallbackModel` | `string` | Fallback model |
|
||||
| `promptSuggestions` | `boolean` | Emit prompt suggestions |
|
||||
| `stderr` | `Function` | Stderr callback |
|
||||
|
||||
### Feature Comparison: SDK vs CLI Direct
|
||||
|
||||
| Feature | CLI Direct | SDK | Notes |
|
||||
|---------|-----------|-----|-------|
|
||||
| MCP config | `--mcp-config '{...}'` | `mcpServers: {...}` | SDK has typed config + in-process MCP servers (SDK advantage) |
|
||||
| Strict MCP | `--strict-mcp-config` | `strictMcpConfig: true` | Equivalent |
|
||||
| Disallowed tools | `--disallowedTools X,Y` | `disallowedTools: ['X','Y']` | Equivalent. Known bug: both ignore MCP tools in `-p` mode ([#12863](https://github.com/anthropics/claude-code/issues/12863)) |
|
||||
| Allowed tools | `--allowedTools X,Y` | `allowedTools: ['X','Y']` | Equivalent |
|
||||
| stream-json I/O | `--input-format stream-json --output-format stream-json` | Automatic (SDK default) | SDK uses this internally, no config needed |
|
||||
| Permission mode | `--permission-mode X` | `permissionMode: 'X'` | Equivalent |
|
||||
| Custom flags | Any `--flag value` | `extraArgs: { flag: 'value' }` | **SDK supports arbitrary flags via `extraArgs`** |
|
||||
| CLAUDE.md | Auto-loaded | `settingSources: ['project']` | Opt-in in SDK, auto in CLI |
|
||||
| Custom spawn | Manual `child_process.spawn()` | `spawnClaudeCodeProcess: (opts) => spawn(...)` | SDK provides typed interface |
|
||||
| In-process MCP | Not possible | `createSdkMcpServer()` | **SDK-only advantage** — no subprocess overhead |
|
||||
| Custom tools | Via MCP only | In-process functions | **SDK-only advantage** |
|
||||
| Programmatic hooks | Via config files | Callback functions | **SDK-only advantage** |
|
||||
| Programmatic subagents | Via config files | `agents: {...}` inline | **SDK-only advantage** |
|
||||
| Agent Teams | Full support | **CLI-only feature** | Not configurable via SDK options. Must use CLI |
|
||||
| Auto memory | Full support | **Never loaded by SDK** | CLI-only feature |
|
||||
| Skills | Full support | Via `settingSources` + `allowedTools: ['Skill']` | Equivalent when configured |
|
||||
| Session resume | `claude --resume ID` | `resume: 'sessionId'` | Equivalent |
|
||||
| Streaming | Via flags | `includePartialMessages: true` | SDK provides typed events |
|
||||
| Structured output | Not available | `outputFormat: { type: 'json_schema', ... }` | **SDK-only advantage** |
|
||||
| File checkpointing | Not available | `enableFileCheckpointing: true` | **SDK-only advantage** |
|
||||
| V2 Session API | Not available | `unstable_v2_*` | **SDK-only**, unstable |
|
||||
|
||||
### Performance: ~12s Overhead Per `query()` Call
|
||||
|
||||
**This is real and documented.** Each `query()` call spawns a new CLI process, which takes ~12s to initialize.
|
||||
|
||||
> "The Claude Agent SDK `query()` has ~12s overhead per call — no hot process reuse"
|
||||
> — [GitHub Issue #34](https://github.com/anthropics/claude-agent-sdk-typescript/issues/34)
|
||||
|
||||
For comparison, direct Anthropic Messages API: 1-3s. Previous SDK versions: ~40s (improved 70%).
|
||||
|
||||
**But for our use case (long-running agent sessions), this doesn't matter.** We spawn teams that run for minutes/hours. 12s startup is amortized. If you need sub-second responses, use the Anthropic API directly — not the SDK and not CLI direct.
|
||||
|
||||
**Direct CLI spawn has the SAME overhead** — the 12s is the CLI initialization time, not SDK overhead. SDK adds negligible wrapper cost on top.
|
||||
|
||||
### SDK-Only Features (Not Available in CLI Direct)
|
||||
|
||||
1. **In-process MCP servers** — `createSdkMcpServer()`, no subprocess management
|
||||
2. **Custom tools as functions** — No separate MCP server needed
|
||||
3. **Programmatic hooks** — TypeScript/Python callbacks, not shell scripts
|
||||
4. **Structured output** — JSON schema for typed responses
|
||||
5. **File checkpointing** — Rewind file changes to any point
|
||||
6. **Typed message stream** — `SDKMessage` union type with discriminators
|
||||
7. **Dynamic MCP management** — `setMcpServers()`, `toggleMcpServer()`, `reconnectMcpServer()`
|
||||
8. **Prompt suggestions** — AI-generated next prompt
|
||||
9. **Permission callbacks** — `canUseTool()` with structured decisions
|
||||
|
||||
### CLI-Only Features (Not Available in SDK)
|
||||
|
||||
1. **Agent Teams** — Multiple coordinated sessions (our core feature!)
|
||||
2. **Auto memory** — `~/.claude/projects/*/memory/` persistence
|
||||
3. **Interactive TUI** — Terminal UI
|
||||
|
||||
### Critical Finding for Our Project
|
||||
|
||||
**Agent Teams are CLI-only.** The official docs explicitly state:
|
||||
> "Agent teams are a CLI feature where one session acts as the team lead, coordinating work across independent teammates."
|
||||
> — [Claude Code Features in SDK](https://platform.claude.com/docs/en/agent-sdk/claude-code-features)
|
||||
|
||||
This means for our team management feature, we **MUST** use CLI direct (which we already do). The SDK cannot replace our current architecture for teams.
|
||||
|
||||
However, for solo agents or subagent workflows, the SDK provides a better API.
|
||||
|
||||
---
|
||||
|
||||
## 2. Codex SDK (`@openai/codex-sdk`)
|
||||
|
||||
### Architecture
|
||||
|
||||
> "The TypeScript SDK wraps the Codex CLI from `@openai/codex`. It spawns the CLI and exchanges JSONL events over stdin/stdout."
|
||||
> — [Codex SDK docs](https://developers.openai.com/codex/sdk)
|
||||
|
||||
Same pattern as Claude: SDK spawns CLI subprocess.
|
||||
|
||||
### API Surface
|
||||
|
||||
```typescript
|
||||
const codex = new Codex({
|
||||
env?: Record<string, string>, // Environment variables
|
||||
baseUrl?: string, // API base URL (→ --config openai_base_url=...)
|
||||
config?: Record<string, any> // Arbitrary config (→ --config key=value)
|
||||
});
|
||||
|
||||
const thread = codex.startThread({
|
||||
workingDirectory?: string,
|
||||
skipGitRepoCheck?: boolean
|
||||
});
|
||||
|
||||
// Buffered
|
||||
const result = await thread.run(prompt, { outputSchema?: JSONSchema });
|
||||
|
||||
// Streaming
|
||||
for await (const event of thread.runStreamed(prompt)) { ... }
|
||||
|
||||
// Resume
|
||||
const thread = codex.resumeThread(threadId);
|
||||
```
|
||||
|
||||
### Feature Comparison: SDK vs CLI Direct
|
||||
|
||||
| Feature | CLI Direct | SDK | Notes |
|
||||
|---------|-----------|-----|-------|
|
||||
| MCP config | `config.toml` / `codex mcp` | Via `config` option passthrough | CLI manages MCP directly |
|
||||
| Custom flags | Any flag | `config: { key: value }` → `--config key=value` | Limited to config passthrough |
|
||||
| Model selection | `/model` command | Not directly exposed | Must use config |
|
||||
| Approval modes | `--full-auto`, etc. | Not directly exposed | Must use config or env |
|
||||
| Structured output | Not in interactive mode | `outputSchema` (Zod → JSON Schema) | **SDK advantage** |
|
||||
| Thread persistence | `codex resume` | `resumeThread(threadId)` | Equivalent |
|
||||
| Streaming | JSONL stdout | `runStreamed()` async generator | SDK provides typed events |
|
||||
| Multimodal input | Screenshots, sketches | `{ type: 'local_image', path }` | Equivalent |
|
||||
| Performance | Baseline (CLI init) | Same + minimal SDK overhead | No significant difference |
|
||||
|
||||
### Native SDK Alternative: `@codex-native/sdk`
|
||||
|
||||
There's a Rust-based alternative via napi-rs that **does NOT spawn child processes**:
|
||||
|
||||
> "The Native SDK provides Rust-powered bindings via napi-rs, giving you direct access to Codex functionality without spawning child processes."
|
||||
> — [@codex-native/sdk npm](https://www.npmjs.com/package/@codex-native/sdk)
|
||||
|
||||
Full API compatibility with the TypeScript SDK, but with native performance. However, only 33 weekly downloads — practically nobody uses it.
|
||||
|
||||
### Known Issues
|
||||
|
||||
- **Windows spawn EPERM** — CLI fails on Windows ([#7810](https://github.com/openai/codex/issues/7810))
|
||||
- **Zombie MCP processes** — 1,300+ zombies, 37GB memory leak ([#12491](https://github.com/openai/codex/issues/12491))
|
||||
- **Subagents experimental** — Gated behind `features.multi_agent` flag
|
||||
|
||||
---
|
||||
|
||||
## 3. Gemini CLI SDK (`@google/gemini-cli-sdk`)
|
||||
|
||||
### Architecture
|
||||
|
||||
Monorepo with three packages:
|
||||
- `@google/gemini-cli` — Bundled single executable (CLI)
|
||||
- `@google/gemini-cli-core` — Core logic, API orchestration, tool execution
|
||||
- `@google/gemini-cli-sdk` — Programmatic API layer over core
|
||||
|
||||
**Key difference from Claude/Codex:** The Gemini SDK **does NOT spawn CLI as subprocess**. It uses `@google/gemini-cli-core` directly as a library. This is architecturally different — the SDK calls core functions in-process.
|
||||
|
||||
### API Surface
|
||||
|
||||
```typescript
|
||||
// Agent-based API
|
||||
const agent = new GeminiCliAgent(definition: LocalAgentDefinition);
|
||||
// Includes: model config, tools, system instructions
|
||||
|
||||
// Session management
|
||||
const session = new GeminiCliSession(context: AgentLoopContext);
|
||||
|
||||
// Activity monitoring
|
||||
agent.onActivity((activity) => { ... });
|
||||
```
|
||||
|
||||
### Feature Comparison: SDK vs CLI Direct
|
||||
|
||||
| Feature | CLI Direct | SDK | Notes |
|
||||
|---------|-----------|-----|-------|
|
||||
| MCP support | `config.toml` | Via core ToolRegistry | Same underlying system |
|
||||
| Custom tools | Via MCP servers | Via ToolRegistry + custom definitions | SDK has more direct access |
|
||||
| Model routing | Auto fallback | Via ModelConfig | Same capability |
|
||||
| Hooks | Shell scripts | Programmatic callbacks | SDK advantage |
|
||||
| Sandboxing | Built-in | Via SandboxManager | Same capability |
|
||||
| Output format | `--output-format json/stream-json` | Typed events via callbacks | SDK provides typed events |
|
||||
| Extensions | Plugin architecture | Same plugin system | Equivalent |
|
||||
| Agent Skills | Custom skills | Custom skills | Equivalent |
|
||||
| Performance | Baseline | **No subprocess — in-process** | **SDK is faster** |
|
||||
| Abort support | Ctrl+C | Limited — aborted requests continue ([known issue](https://github.com/google-gemini/gemini-cli/issues/15539)) | CLI wins here |
|
||||
| Checkpointing | Automatic snapshots | Via SDK session | Equivalent |
|
||||
|
||||
### Maturity
|
||||
|
||||
The SDK was introduced in v0.30.0. GitHub issue [#15539](https://github.com/google-gemini/gemini-cli/issues/15539) requesting a formal SDK is now **CLOSED as completed**. The core API surface is still evolving — `@google/gemini-cli-core` includes "robust compatibility measures" suggesting instability.
|
||||
|
||||
---
|
||||
|
||||
## 4. Cross-SDK Comparison Matrix
|
||||
|
||||
| Dimension | Claude Agent SDK | Codex SDK | Gemini CLI SDK |
|
||||
|-----------|-----------------|-----------|----------------|
|
||||
| **Architecture** | Spawns CLI subprocess | Spawns CLI subprocess | In-process (uses core directly) |
|
||||
| **Startup overhead** | ~12s per query() | Unknown (similar pattern) | Minimal (no subprocess) |
|
||||
| **CLI flag passthrough** | `extraArgs` for ANY flag | `config` for config flags | N/A (not subprocess-based) |
|
||||
| **MCP support** | Full (stdio, SSE, HTTP, in-process) | Full (stdio, HTTP) | Full (via ToolRegistry) |
|
||||
| **In-process tools** | `createSdkMcpServer()` | Custom tool registration | ToolRegistry |
|
||||
| **Structured output** | JSON Schema | JSON Schema (Zod) | Zod schemas |
|
||||
| **Agent teams** | CLI-only | N/A | N/A |
|
||||
| **Subagents** | Programmatic + filesystem | Experimental | Via LocalAgentExecutor |
|
||||
| **Streaming** | AsyncGenerator<SDKMessage> | AsyncGenerator events | onActivity callback |
|
||||
| **Custom spawn** | `spawnClaudeCodeProcess` | Not exposed | N/A (no subprocess) |
|
||||
| **Session resume** | Full (resume, fork) | Full (resumeThread) | Via GeminiCliSession |
|
||||
| **Hooks** | Programmatic callbacks | Not documented | Programmatic callbacks |
|
||||
| **License** | Proprietary | Open source (Apache 2.0) | Open source (Apache 2.0) |
|
||||
| **npm weekly DL** | High (official Anthropic) | High (official OpenAI) | Medium (newer) |
|
||||
| **Maturity** | Production (v0.2.81) | Production | Early (v0.30.0+) |
|
||||
|
||||
---
|
||||
|
||||
## 5. Key Questions Answered
|
||||
|
||||
### Q1: Does Claude Agent SDK support ALL CLI flags?
|
||||
|
||||
**YES.** Via `extraArgs: Record<string, string | null>` you can pass ANY arbitrary flag. Plus most important flags have dedicated typed options (`mcpServers`, `disallowedTools`, `allowedTools`, `permissionMode`, etc.).
|
||||
|
||||
### Q2: Does Codex SDK expose all CLI capabilities?
|
||||
|
||||
**Partially.** The `config` option can pass arbitrary config values, but not all CLI flags are exposed as typed options. The API surface is minimal compared to Claude's SDK.
|
||||
|
||||
### Q3: Does Gemini CLI SDK expose all CLI capabilities?
|
||||
|
||||
**Mostly.** Since it uses `@google/gemini-cli-core` directly (not subprocess), it has access to all internal APIs. But the public SDK surface is still maturing.
|
||||
|
||||
### Q4: Is there a performance overhead?
|
||||
|
||||
**Claude/Codex: YES — ~12s startup per query() call.** This is the CLI initialization time, not SDK overhead. Direct spawn has the same cost.
|
||||
|
||||
**Gemini: NO additional overhead** — in-process architecture, no subprocess.
|
||||
|
||||
### Q5: Can we pass arbitrary flags through the SDK?
|
||||
|
||||
- **Claude:** YES, via `extraArgs`
|
||||
- **Codex:** Partially, via `config` (maps to `--config key=value`)
|
||||
- **Gemini:** N/A (not subprocess-based)
|
||||
|
||||
### Q6: Does the SDK actually spawn the CLI?
|
||||
|
||||
- **Claude:** YES — spawns bundled `cli.js` via `child_process`
|
||||
- **Codex:** YES — spawns CLI and exchanges JSONL over stdin/stdout
|
||||
- **Gemini:** NO — uses core library in-process
|
||||
|
||||
### Q7: What happens when a new CLI flag is added?
|
||||
|
||||
- **Claude:** `extraArgs` passes ANY flag through immediately. No SDK update needed.
|
||||
- **Codex:** May need SDK update for new flags not covered by `config`
|
||||
- **Gemini:** Core library update needed, but it's the same package ecosystem
|
||||
|
||||
### Q8: Can we use SDK and direct CLI interchangeably?
|
||||
|
||||
**YES.** They are not mutually exclusive. Use SDK for simple flows, CLI direct for advanced (Agent Teams, etc.). Both produce the same session files, use the same auth, same MCP servers.
|
||||
|
||||
---
|
||||
|
||||
## 6. Verdict for Our Project (Claude Agent Teams UI)
|
||||
|
||||
### What We Need
|
||||
|
||||
1. **Agent Teams** (lead + teammates, stream-json, inbox messaging) — **CLI-only**
|
||||
2. **MCP config passthrough** (`--mcp-config`, `--strict-mcp-config`) — **Both work**
|
||||
3. **Disallowed tools** (`--disallowedTools`) — **Both work**
|
||||
4. **stream-json stdin/stdout** — **SDK uses this internally, CLI direct also works**
|
||||
5. **Custom spawn control** (Electron, process management) — **Both work**
|
||||
6. **Long-running sessions** (teams run for hours) — **Both work, 12s overhead irrelevant**
|
||||
|
||||
### Recommendation
|
||||
|
||||
| Use Case | Approach | Confidence |
|
||||
|----------|----------|------------|
|
||||
| Agent Teams (lead + teammates) | **CLI direct spawn** (current) | 10/10 — SDK cannot do this |
|
||||
| Solo agent mode | **Either works**, SDK is nicer | 9/10 |
|
||||
| Future multi-provider support | **CLI direct for each** | 8/10 — more flexible |
|
||||
| Subagent orchestration | **SDK preferred** (typed subagents) | 8/10 |
|
||||
|
||||
### Final Assessment
|
||||
|
||||
**The concern about SDKs being "less flexible" is UNFOUNDED for most use cases.** The SDKs provide typed access to everything the CLI does, plus extras (in-process MCP, programmatic hooks, structured output). The `extraArgs` option in Claude SDK means you're never blocked by missing typed options.
|
||||
|
||||
**The concern about SDKs being "slower" is VALID but IRRELEVANT for long-running agents.** The ~12s startup overhead is the CLI itself, not the SDK wrapper. Direct spawn has the same cost.
|
||||
|
||||
**The ONE real limitation: Agent Teams are CLI-only.** Since our core feature IS Agent Teams, we MUST use CLI direct for team management. This is not a limitation of "SDKs in general" — it's a specific architectural decision by Anthropic.
|
||||
|
||||
### Hybrid Approach (Best of Both Worlds)
|
||||
|
||||
```
|
||||
Agent Teams → CLI direct spawn (mandatory)
|
||||
Solo agents → SDK query() (nicer API, typed, in-process MCP)
|
||||
Subagents → SDK agents option (programmatic, isolated)
|
||||
Multi-provider → CLI direct for each provider
|
||||
```
|
||||
|
||||
Reliability: 9/10
|
||||
Confidence: 9/10
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Claude Agent SDK TypeScript Reference](https://platform.claude.com/docs/en/agent-sdk/typescript)
|
||||
- [Claude Code Features in SDK](https://platform.claude.com/docs/en/agent-sdk/claude-code-features)
|
||||
- [Claude Agent SDK Overview](https://platform.claude.com/docs/en/agent-sdk/overview)
|
||||
- [Claude Agent SDK MCP](https://platform.claude.com/docs/en/agent-sdk/mcp)
|
||||
- [Claude Agent SDK Performance Issue #34](https://github.com/anthropics/claude-agent-sdk-typescript/issues/34)
|
||||
- [Claude Agent SDK Custom Spawn #103](https://github.com/anthropics/claude-agent-sdk-typescript/issues/103)
|
||||
- [Claude Agent SDK Pitfalls](https://liruifengv.com/posts/claude-agent-sdk-pitfalls-en/)
|
||||
- [Claude Agent SDK vs CLI System Prompts](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-sdk-vs-cli-system-prompts.md)
|
||||
- [Claude Code vs Claude Agent SDK (Medium)](https://drlee.io/claude-code-vs-claude-agent-sdk-whats-the-difference-177971c442a9)
|
||||
- [--disallowedTools MCP bug #12863](https://github.com/anthropics/claude-code/issues/12863)
|
||||
- [Codex SDK Documentation](https://developers.openai.com/codex/sdk)
|
||||
- [Codex CLI Documentation](https://developers.openai.com/codex/cli)
|
||||
- [Codex MCP Support](https://developers.openai.com/codex/mcp)
|
||||
- [@codex-native/sdk npm](https://www.npmjs.com/package/@codex-native/sdk)
|
||||
- [Codex Zombie Process Bug #12491](https://github.com/openai/codex/issues/12491)
|
||||
- [Gemini CLI SDK DeepWiki](https://deepwiki.com/google-gemini/gemini-cli/5.9-sdk-and-programmatic-api)
|
||||
- [Gemini CLI Formal SDK Request #15539](https://github.com/google-gemini/gemini-cli/issues/15539)
|
||||
- [Gemini CLI npm Package](https://geminicli.com/docs/npm/)
|
||||
- [Making Claude Agents Run Faster](https://medium.com/@bayllama/making-your-agents-built-using-claude-agent-sdk-run-faster-2f2526a5cb42)
|
||||
- [Building Agents with Claude Agent SDK (Anthropic)](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)
|
||||
Loading…
Reference in a new issue