Super Agents

Super Agents is a Python MCP server and library for controlling local Codex app-server 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:

uv tool install super-agents

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

pipx also works:

pipx install super-agents

For library-only use inside an existing Python environment:

python -m pip install super-agents

Requirements

• Python 3.11+
• A running local codex app-server
• 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:

super-agents-mcp

For local development from a checkout:

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

Example MCP server command:

uvx --from super-agents super-agents-mcp

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

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

Start Codex App Server

Super Agents talks to the Codex app-server over WebSocket frames. On Unix, start Codex on its standard Unix control socket before using the MCP tools:

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:

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).

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

or, from a source checkout:

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:

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:

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:

codex mcp list
codex mcp get super-agents

Add To Claude Code

Install the package, then register the MCP server:

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

For a non-default Codex app-server endpoint:

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:

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.

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:

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:

{
  "queueItemId": "q_abc123"
}

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

{
  "turnId": "t_abc123"
}

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

{
  "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:

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:

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

License

Super Agents is licensed under the MIT License.