Metadata-Version: 2.5
Name: super-agents
Version: 0.1.16
Summary: MCP wrapper for controlling Codex app-server threads, turns, plan mode, and steering.
Project-URL: Repository, https://github.com/montaguegabe/super-agents
Project-URL: Issues, https://github.com/montaguegabe/super-agents/issues
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: mcp<2,>=1.12.4
Requires-Dist: websockets>=12.0
Provides-Extra: claude
Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'claude'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Description-Content-Type: text/markdown

# Super Agents

Super Agents is a Python MCP server and library for controlling local
[Codex app-server](https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md)
sessions asynchronously.

It gives AI agents a compact tool surface for creating named Codex threads,
starting turns, checking progress, steering active work, cancelling turns,
answering app-server callbacks, and tracking lightweight local session state.

Super Agents is used by Openbase Coder, but it can also be run directly by any
MCP client that needs to coordinate Codex app-server threads without blocking on
long-running turns.

It also supports Claude Code for Super Agents UI-driver sessions. A small
non-MCP command switches Openbase's default backend.

## Install

The recommended install path is `uv tool install`, which installs the
`super-agents-mcp` command in an isolated tool environment:

```bash
uv tool install super-agents
```

Then register `super-agents-mcp` with your MCP client.

`pipx` also works:

```bash
pipx install super-agents
```

For library-only use inside an existing Python environment:

```bash
python -m pip install super-agents
```

## Requirements

- Python 3.11+
- A running local
  [`codex app-server`](https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md)
- An MCP-compatible client such as Codex, Claude Desktop, or Openbase Coder

On macOS and Linux, Super Agents defaults to Codex's standard Unix control
socket at `$CODEX_HOME/app-server-control/app-server-control.sock`. Windows
retains the loopback WebSocket default until Codex provides an equivalent
local daemon transport there.

## MCP Server

Run the MCP server with:

```bash
super-agents-mcp
```

For local development from a checkout:

```bash
uv sync --extra dev
uv run super-agents-mcp
```

Example MCP server command:

```bash
uvx --from super-agents super-agents-mcp
```

If you are running from a source checkout instead of an installed package:

```bash
uv --directory /path/to/super-agents run super-agents-mcp
```

## Start Codex App Server

Super Agents talks to the
[Codex app-server](https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md)
over WebSocket frames. On Unix, start Codex on its standard Unix control socket
before using the MCP tools:

```bash
codex app-server --listen unix://
```

Openbase Coder users usually do not need to run this by hand; the
`codex-app-server` background service owns that process.

## Backends

Super Agents supports four configured backend identities:

- `codex`: native Codex app-server over a Unix socket or TCP WebSocket.
- `openbase_cloud`: Claude Code sessions through the Openbase Cloud Anthropic proxy.
- `claude_code`: Claude Code sessions using local Claude auth/billing.
- `openbase_cloud_codex`: Codex-compatible sessions routed through an
  Openbase Cloud integration.

Launching is model-first: pass `model` to `super_agents_start` (or a turn
tool) and the thread routes to a backend that can run it — `fable`, `opus`,
`sonnet`, and `haiku` route to Claude Code; `gpt-5.5`, `gpt-5`, `sol`, and
`astra` route to Codex. Provider-style aliases normalize to canonical slugs
(`openai-sol`, `open-ai-sol`, `openai/sol` → `sol`; `claude-fable-5`,
`anthropic-fable` → `fable`), and provider-prefixed ids newer than the
catalog (`gpt-*`, `claude-*`) pass through to their family. A bare unknown
slug is rejected before anything starts, with suggestions. Extend the
catalog without a release via `SUPER_AGENTS_EXTRA_MODELS`, e.g.
`{"codex": ["new-model"]}`.

When `model` is omitted, the default is the caller's own model when the
environment carries it (`SUPER_AGENTS_CALLER_MODEL`, then the
vendor-neutral `AGENT_MODEL` — which Super Agents itself injects into agent
shells alongside `AGENT_SESSION_ID`, so agents that spawn Super Agents
default their children to the model they run on), provided it is compatible
with the selected backend; otherwise the configured `backend_models`
default applies.

The MCP server can mix these identities per thread. Pass `backend` to
`super_agents_start` only as an advanced override — an explicit backend that
cannot execute the requested model fails immediately. If it is omitted,
model routing wins, then `SUPER_AGENTS_DEFAULT_BACKEND` when set, then
`OPENBASE_CODING_BACKEND`.
Explicit and default identities are persisted against returned thread, turn,
and approval-request ids, so follow-up operations keep using the owning
backend after a server restart. If the same name exists on multiple backends,
name-only operations fail with an ambiguity error; pass `backend` or the
returned `threadId`.

