swebot-client

Python client for the swebot autonomous coding agent.

Pure Python — zero dependencies beyond the standard library.

Install

# pip
pip install swebot-client

# uv
uv add swebot-client

Quick start

import swebot

print(swebot.ask("explain goroutines"))

That is the whole ceremony for a one-shot question against a backend on localhost. Stream it instead, when you want to watch it arrive:

for token in swebot.stream("explain goroutines"):
    print(token, end="", flush=True)

Take a session when the second question depends on the first — a session IS the context that makes a follow-up a follow-up:

with swebot.session(agent="developer") as s:
    s.send("read parser.go")
    print(s.send("what would you change about it?"))

Elsewhere, or behind a token:

swebot.connect("http://10.0.0.5:8080", token="…")   # or set SWEBOT_TOKEN

And the full client is one call away — everything below is reachable from it:

client = swebot.Client(timeout=30)
client.set_mode("autonomous")
session = client.create_session(agent="developer")

The same library under two names

import swebot is the front door; swebot_client is the same objects under the name existing scripts already import. They can be mixed in one program — swebot.TurnFailed is swebot_client.TurnFailed, not a copy of it — so nothing has to be rewritten to use the shorter form, and an except clause keeps catching either way.

from swebot_client import SwebotClient     # unchanged, and staying

Features

• Streaming — real-time token-by-token output via SSE
• Tool callbacks — observe tool invocations and results
• Session management — create, resume, list, delete sessions
• Mode / model control — switch modes, models, thinking, reasoning
• Todos & checkpoints — read, create, update, delete todos; list/restore checkpoints
• MCP management — configure MCP servers programmatically
• Plugin management — install, remove, enable, disable plugins
• AgentSpeak — multi-agent collaboration (join, leave, send messages)
• Context control — compact or clear session context
• Skills — list built-in skill agents

Examples

from swebot_client import SwebotClient, ToolCall

client = SwebotClient("http://localhost:8080")
client.wait_until_ready(timeout=10)

# Set mode to autonomous so the agent executes (not plans)
client.set_mode("autonomous")

# Enable extended thinking
client.set_thinking("high")

# Switch model
client.set_model("claude-opus-4-5")

# Create a session and send a message
session = client.create_session(agent="developer")

def on_tool(tc: ToolCall):
    print(f"  ⚙ {tc.name}")

reply = session.send_with_events(
    "create a hello.py file",
    on_tool_start=on_tool,
)

# Read todos
for todo in session.get_todos():
    print(f"[{todo.status}] {todo.title}")

# Token usage
usage = session.token_usage()
print(f"Tokens: {usage['tokens_in']:,} in / {usage['tokens_out']:,} out ({usage['usage_pct']}%)")

Pipeline example

from swebot_client import SwebotClient

client = SwebotClient()
client.wait_until_ready()
client.set_mode("autonomous")

# Stage 1: generate
s1 = client.create_session()
code = s1.send("Write a Python prime sieve for 0-1000000")

# Stage 2: review
s2 = client.create_session("code_auditor")
review = s2.send(f"Review this code:\n{code}")
print(review)

API reference

Module-level calls

A backend that is not running gives a ConnectionError naming the address and telling you to start one, rather than a bare URLError from urllib.

The session ask and stream create is scratch: you never see its id, nothing can resume it, and a script asking a thousand questions would leave a thousand sessions behind. It is discarded when the answer is in — unless the session is still doing something, in which case it is left alone:

