Metadata-Version: 2.4
Name: agentprism
Version: 0.1.3
Summary: Universal MCP server that exposes coding agents (Copilot, Claude Code, Codex) as subagents via a unified tool interface
Project-URL: Homepage, https://github.com/StefanMaron/agentprism
Project-URL: Repository, https://github.com/StefanMaron/agentprism
Project-URL: Issues, https://github.com/StefanMaron/agentprism/issues
Author-email: Stefan Maron <stefan@stefanmaronconsulting.com>
License: MIT
Keywords: agents,ai,claude,codex,copilot,mcp,subagent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# agentprism

**A universal MCP server that exposes coding agents — GitHub Copilot, Claude Code, Codex — as background subagents behind a single, unified tool interface.**

agentprism lets one AI agent orchestrate other AI agents. Drop it into your MCP client (Claude Code, Cursor, Continue, …) and you gain seven tools — `agent_spawn`, `agent_send`, `agent_wait`, `agent_status`, `agent_list`, `agent_kill`, `agent_models` — that drive any supported coding agent through its native protocol. Run several in parallel, hand off tasks between them, or use a cheaper model as a worker for a more expensive planner. agentprism speaks each provider's wire protocol natively (ACP JSON-RPC for Copilot, stream-JSON for Claude Code, exec-resume for Codex) — no fragile screen-scraping.

## Installation