`codex` and `openbase_cloud_codex` can coexist only when their identity-specific
websocket variables point to distinct app-server processes. The server rejects
a second Codex identity on the same endpoint instead of pretending it is an
independent backend.

Switch modes without MCP:

```bash
super-agents-backend use codex
super-agents-backend use openbase-cloud
super-agents-backend use claude-code
super-agents-backend status
```

Restart the process that owns Super Agents after switching. For `codex`, restart
`codex-app-server`; for Openbase Cloud and Claude Code, restart the MCP host
running `super-agents-mcp`.

## Claude Code Backend

Normal steering sends a correction into the active conversation while running tools finish. When a correction explicitly stops or replaces that tool work, call `super_agents_steer` with `interruptCurrentWork: true`. On Claude-compatible backends this interrupts the tool and submits the correction on the same conversation and active turn. Progress remains pending until the corrective response finishes; a submission acknowledgment is not proof that the work changed. Error results, missing terminal results and interrupted follow-ups that never begin are reported as failed rather than successful completion. Use a queued turn for independent follow-up work.

The Claude Code backend uses the `claude-agent-sdk` package directly. It does
not run a local Anthropic Messages API adapter, does not expose `/v1/responses`,
and does not require Codex app-server. Direct `claude_code` billing/auth comes
from the local Claude setup on the computer. The `openbase_cloud` backend uses
the same Claude Code execution path, but points Claude Code at Openbase's
Anthropic proxy with `ANTHROPIC_BASE_URL` and an Openbase machine token in
`ANTHROPIC_AUTH_TOKEN`.

