Prime Agent Python client¶

SuperQode includes a native, async Python host for Prime Agent's public RPC mode. It replaces the application-side TypeScript bridge: Prime Agent remains the coding runtime, while Python owns process lifecycle, request correlation, event streaming, cancellation, and SuperQode integration.

The client is maintained independently as prime-agent-python-client and consumed by SuperQode as a normal dependency. Add it to another Python project with:

uv add prime-agent-python-client

Requirements¶

• Python 3.12 or 3.13
• prime-agent 0.7.0 or 0.7.1 on PATH
• Credentials required by the selected Prime Agent provider

The client never invokes a shell. A custom executable is represented as an argument sequence, not a command string.

Install and authenticate¶

Install the released SuperQode application with uv:

uv tool install superqode

Prime Agent is a separate executable. Install it from its official release, then confirm both commands resolve to the versions you expect:

superqode --version
prime-agent --version

Prime Agent owns provider authentication. Start it once and run /login to configure GitHub Copilot, or configure another provider using Prime Agent's normal provider settings:

prime-agent

Credentials remain in Prime Agent's configuration. SuperQode does not copy or translate provider tokens.

Use the client directly¶

import asyncio

from prime_agent_client import PrimeSession


async def main() -> None:
    async with PrimeSession(
        cwd="/path/to/repository",
        provider="anthropic",
        model="claude-sonnet-4-20250514",
    ) as session:
        async for event in session.prompt_stream("Fix the failing tests"):
            if event.type == "message_update":
                update = event.get("assistantMessageEvent", {})
                if update.get("type") == "text_delta":
                    print(update.get("delta", ""), end="", flush=True)


asyncio.run(main())

PrimeEvent.raw retains the complete wire payload, including fields and event types introduced by newer Prime Agent releases. Malformed records are surfaced as protocol_error events rather than disappearing.

The high-level API also exposes steer, follow_up, abort, state, messages, stats, set_model, available_models, compact, refine, switch_session, fork, and clone. Use PrimeRpcTransport.request() for a new command that has not yet received a convenience method.

Use Prime Agent from a HarnessSpec¶

Save this as prime-agent.yaml in the repository you want Prime Agent to work in:

name: prime-coder
inherits: coding
runtime:
  backend: prime-agent
  config:
    prime_agent:
      prompt_timeout: 900
      session_dir: .superqode/prime-agent/sessions
model_policy:
  primary: github-copilot/gpt-4.1

The repository includes the same starting point at examples/harnesses/prime-agent.yaml. Run the local spec:

superqode harness doctor --spec prime-agent.yaml --json

superqode harness run \
  --spec prime-agent.yaml \
  --prompt "Explain the repository and identify the highest-risk module" \
  --provider github-copilot \
  --model gpt-4.1 \
  --stream

Use --json instead of --stream when another program will consume the final result:

superqode harness run \
  --spec prime-agent.yaml \
  --prompt "Return a concise repository summary" \
  --provider github-copilot \
  --model gpt-4.1 \
  --json

Normal output prints the completed response, --stream prints model deltas as they arrive, and --json returns the normalized harness result. The three modes use the same Python-hosted RPC backend.

The same HarnessSpec connects in the TUI without a second connection command:

superqode --harness prime-agent.yaml

From an open TUI, use :harness switch ./prime-agent.yaml. SuperQode reports that prime-agent-python-client is active and shows PY RPC in the mode badge. The separate ACP route remains available as :connect acp prime-agent.

The backend emits SuperQode model_delta, thinking_delta, tool_call, tool_update, tool_result, lifecycle, usage, and error events. Every mapped event includes prime_event, the original Prime RPC object.

Configuration keys under runtime.config.prime_agent:

Prime Agent executes its own tools with the permissions of the SuperQode process. The backend therefore advertises shell access but not SuperQode's approval, sandbox, MCP, or typed-output guarantees. Extension UI requests are cancelled by default in headless harness runs so they cannot deadlock the host; direct clients can provide a ui_handler for confirmations and input.

Compatibility policy¶

The package currently marks Prime Agent 0.7.0 and 0.7.1 as tested. Unknown versions are allowed because the protocol is additive, but session.compatibility.tested will be false. This makes upgrades observable without unnecessarily preventing experimentation.

Troubleshooting¶

prime-agent is not found¶

Run prime-agent --version in the same terminal as SuperQode. If it fails, add the Prime Agent installation directory to PATH, then rerun superqode harness doctor.

Authentication or model lookup fails¶

Launch prime-agent directly and complete /login. Verify the requested model works there before using the same provider and model in SuperQode. Provider credentials and model catalogs belong to Prime Agent, not the Python client.

The run starts but produces no streamed text¶

Upgrade SuperQode and verify the active executable:

uv tool upgrade superqode
superqode --version

SuperQode 0.2.80 and later render the normalized model_delta events emitted by the RPC backend. Use --json to distinguish an empty model response from a terminal-rendering problem.

A run times out¶

Raise prompt_timeout for long coding tasks. Keep request_timeout lower so a stalled individual RPC command still fails promptly. Recent Prime Agent stderr is included in timeout and process-exit errors.

Session files are not wanted¶

Set persist_session: false. To retain sessions somewhere explicit, keep persist_session: true and set session_dir. Use one directory per concurrent automation worker to avoid accidental session reuse.