Agestra

Agent + Orchestra — Multi-host MCP orchestration for Claude Code, Codex CLI, Gemini CLI, and local models.

English | 한국어 | 日本語 | 中文

Agestra connects the Claude host/CLI, Ollama (local), Gemini CLI, and Codex CLI as pluggable providers, enabling multi-agent orchestration with independent aggregation, consensus debates, autonomous CLI workers, parallel task dispatch, cross-validation, and capability-based provider routing with optional trace evidence — all through 45 MCP tools.

Quick Start

Pick the host you work in first. Use the --assets path when you want the host-native commands/agents installed too; use MCP-only registration when you only need the server connection.

MCP-only registration is also available:

Claude keeps the native plugin UX. Codex combines AGENTS.md, generated custom agents, and the registered agestra MCP server. Gemini combines GEMINI.md, .gemini/commands/agestra/, generated skills, and either project-scope managed files or a user-scope native extension.

Note: npm run install:gemini:assets uses user scope by default. For project-scope managed Gemini files from a checkout, run node scripts/install-host-mcp.mjs gemini --assets --scope project.

Available Gemini commands after asset setup:

• /agestra:setup
• /agestra:review
• /agestra:design
• /agestra:idea
• /agestra:implement
• /agestra:qa
• /agestra:security

Prerequisites

At least one AI provider must be installed:

Each CLI manages its own authentication. Sign in through each CLI's own login flow before using Agestra — Agestra spawns these CLIs as child processes and does not handle their credentials.

Optional but recommended:

• tmux — enables visible CLI worker panes during autonomous execution
• ripgrep (rg) on Windows — if Codex resolves rg to its bundled Store-app path and fails with an "Access is denied" error, install ripgrep separately so a normal rg.exe is found first in PATH:

cargo install ripgrep

Alternative:

winget install BurntSushi.ripgrep.MSVC

Philosophy

Multi-AI is for verification, not token savings. The review, design exploration, and idea generation workflows are structured as validation processes — getting independent opinions from multiple AI providers to catch blind spots, not to parallelize for speed.

How It Works

flowchart TD
    Start([User invokes /agestra command]) --> Preflight[Setup status / environment / provider check]
    Preflight --> Domain{Workflow type}

    Domain -->|Idea / design / review / security| TextLead[Leader assembles specialist and external AIs]
    Domain -->|QA| QaLead[Leader forms QA Brigade]
    Domain -->|Implementation| ImplLead[Leader decomposes implementation work]

    ImplLead --> ImplRoute{Task shape}
    ImplRoute -->|Clear parallel implementation| CliWorkers[Codex / Gemini CLI workers<br/>isolated worktrees]
    ImplRoute -->|Capability-matched scoped work| Ollama[Local/tool models<br/>read / write if policy allows]
    ImplRoute -->|Risky or core change| HostImpl[Host implementer<br/>close leader supervision]
    CliWorkers --> ReviewDiff[Leader monitors status / quota / diff]
    Ollama --> ReviewDiff
    HostImpl --> ReviewDiff
    ReviewDiff --> Merge{Acceptable?}
    Merge -->|No| Reassign[Correction prompt or reassignment]
    Reassign --> ImplRoute
    Merge -->|Yes| QaEvidence

    QaLead --> QaEvidence[Host QA collects executable evidence<br/>build / tests / E2E / screenshots]
    TextLead --> Providers{External AIs available?}
    QaEvidence --> Providers

    Providers -->|No| LocalOut[Host specialist writes<br/>domain report or document]
    Providers -->|Yes| Individual[Each AI writes independent source material]
    LocalOut --> Final([Report back to user])

    Individual --> Ledger[ITEM-* JSON consensus ledger]
    Ledger --> Round[Sequential rounds<br/>agree / disagree / revise / opinion]
    Round --> Gate{Ledger state}
    Gate -->|Needs more discussion| Round
    Gate -->|Leader judgment needed| LeaderDecision[Leader chooses continue / approve / reject]
    Gate -->|Resolved| LeaderDecision
    LeaderDecision -->|Continue| Round
    LeaderDecision -->|Approve| Approved[Approved synthesis document]
    LeaderDecision -->|Reject| Rejected[Rejected / unresolved synthesis document]
    Approved --> Final
    Rejected --> Final