Set `SUPER_AGENTS_CLAUDE_EXTRA_ARGS` to a JSON object to pass extra Claude
Code CLI flags to every session, e.g. `{"chrome": null}` to enable the Claude
in Chrome browser tools (`null` means a bare flag; string values are passed as
the flag's argument).

```bash
uv tool install 'super-agents[claude]'
super-agents-backend use claude-code
```

or, from a source checkout:

```bash
uv sync --extra dev --extra claude
uv run super-agents-backend use claude-code
```

Set `OPENBASE_CODING_BACKEND=claude_code` to make `super-agents-mcp` use
this backend. `OPENBASE_CODEX_BACKEND` is still read as a legacy fallback.
Follow-up turns preserve live SDK conversation context while the MCP process
remains running; persisted metadata and logs survive restarts.

Session listings on this backend index the local Claude home
(`CLAUDE_CONFIG_DIR`, default `~/.claude`) by last interaction: transcript
files the user touched recently — including Claude Code sessions started
outside Super Agents — are registered and kept fresh, and all listings sort
most-recently-interacted first across backends.

A Claude Code session running in a terminal (one this library did not launch) is steered through Claude Code's per-session inbox socket (`super_agents.claude_inbox`). Claude Code exports the socket and its token only to the session's own hooks, so an integrator records them at SessionStart, one JSON file per session (`sessionId`, `socket`, `token`, `cwd`, `recordedAt`), in `$CLAUDE_INBOX_REGISTRY_DIR` or `<Claude home>/inbox-registry`. `steer_by_label` then delivers into a live inbox instead of resuming the transcript the terminal is driving; `claude_inbox.resolve_inbox` and `claude_inbox.deliver_steer` are usable directly, and `claude_home_index.latest_custom_title` reads a transcript's user-set name. A receiver running with permissions bypassed holds such a message until approved in that terminal, unless its settings set `crossSessionInbound` to `accept`.

On this backend, `start_thread` reuses an existing session with the same
`name` (refreshing its cwd, instructions, and model). Library callers that
need a brand-new session and conversation under an existing name can pass
`"fresh": true`, which retires the old session by renaming it aside before
creating the new one.

Library callers creating ordinary conversations should instead supply a unique internal `name` and `"autoTitle": true`. These sessions expose a separate `title`: initially the project basename, then a whitespace-normalized excerpt of the first accepted prompt. Titles never append a session ID, may repeat, persist even if the turn fails, and stay unchanged on later turns. `rename_by_label` changes the display title of these sessions and disables automatic titling; named sessions without `autoTitle` retain their existing rename and reuse semantics. Title extraction strips known integration context and system-note envelopes before shortening the request; imported transcripts with no visible request use the project name. Imported names remain unique through numbered suffixes such as `project (2)`; retired name holders use `name (retired)`, then `name (retired) (2)`.

The SQLite store adds optional `title` and `auto_title` columns on open; existing rows remain named sessions. Under the state-file lock, a one-time migration advances SQLite `user_version` from 0 to 1 and removes legacy ID suffixes from stored titles and imported or retired names only when the suffix matches that row's own ID. Renamed lookup names receive numbered suffixes when needed to preserve uniqueness. A listing sweep also repairs legacy imported names contaminated by integration context, without changing transcript history, thread IDs, activity times, or explicit user titles. Imported transcript turn views omit known boundary context/system-note/reminder envelopes and unwrap voice transport in user messages; assistant text and the original JSONL used to resume a session remain unchanged.

If the SDK package is not installed, the backend reports `ready=false` with an
install hint.

## Add To Codex

Install the package, then register the MCP server:

```bash
uv tool install super-agents
codex mcp add super-agents -- super-agents-mcp
```

If your Codex app-server is listening somewhere other than the standard Unix
socket, pass the neutral endpoint setting when registering the server:

```bash
codex mcp add \
  --env SUPER_AGENTS_APP_SERVER_ENDPOINT=unix:///var/run/codex.sock \
  super-agents -- super-agents-mcp
```

`SUPER_AGENTS_WS_URL` and `CODEX_APP_SERVER_URL` remain compatibility aliases
for existing TCP WebSocket deployments. Conflicting values are rejected so two
variables cannot silently select different app-server owners.

Check that Codex can see the server:

```bash
codex mcp list
codex mcp get super-agents
```

## Add To Claude Code

Install the package, then register the MCP server:

```bash
uv tool install super-agents
claude mcp add --scope user super-agents -- super-agents-mcp
```

For a non-default Codex app-server endpoint:

```bash
claude mcp add \
  --scope user \
  -e SUPER_AGENTS_APP_SERVER_ENDPOINT=ws://127.0.0.1:4500 \
  super-agents -- super-agents-mcp
```

Check that Claude Code can see the server:

```bash
claude mcp list
claude mcp get super-agents
```

For project-local installs, use `--scope project` instead of `--scope user`.

## Configuration

Super Agents is configured with environment variables and, when running under
Openbase, `~/.openbase/dispatcher-config.json`.

| Variable | Default | Description |
| --- | --- | --- |
| `SUPER_AGENTS_APP_SERVER_ENDPOINT` | `unix://` on Unix; `ws://127.0.0.1:4500` on Windows | Codex app-server endpoint (`unix://`, `unix://PATH`, `ws://`, or `wss://`) |
| `SUPER_AGENTS_WS_URL` | unset | Deprecated compatibility alias for TCP WebSocket deployments |
| `CODEX_APP_SERVER_URL` | unset | Openbase compatibility alias; must not conflict with another endpoint selector |
| `SUPER_AGENTS_CODEX_APP_SERVER_ENDPOINT` | unset | Identity-specific Codex endpoint; required to differ when local and Cloud Codex identities coexist |
| `SUPER_AGENTS_OPENBASE_CLOUD_CODEX_APP_SERVER_ENDPOINT` | unset | Identity-specific Cloud Codex endpoint; required to differ when local and Cloud Codex identities coexist |
| `OPENBASE_CODING_BACKEND` | unset | Machine backend identity: `codex`, `openbase_cloud`, `claude_code`, or `openbase_cloud_codex` |
| `SUPER_AGENTS_DEFAULT_BACKEND` | unset | Per-process default for newly launched threads; falls back to `OPENBASE_CODING_BACKEND` |
| `OPENBASE_CODEX_BACKEND` | unset | Legacy fallback for `OPENBASE_CODING_BACKEND` |
| `SUPER_AGENTS_STATE_FILE` | `~/.super-agents/state.json` | Local session metadata file |
| `SUPER_AGENTS_BACKEND_PROVENANCE_FILE` | `~/.super-agents/backend-provenance.json` | Configured-backend ownership for thread, turn, and approval ids |
| `SUPER_AGENTS_CLAUDE_PERMISSION_MODE` | `bypassPermissions` | Claude SDK permission mode. Gated modes route tool requests through the native approval store. |
| `SUPER_AGENTS_CALLER_MODEL` | unset | Caller's model; becomes the default for launched agents when backend-compatible |
| `AGENT_MODEL` | unset | Vendor-neutral fallback for the caller's model; injected into agent shells on turn start |
| `SUPER_AGENTS_EXTRA_MODELS` | unset | JSON map of extra model slugs per execution backend, e.g. `{"codex": ["new-model"]}` |
| `SUPER_AGENTS_CODEX_PROFILE_PATH` | unset | Optional TOML profile applied to Codex thread configuration, never daemon launch arguments |
| `SUPER_AGENTS_OPENBASE_CLOUD_CODEX_PROFILE_PATH` | unset | Backend-specific Codex profile; falls back to the generic Codex profile |
| `SUPER_AGENTS_CLAUDE_SYSTEM_PROMPT_MODE` | `append` | How the base instructions file shapes the Claude system prompt: `append` keeps the stock `claude_code` preset and appends the file's text; `replace` substitutes the file contents for the whole prompt |
| `SUPER_AGENTS_CLAUDE_SETTINGS_PATH` | unset | Optional Claude session settings JSON, passed through the SDK's `settings` option |
| `SUPER_AGENTS_CLAUDE_MCP_CONFIG_PATH` | unset | Optional JSON `mcpServers` map merged into each Claude session |

Profiles are opt-in for embedding applications. Selected files must exist and parse successfully. They do not rewrite user configuration or relocate authentication and history. Codex's runtime `--profile` flag is not accepted by `app-server`; the client loads TOML into per-thread config instead. Native file hooks are not guaranteed to execute from app-server config overrides; Super Agents supplies its thread identity through developer instructions and shell environment independently.

With a Claude SDK supporting system-prompt snapshots and Claude Code CLI 2.1.257 or later, session `developerInstructions` and assigned identity are composed into the configured system prompt. Append mode preserves the stock preset and global base; replace mode preserves the custom base. Snapshotting is disabled so resumed sessions receive current policy without losing their history. A cached client reconnects at the next turn only when its effective policy changes. Active steers retain their existing per-query delivery without interrupting the client. Older SDKs keep the legacy user-context instruction path; no dependency upgrade is performed automatically. Explicit quiet instructions remain intact, and this integration does not add announcement hooks.

Openbase-specific defaults:

| Config key | Description |
| --- | --- |
| `super_agents_reasoning_effort` | Default reasoning effort for Super Agents turns |
| `backend_models` | Model defaults keyed by backend and role |
| `SUPER_AGENTS_QUEUE_DIR` | next to the state file | Directory for queued turn files |

Super Agents does not silently approve app-server callbacks. If plan mode asks a
question or a sandboxed turn asks for approval, inspect the pending request and
answer it explicitly with `codex_answer_request`.

The same flow applies to Claude Code when `SUPER_AGENTS_CLAUDE_PERMISSION_MODE`
is a gated SDK mode such as `default` or `acceptEdits`. Pending tool requests
appear in status and can be answered with `codex_answer_request`. Approval waits
are bounded and fail closed; persisted details are redacted, and stale requests
from exited processes are discarded rather than reused after restart.

## Tools

The MCP server exposes these tools:

- `codex_app_server_status`: check app-server readiness, websocket connection,
  pending callbacks, and active turns.
- `super_agents_start`: create a named thread, optionally on an explicit backend. Pass the first task as `prompt` to start its first turn in the same call. Without a prompt, the result includes `turnStarted: false` and a `nextStep`; `developerInstructions` supplies standing guidance and does not start work. If starting the turn fails after creation, the error identifies the existing thread so you can inspect it and retry with `super_agents_start_turn` instead of creating a duplicate.
- `super_agents_resume`: resume a named thread.
- `super_agents_read`: read a named or id-addressed thread.
- `super_agents_rename`: rename a Super Agents thread.
- `codex_answer_request`: answer a pending callback on its owning backend.
- `super_agents_sessions`: list named threads across engaged backends.
- `super_agents_thread_favorite`: check whether one local Openbase Coder thread
  is favorited.
- `super_agents_tags`: list local Openbase Coder tag options shared by threads
  and reports.
- `super_agents_thread_tags`: read or replace local tags for one thread.
- `super_agents_report_tags`: read or replace local tags for one report file.
- `super_agents_active`: list active tracked agents with compact previews.
- `super_agents_status`: return a compact status list for voice/status checks.
- `super_agents_resolve`: resolve a name to the latest matching active thread.
- `super_agents_progress`: inspect progress by name, thread id, or turn id.
- `super_agents_steer`: send steering input to an active turn.
- `super_agents_cancel`: cancel an active turn.
- `super_agents_start_turn`: submit follow-up input through app-server
  `turn/start`.
- `super_agents_queue_turn`: queue a follow-up prompt to run after the active
  turn completes.
- `super_agents_cancel_queued_turn`: remove a queued follow-up prompt before
  it starts.
- `super_agents_recent`: list recent named Codex app-server threads.

List-style tools accept `favorite=true` or `favorite=false` to filter by
Openbase Coder's local per-machine favorite metadata.

Default responses are intentionally compact. Full turns, tracked event
transcripts, diffs, and large previews are opt-in through each tool's detail
flags.

### Cancelling Queued Turns

Queued follow-up prompts are visible in `codex_app_server_status` under
`queuedTurns`, and `super_agents_queue_turn` returns the queued item under
`item`. To remove a queued item before it starts, call
`super_agents_cancel_queued_turn` with the queued item id:

```json
{
  "queueItemId": "q_abc123"
}
```

The Claude Code backend exposes queued turns as turn ids, so `turnId` is also
accepted as an alias:

```json
{
  "turnId": "t_abc123"
}
```

If the id is not available, cancel by target thread and 1-based queue position:

```json
{
  "name": "agent-name",
  "position": 1
}
```

Use `threadId` instead of `name` when resolving by id is clearer. This tool only
removes queued items whose status is still `queued`; active or already-started
turns are rejected. Use `super_agents_cancel` for active turns.

## Openbase Coder Report Tags

Openbase Coder stores thread and report tags in the same local tag registry.
When an agent writes a report under a project's `.reports` directory, it can
tag that report by calling `super_agents_report_tags` with:

- `projectPath`: the project directory that contains `.reports`.
- `path`: the report path relative to `.reports`, such as `summary.md` or
  `audits/security.md`.
- `tags`: the complete list of tag labels that should be assigned.

For example, after creating `/workspace/app/.reports/audit.md`, call
`super_agents_report_tags` with `projectPath=/workspace/app`,
`path=audit.md`, and `tags=["Needs Review", "Security"]`. Omitting `tags`
reads the current assignment. New tag labels are added to the shared options
and can then be reused by thread and report tag pickers in Openbase Coder.

## Python API

Openbase Coder and other Python applications can use the app-server client
directly:

```python
from super_agents.app_server_client import CodexAppServerClient

client = CodexAppServerClient()
try:
    status = await client.status()
finally:
    await client.close()
```

The public modules are organized so applications can reuse the websocket client,
session metadata helpers, routine state, and queue handling without starting the
stdio MCP server.

Routines (loops) can run on a schedule, on webhook events, or on file events:
`EventClientMixin.add_routine_trigger` accepts `{"type": "file", "watchPath": "<absolute glob>"}`
and `run_due_routines` sweeps every file trigger, delivering one event per created or
modified file (`path`, `name`, `dir`, `mtime`, `change`, small `contents`).

## Development

Python embeddings of `ClaudeAgentSdkClient` may supply `disallowed_tools_for_session`, a callback receiving the session and returning a tuple of SDK tool names to exclude. The default excludes none. Policies are evaluated per session, and changing a policy reconnects that session's SDK client rather than reusing outdated tool options. This supports routing-only clients without restricting separately managed worker sessions.

Two optional constructor callbacks support application-owned SDK integration. Both default to `None`:

Check `getattr(ClaudeAgentSdkClient, "embedding_callbacks_version", 0) >= 1` before passing these callbacks to clients from older installations. Version 1 covers both callbacks and the crash-safe completion contract below. A missing capability means the embedding must report its required integration unavailable rather than claim enforcement; package version alone is not a capability check. Reading this class attribute requires no client construction or SDK connection.

- `configure_session(session, options, sdk)` is synchronous and runs immediately before each new SDK client is constructed and connected, including connections that resume an existing session. It receives the already configured options, including the in-process Super Agents MCP server. It may extend `options.hooks` and `options.mcp_servers`; preserve unrelated entries. Cached connections do not invoke it again, so hooks that need current turn state should read it when invoked.
- `async validate_turn_result(session, turn, last_result_message)` runs after response and background-task draining, after a non-error terminal result, and before persisting completion. It receives fresh stored session and turn state. Missing/error results, unfinished background tasks and cancellation skip validation. Cancellation is checked again after the callback. Exceptions use normal failed-turn cleanup and disconnect the SDK client. A new response queued during validation prevents completion and fails the turn rather than leaving unread work on a cached client. For validated turns, the completion-eligible `response_finished_at` marker is withheld until validation succeeds, so orphan recovery cannot report an unvalidated turn as completed after process exit. Validators should impose their own bounded waits and must not start another query on the same session.

These callbacks provide no application policy by default and perform no external actions themselves.

From this repository:

```bash
uv sync --extra dev
uv run pytest
uv run ruff check .
uv build
```

## License

Super Agents is licensed under the [MIT License](LICENSE).