• a wake-up is scheduled — the turn asked to be resumed, and the session is how it comes back. (The same rule swebot's own one-shot CLI applies.)
• the turn is still running — an autonomous or goal continuation outlives the stream that started it, so a one-shot that set one going leaves it working rather than deleting it mid-turn.
• anything unknown — an older backend that does not report wake-ups, a request that fails. Deleting is the direction that cannot be undone.

The backend checks again as it deletes, so a wake-up scheduled by another backend between the check and the delete cannot be lost. keep=True holds on to the session regardless; swebot.session() is for when the conversation itself matters.

SwebotClient(addr="http://localhost:8080", token="", timeout=60.0, stream_timeout=None)

No token needed for a backend on your own machine. If it was started with --token (which a backend bound off loopback requires), set SWEBOT_TOKEN in your environment — the SDK reads it automatically.

timeout bounds ordinary requests, so a backend that accepts the connection and then stops answering cannot hang your script; wait_until_ready(timeout=…) passes its remaining time down to each probe. stream_timeout is separate and defaults to no deadline, because a turn streams for as long as it runs and a silent tool call of several minutes is normal.

Errors

A turn that fails — the provider erroring, a stall, a cancellation — raises TurnFailed from send(), stream() and send_with_events(). Whatever text arrived before the failure is on the exception as .partial:

from swebot_client import TurnFailed

try:
    answer = session.send("refactor the parser")
except TurnFailed as e:
    print("the turn failed:", e)
    print("partial output was:", e.partial)

These used to return the empty string, or the partial text, with nothing to distinguish a failed turn from a short answer.

ToolCall

What the agent did, as on_tool_start / on_tool_result see it: id, name, input, output, and two flags that are NOT the same question.

A refused tool is not a failed tool, and anything auditing what the agent actually did needs to tell them apart. examples/17_failures.py shows all three outcomes.

Sessions

Agents / Providers / Models

Mode / Thinking / Reasoning

MCP Servers

Scheduled work

Wake-ups (the agent's schedule tool) and cron jobs run in the backend, with or without a client connected — nothing here blocks on them. List and cancel them, and watch them fire with events(). See examples/19_scheduled.py.

Questions

session.ask("what does fitFrame do?") asks a question: it is send("? " + question). The backend answers at once, without the reasoning pre-analysis or the verify pass, and refuses every tool that writes or executes for that turn, so asking never changes files. session.ask(q, keep_mode=True) sends ?? q instead: the same quick answer, but the tools follow the session's mode rather than being blocked, so in autonomous mode the agent may change files if the answer needs it. See examples/20_questions.py.

Plugins

AgentSpeak (Multi-Agent)

Backend Management

Session

Messaging

Todos

Checkpoints

Context

Info

Publishing to PyPI

cd sdk/python
python3 -m build
UV_PUBLISH_TOKEN=pypi-YOUR-TOKEN uv publish dist/*

Requirements

• Python 3.9+
• A running swebot backend (swebot --serve)

License

MIT

Code review

Review what a session changed, then choose what to fix. Findings are verified by an adversarial second pass — only confirmed ones can be applied.

from swebot_client import SwebotClient

session = SwebotClient().create_session()
session.send("Add a ParseInt helper to util/parse.go")

rev = session.review(mode="informative")   # or "autonomous"
if rev.running:
    rev = session.wait_for_review(rev.id)

for f in rev.findings:
    print(f.id, f.severity, f.file, f.claim, "confirmed" if f.confirmed else "refuted")

keep = [f.id for f in rev.confirmed if f.blocking]
drop = [f.id for f in rev.confirmed if not f.blocking]
if keep:
    session.apply_review(rev.id, keep)
if drop:
    session.dismiss_findings(rev.id, drop, reason="not now")

A session that changed no files returns scope="out_of_scope" (or "nothing_to_review") without calling a model at all.

Inspect language-server reports

session.lsp_diagnostics("pyright") reads the backend's cached project diagnostics without starting a server or asking the agent to repair files. Each report includes file, line, column, severity and message. Missing imports can indicate environment setup, not code defects. See examples/22_lsp_diagnostics.py.

Headless deployment capability

client.deploy_capabilities() reads authenticated GET /api/deploy. headless_deploy >= 1 supports API-key-only all and independent remote headless authentication. This check neither deploys nor transfers credentials. An older backend's HTTP error is preserved: update it rather than falling back to legacy deployment that might copy OAuth tokens. See examples/23_deploy_capabilities.py. Use the TUI /backend remote auth REMOTE for interactive, masked login; no browser is launched automatically.

Interactive deployment HTTP protocol (NDJSON)

See examples/python/deploy_http.py for a complete standard-library client. Unlike the CLI remote_deploy_pipeline.py, it keeps the deployment stream open while sending separate answer requests, masks secret input and cancels on Ctrl+C/EOF. No new public SDK helpers or PyPI release: 0.14.5 already provides deploy_capabilities().

export SWEBOT_ADDR=http://localhost:8080
# Set SWEBOT_TOKEN securely if the source backend requires authentication.
python examples/python/deploy_http.py user@host:2222 --port 8080 --auth anthropic
python examples/python/deploy_http.py user@host --all --auth openai

All requests use the source backend's bearer token. SSH, downloads and saved credential reads run on that backend, not this client. Use trusted HTTPS or a protected local transport for credentials.

1. Preflight: GET /api/deploy must return {"headless_deploy":1} (or a higher supported version). Reject 404/unsupported responses: a legacy backend may ignore auth options and copy OAuth tokens. Capability support does not guarantee deployment availability: POST returns 501 if the backend lacks its deployment binary callback.
2. Start: POST /api/deploy with JSON:

   {"Target":"user@host:2222","Port":8080,"All":false,"Auth":true,"AuthProvider":"anthropic"}
   

   Target is the SSH destination (2222 is SSH port). Required Port is backend port, 1–65535. All selects saved Anthropic/OpenAI/Google/Alibaba API keys only, never OAuth/login tokens. Auth requests independent remote authentication; AuthProvider selects a provider, or empty string offers a menu. Auth-only (Auth:true, All:false) skips local credential transfer; All:true, Auth:true combines transfer and login. Without either, offer saved API keys individually.
3. Read NDJSON (one JSON object per line, not SSE):

   {"text":"Installing binary…"}
   {"text":"Choose provider","question":"opaque-id","input":true,"choices":["anthropic","openai"],"secret":false,"url":"","code":""}
   {"text":"Enter API key","question":"another-id","input":true,"choices":null,"secret":true,"url":"","code":""}
   {"text":"Authorize manually","url":"https://provider.example/authorize","code":"DEVICE-CODE"}
   {"text":"","done":true,"failed":false}
   

   Illustrative events, not a fixed sequence or complete menu. Show text, URLs and device codes; do not auto-open a browser or use the clipboard. Events without question require no reply. Submit exact displayed choice strings. Mask secret:true input; never log answers, bodies or authorization headers.
4. Answer on a separate connection: POST /api/deploy/answer with {"question":"opaque-id","value":"choice or secret"}; response {"accepted":true}. Legacy boolean yes still supports yes/no prompts; string value takes precedence. Questions are single-use; expired or consumed IDs return 404. Keep the original streaming request open.
5. Finish/cancel: done:true, failed:false means deployment completed, not necessarily backend startup. Installation without usable credentials succeeds unstarted: preserve progress and follow its hints. failed:true carries sanitized failure text. EOF without done leaves outcome unknown. Closing the stream requests cancellation; the backend also enforces a 20-minute deadline. Completed installation/settings are not rolled back and existing backends are not stopped. Verify remote state before retrying after cancellation or transport failure.

Remote connection and lifecycle HTTP API

These authenticated routes also execute on the source backend. No public SDK stream/lifecycle helpers exist; the HTTP example uses urllib. Existing SwebotClient can use a proxy as its base URL without a new package release.

Connections are process-local, expire after 24 hours and require the source backend to stay up. Requests forwarded through missing/expired proxies return 404; SSH transport failures return 502. Deletion is idempotent and returns {"closed":true} even for a missing or expired ID. Reconnect after expiry/source restart. Proxy deletion is not backend shutdown. The CLI pipeline demonstrates tasks against a running destination; installation-only success is not proof it is ready for those tasks.

Named backend inventory (0.14.6)

GET /api/backends returns remotes (name -> SSH target) and backends (REMOTE/NAME -> name/remote/workspace/port). POST /api/backends/action takes action and fields: remote-add (name,target), remote-remove/remove (name), save/create-local (backend, optional create_directory; create-local accepts auto_port to skip occupied/saved ports), refresh (optional remote name), prepare/start/stop/logs/ connect (name; create_directory for prepare). Stop is explicit caller authorization; HTTP does not add TUI consent. Refresh returns running/stopped/unreachable per key. Logs returns bounded logs; connect returns proxy id using source bearer token. Existing DELETE /api/connect/{id} closes proxy, not executor. New named databases are isolated; old data untouched. See examples/24_named_backends.py.

Existing HTTP/CLI clients remain compatible despite TUI slash consolidation. Deployment NDJSON adds optional Backend definition and InstallOnly; clients provide workspace and answer directory/credential decisions explicitly.

Authenticated SDK requests and streams reject HTTP redirects rather than forward bearer credentials. Use the backend URL directly, including its proxy base path.

Remote uninstall

Existing backend_action() also supports uninstall on an updated backend/target:

# Destructive operation: call only after obtaining user confirmation.
# Stop target swebot processes first. Normal mode preserves settings/sessions.
client.backend_action("uninstall", name="lab", target="user@host",
                      full=False, confirmed=True)
# full=True permanently removes standard swebot credentials, settings and databases.
# Workspace files/external databases and source inventory are not deleted.

The target must exactly match backend_inventory()["remotes"]["lab"]. Errors are not converted to success or retried with broader deletion. No new SDK method or package release is required for this action.