When no external provider is configured, Agestra skips consensus rounds and the host specialist writes the domain artifact: review or QA report, design plan, idea record, and so on. When a structured debate runs, leader finalization always leaves a synthesis document: approval produces an approved synthesis, while rejection produces a rejected/unresolved synthesis that lists accepted, excluded, and still-open items.

Host Workflows

All three hosts drive the same MCP server and shared workflow specs from commands/*.md.

Commands

When external providers are available, review, QA, security, design, and idea workflows route through the team lead for multi-AI cross-validation. For QA, the team lead forms a QA Brigade from the configured provider set by default, then hands it to the moderator engine's existing ITEM-* / JSON stance ledger: host QA collects executable evidence, providers take distinct verification lenses, candidate findings are challenged before inclusion, and the synthesis preserves consensus plus dissent. E2E/browser/runtime execution remains host-owned, and external providers review the resulting evidence. When no providers are detected, the current leader host works with its local specialist agent automatically. Implementation requests first classify the task and can ask whether to propose an AI task distribution.

Agents

Skills

Architecture

Turborepo monorepo with 8 packages:

Design Principles

• Provider abstraction — All backends implement AIProvider (chat, healthCheck, getCapabilities). Adding a new provider is isolated to a provider package plus factory registration.
• Zero-config — Providers are auto-detected at startup. No manual configuration required.
• Host-native — Claude uses the plugin bundle, Codex uses AGENTS.md plus custom agents, and Gemini uses GEMINI.md, commands, skills, or the native extension. All hosts share the same MCP server and workflow core.
• Modular dispatch — Each tool category is an independent module with getTools() + handleTool(). The server collects and dispatches dynamically.
• Atomic writes — All file operations use write-to-temp-then-rename to prevent corruption.
• Dead-end tracking — Failed approaches are recorded and injected into future prompts.
• Preflight security — CLI worker spawning includes secret scanning and array-based process args to prevent injection.

Work Modes

In multi-provider modes (consensus debate, cross-validation, review rounds), one provider's output may become part of the prompt the next provider receives.

Text work (review, QA, security, design, idea): providers available → consensus debate mode; no providers → Leader-host only. For QA, the team lead runs a QA Brigade by default while E2E/runtime checks stay host-owned.

Implementation work (team-lead orchestration):

• Leader-host only — agestra-implementer applies scoped code changes; the team lead still routes QA through the QA Brigade by default, with host-only review/QA available on request.
• Suggested AI distribution — the team lead proposes a routing table, asks for approval, then distributes work according to the capabilities of detected models, including frontier and local models. Codex/Gemini CLI workers handle suitable autonomous code edits, and local/tool models may receive read-only or read/write AgentLoop tools according to their executionPolicy.

Tools (45)

AI Chat (3)

Agent Orchestration (15)

CLI Workers (4)

Environment (1)

Workspace (7)

Provider Management (2)

Setup (2)

Host Assets (3)

Ollama (2)

Jobs (2)

QA (1)

Trace / Observability (3)

Configuration

providers.config.json

Created by /agestra setup. The default location is the host-shared ~/.agestra/providers.config.json. Resolution order is AGESTRA_CONFIG_PATH env var → existing ~/.agestra/providers.config.json → existing legacy $CLAUDE_PLUGIN_ROOT/providers.config.json → ~/.agestra/providers.config.json for new writes. It is not meant to sit in the project repo and is gitignored accordingly.

Runtime Data

Stored under .agestra/ (gitignored):

Development

npm install        # Install dependencies
npm run build      # Build all packages (Turborepo)
npm test           # Run all tests (Vitest)
npm run bundle     # Build single-file plugin bundle (esbuild)
npm run dev        # Watch mode
npm run lint       # Lint (ESLint)
npm run clean      # Remove dist/

Project Structure

agestra/
├── AGENTS.md               # Codex host instructions
├── GEMINI.md               # Gemini host instructions
├── .claude-plugin/
│   ├── plugin.json          # Claude Code plugin manifest
│   └── marketplace.json     # Plugin marketplace metadata
├── .gemini/
│   └── commands/
│       └── agestra/
│           ├── setup.toml   # /agestra:setup in Gemini CLI
│           ├── review.toml  # /agestra:review in Gemini CLI
│           ├── design.toml  # /agestra:design in Gemini CLI
│           ├── idea.toml    # /agestra:idea in Gemini CLI
│           ├── implement.toml # /agestra:implement in Gemini CLI
│           ├── qa.toml      # /agestra:qa in Gemini CLI
│           └── security.toml # /agestra:security in Gemini CLI
├── commands/
│   ├── setup.md             # /agestra setup — provider setup
│   ├── review.md            # /agestra review — quality verification
│   ├── qa.md                # /agestra qa — PASS/FAIL verification
│   ├── security.md          # /agestra security — security review
│   ├── idea.md              # /agestra idea — improvement discovery
│   ├── design.md            # /agestra design — architecture exploration
│   └── implement.md         # /agestra implement — execution workflow
├── agents/
│   ├── agestra-reviewer.md  # Strict quality verifier (Opus)
│   ├── agestra-designer.md  # Architecture explorer (Opus)
│   ├── agestra-ideator.md   # Improvement discoverer (Sonnet)
│   ├── agestra-implementer.md # Scoped implementation executor (Sonnet)
│   ├── agestra-e2e-writer.md # Persistent E2E test writer (Sonnet)
│   ├── agestra-moderator.md # Multi-mode facilitator (Sonnet)
│   ├── agestra-qa.md        # QA verifier (Opus, no code writes)
│   ├── agestra-security.md  # Security reviewer (Opus)
│   └── agestra-team-lead.md # Full orchestrator (Sonnet, no code writes)
├── skills/
│   ├── provider-guide.md    # Provider routing and mode reference
│   ├── worker-manage.md     # CLI worker management
│   ├── cancel.md            # Graceful operation cancellation
│   ├── build-fix.md         # Build error auto-repair
│   ├── trace.md             # Execution timeline viewer
│   ├── setup.md             # Initial provider selection
│   ├── design.md            # Architecture exploration workflow
│   ├── idea.md              # Improvement discovery workflow
│   ├── review.md            # Code quality review workflow
│   ├── qa.md                # Design-contract QA workflow
│   ├── security.md          # Dedicated security review workflow
│   ├── e2e.md               # Persistent E2E test-writing workflow
│   └── leader.md            # Multi-AI orchestration entry router
├── hooks/
│   └── user-prompt-submit.md  # Tool recommendation hook
├── dist/
│   └── bundle.js            # Single-file MCP server bundle
├── scripts/
│   ├── bundle.mjs           # esbuild bundle script
│   ├── install-host-mcp.mjs # Register Claude/Codex/Gemini MCP + host assets
│   └── uninstall-host-mcp.mjs # Remove host registrations and managed assets
├── packages/
│   ├── core/                # AIProvider interface, registry, security, workers
│   ├── provider-claude/     # Anthropic Claude CLI adapter
│   ├── provider-ollama/     # Ollama HTTP adapter
│   ├── provider-gemini/     # Gemini CLI adapter
│   ├── provider-codex/      # Codex CLI adapter
│   ├── agents/              # Debate engine, dispatcher, cross-validator
│   ├── workspace/           # Workspace document manager
│   └── mcp-server/          # MCP server, 45 tools, environment-aware filtering, dispatch
├── package.json             # Workspace root
└── turbo.json               # Turborepo pipeline

Adding a Provider

1. Create packages/provider-<name>/ implementing AIProvider.
2. Add a factory in packages/mcp-server/src/index.ts.
3. npm run build && npm test

Uninstall

Claude Code:

/plugin uninstall agestra@agestra

Codex CLI:

npm run uninstall:codex
npm run uninstall:codex:assets

Gemini CLI:

npm run uninstall:gemini
npm run uninstall:gemini:assets

The *:assets uninstall commands remove both the host registration and unchanged generated host assets. Codex assets are custom-agent files. Gemini project-scope assets are managed files; Gemini user-scope assets are removed through gemini extensions uninstall agestra. If a generated asset was edited by the user, Agestra leaves it in place and reports it. For a global npm install, use agestra-uninstall codex --assets or agestra-uninstall gemini --assets --scope user.

If you also want to delete generated project data, remove the .agestra/ directory manually.

License

GPL-3.0