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

By default, Super Agents connects to Codex at ws://127.0.0.1:4500.

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 a websocket. Start Codex with a local websocket listener before using the MCP tools:

codex app-server --listen ws://127.0.0.1:4500

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 three backend modes:

• codex: native Codex app-server over websocket.
• openbase_cloud: Claude Code sessions through the Openbase Cloud Anthropic proxy.
• claude_code: Claude Code sessions using local Claude auth/billing.

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

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.

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.

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 default ws://127.0.0.1:4500, pass SUPER_AGENTS_WS_URL when registering the server:

codex mcp add \
  --env SUPER_AGENTS_WS_URL=ws://127.0.0.1:4500 \
  super-agents -- super-agents-mcp

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 websocket URL:

claude mcp add \
  --scope user \
  -e SUPER_AGENTS_WS_URL=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.

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.

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 Codex app-server thread.
• super_agents_resume: resume a named thread.
• super_agents_read: read a named or id-addressed thread.
• super_agents_rename: rename a Codex app-server thread.
• codex_answer_request: answer a pending app-server callback.
• super_agents_sessions: list named Codex app-server threads.
• 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.

Development

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.