**Recommended — no install required ([uvx](https://docs.astral.sh/uv/)):**

```bash
# uvx runs agentprism directly from PyPI, no pip install needed
uvx agentprism
```

**Or install permanently:**

```bash
pip install agentprism
# or: uv tool install agentprism
```

**Or from source:**

```bash
git clone https://github.com/StefanMaron/agentprism
cd agentprism
pip install -e .
```

You also need at least one supported coding-agent CLI installed and authenticated:

| Provider     | CLI                                  | Auth                    |
|--------------|--------------------------------------|-------------------------|
| Copilot      | `copilot` ([install][copilot-cli])   | `copilot login`         |
| Claude Code  | `claude` ([install][claude-cli])     | `claude` then `/login`  |
| Codex        | `codex` ([install][codex-cli])       | `codex login`           |

[copilot-cli]: https://docs.github.com/en/copilot/github-copilot-in-the-cli
[claude-cli]:  https://docs.anthropic.com/en/docs/claude-code
[codex-cli]:   https://github.com/openai/codex

## Usage with Claude Code

Add to `~/.claude/mcp.json` (create if it doesn't exist):

```json
{
  "mcpServers": {
    "agentprism": {
      "command": "uvx",
      "args": ["agentprism"],
      "type": "stdio"
    }
  }
}
```

If you installed agentprism permanently, use `"command": "agentprism"` with no `args`.

Restart Claude Code. The eight `agent_*` tools will appear. Try:

> Call `agent_providers` to see what's available, then use `agent_spawn` to start a Copilot session in `/tmp/playground` with the task "write a Python script that prints prime numbers up to 100", then `agent_wait` for it to finish.

## Usage with other MCP clients

Any MCP client that supports stdio servers works. The config shape is the same — point `command` at `agentprism` (or `uvx` + `args: ["agentprism"]`).

## Tool reference

| Tool               | Args                                              | Returns                                    |
|--------------------|---------------------------------------------------|--------------------------------------------|
| `agent_providers`  | —                                                 | which providers are installed + authenticated |
| `agent_models`     | `provider?`                                       | model ids + cost multipliers per provider  |
| `agent_run`        | `task`, `cwd`, `provider?`, `model?`, `timeout?`  | output — one-shot, blocks, auto-cleans up  |
| `agent_spawn`      | `task`, `cwd`, `provider?`, `model?`, `mode?`     | `session_id` — non-blocking, persistent    |
| `agent_send`       | `session_id`, `message`                           | agent reply (blocks until response)        |
| `agent_status`     | `session_id`                                      | `working` \| `idle` \| `done` \| `error`  |
| `agent_wait`       | `session_id`, `timeout_seconds?`                  | accumulated output (blocks until done)     |
| `agent_list`       | —                                                 | all active sessions                        |
| `agent_kill`       | `session_id`                                      | terminates the subprocess                  |

**`provider`** values: `copilot`, `claude`, `codex` — omit to use `AGENTPRISM_DEFAULT_PROVIDER` (default: `copilot`)

**`mode`** values (Copilot / Claude Code): `agent` (default), `plan`, `autopilot`

## Push notifications

When a worker finishes, agentprism proactively notifies the orchestrating MCP client — no polling required.

If the client advertised the `sampling` capability (Claude Code does), agentprism sends a `sampling/createMessage` request: the LLM receives a structured wake-up message with the session summary and can immediately act on the results. Falls back to a `notifications/message` log event for clients that don't support sampling.

## Provider support

| Provider       | Status | Protocol                              |
|----------------|--------|---------------------------------------|
| GitHub Copilot | ✓      | ACP JSON-RPC over stdio               |
| Claude Code    | ✓      | stream-JSON bidirectional stdio       |
| Codex          | ✓      | `codex exec` / `codex exec resume`    |

## Model cost multipliers

Use `agent_models(provider="copilot")` at runtime to get the current list. Examples:

| Model (Copilot)       | Multiplier | Notes                  |
|-----------------------|-----------|------------------------|
| `auto` / `claude-sonnet-4.6` | 1x | default               |
| `claude-haiku-4.5`    | 0.33x     | cheapest Claude        |
| `gpt-5-mini`          | 0x        | free                   |
| `gpt-4.1`             | 0x        | free                   |
| `claude-opus-4.7`     | 7.5x      | deep reasoning only    |
| `gpt-5.5`             | 7.5x      | GPT flagship           |

## Architecture

```
┌──────────────────┐                     ┌──────────────────────────────┐
│  MCP client      │  agent_spawn(...)   │      agentprism server         │
│  (Claude Code,   │ ──────────────────► │                              │
│   Cursor, ...)   │  ◄──── result ────  │  ┌────────────────────────┐  │
└──────────────────┘                     │  │   ToolDispatcher       │  │
                                         │  └───────────┬────────────┘  │
                                         │              │               │
                                         │  ┌───────────▼────────────┐  │
                                         │  │   SessionRegistry      │  │
                                         │  │   session_id ► Adapter │  │
                                         │  └───────────┬────────────┘  │
                                         │              │               │
                                         │  ┌───────────▼────────────┐  │
                                         │  │   CopilotAdapter (ACP) │  │
                                         │  │   ClaudeCodeAdapter    │  │
                                         │  │   CodexAdapter         │  │
                                         │  └───────────┬────────────┘  │
                                         └──────────────┼───────────────┘
                                                        │ native protocol
                                                        ▼
                                          ┌─────────────────────────────┐
                                          │  coding agent subprocess    │
                                          └─────────────────────────────┘
```

Each adapter owns one subprocess per session. A reader coroutine demuxes stdout: responses resolve pending futures, while streaming updates accumulate in an output buffer that `agent_wait` and `agent_send` drain.

## Configuration

Environment variables:

| Variable               | Default    | Purpose                                   |
|------------------------|------------|-------------------------------------------|
| `AGENTPRISM_LOG_LEVEL`   | `INFO`     | Python logging level (logs go to stderr)  |
| `AGENTPRISM_COPILOT_BIN` | `copilot`  | Path to the `copilot` binary              |
| `AGENTPRISM_CLAUDE_BIN`  | `claude`   | Path to the `claude` binary               |
| `AGENTPRISM_CODEX_BIN`   | `codex`    | Path to the `codex` binary                |

## Development

```bash
git clone https://github.com/StefanMaron/agentprism
cd agentprism
pip install -e ".[dev]"
ruff check .
pytest
```

## License

MIT
