swytchcode-runtime (Python)
Thin runtime wrapper around the Swytchcode CLI. Calls swytchcode exec for you so you can stay in Python without shell boilerplate.
Requires: The swytchcode CLI must be installed. The binary is located automatically - no configuration needed in most environments. Resolution order:
SWYTCHCODE_BINenv var - explicit override.$PATHlookup viashutil.which- the standard system resolution.- Common install paths -
~/.local/bin,/usr/local/bin(Unix) or%LOCALAPPDATA%\Programs\swytchcode\bin(Windows).
Install
pip install swytchcode-runtime
Or from the repo:
pip install /path/to/runtime-libraries/python-runtime
Use
JSON mode (default)
from swytchcode_runtime import exec
result = exec("api.account.create", {"email": "test@example.com"})
# result is parsed JSON (any)
Equivalent to: swytchcode exec api.account.create --json with args on stdin.
Request input (args): The second argument is the kernel args object (sent as JSON on stdin). Use this shape so the kernel builds the request correctly:
- body - Request body (dict).
- params - Query/path params (e.g.
{"id": "cluster-123"}). - Authorization - Auth header value (e.g.
"Bearer token123"). - headers - Additional request headers (e.g.
{"X-Request-Id": "abc-123"}). - Other top-level keys are passed as query params.
Example with body, params, and headers:
exec("api.cluster.get", {
"params": {"id": "cluster-123"},
"Authorization": "Bearer token123",
"headers": {"X-Request-Id": "abc-123"},
})
Raw mode
Get stdout as a string instead of parsing JSON:
from swytchcode_runtime import exec
output = exec("api.report.export", {"id": "123"}, raw=True)
# output is the raw stdout string
Options
- cwd - Working directory for the process (default: current directory).
- env - Extra environment variables (merged with
os.environ). - raw - If
True, use--rawand return stdout as a string. - dry_run - If
True, pass--dry-runto the CLI; request details (method, url, headers, body) are output instead of calling the server. - allow_raw - If
True, pass--allow-rawto the CLI; required for executing raw methods (kernel has this disabled by default). - tenant_id - Run the call for one end user of your app, with their own connected account (passes
--tenant). Never falls back to your account. See Multi-tenant apps. - tenant_label - How approvers see that end user, e.g.
"Alice Smith (alice@acme.com)"(passes--tenant-label). Needstenant_id.
This runtime invokes swytchcode exec [canonical_id] with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
Environment variables
This runtime itself needs no environment configuration to run - all auth lives in the CLI's own session (swytchcode login, stored under ~/.swytchcode/) or in .swytchcode/ in your project. The variables below are for the rarer cases where you need to override that:
| Variable | Description |
|---|---|
SWYTCHCODE_BIN |
Override the resolved binary path. Set this only when automatic resolution does not find the correct binary (e.g. non-standard install locations or virtualised environments). |
SWYTCHCODE_TOKEN |
Service-token auth for headless environments (CI, servers) where an interactive swytchcode login isn't possible. Not needed for local development once you've run swytchcode login. |
Error handling
Failures raise SwytchcodeError (spawn error, non-zero exit, invalid JSON). Use the helper to narrow:
from swytchcode_runtime import exec, SwytchcodeError, is_swytchcode_error
try:
exec("api.account.create", {"email": "test@example.com"})
except Exception as e:
if is_swytchcode_error(e):
print(e.message, e.cause)
raise
On a non-zero exit the CLI writes a classified JSON error to stderr; exec() parses it into a clean .message and a structured .details dict (category, retryable, suggested_action, docs_url) instead of leaving you to parse the raw JSON yourself:
except SwytchcodeError as e:
if e.details and e.details.get("category") == "auth":
print(e.details.get("suggested_action"))
Multi-tenant apps
When your app's own users each connect their accounts, pass your id for the logged-in user (from your server's session, never from the browser) on every call made for them:
from swytchcode_runtime import connect, save_key, save_credentials, disconnect, exec, Swytchcode
url = connect("gmail", user.id)["url"] # one-time link (OAuth), open it from the user's click
save_key("stripe", user.id, key) # API-key providers: stored on your server only
save_credentials("coinswitch", user.id, # signed requests (crypto exchanges): every field
{"api_key": api_key, "secret_key": secret_key}) # the exchange needs, stored on your server only
exec("gmail.user.profile.get", {"params": {"userId": "me"}}, tenant_id=user.id)
client = Swytchcode(provider, tenant_id=user.id) # agents: every tool runs for this user
disconnect("gmail", user.id)
An end user who has not connected raises SwytchcodeError with details["category"] == "tenant_not_connected". For exchanges that sign every request, save_credentials() takes the fields the provider's signing recipe names (for example api_key, secret_key and passphrase); the CLI signs each of that user's requests with them. Guide: https://docs.swytchcode.com/guides/multi-tenant/
What this library is
- A thin process wrapper over the Swytchcode shell.
- A stable call surface:
exec(canonical_id, input=None, *, cwd=..., env=..., raw=...). - A convenience for developers and IDE agents.
What this library is not
- An HTTP SDK or API client.
- A replacement for the shell. All authority stays in the Swytchcode CLI.
This library must not and does not:
- Read
.swytchcode/*or parsetooling.json. - Validate schemas or add retries/timeouts.
- Call the registry or embed auth logic.
It is a pipe, not a brain.
For Cursor / IDE agents
Generate code that uses this runtime instead of subprocess boilerplate.
Preferred:
from swytchcode_runtime import exec
def create_account(input: dict) -> any:
return exec("api.account.create", input)
Avoid: subprocess boilerplate, HTTP calls, or config parsing. Use exec(...) and let the CLI handle execution and policy.
Agentic workflows (framework integrations)
For full, production-ready examples across all major frameworks, check out the Swytchcode Examples Repository.
On top of exec, the runtime exposes a small agentic surface that turns Swytchcode tools into the native tool objects each agent framework expects.
Tool-use guidance - TOOL_USE_INSTRUCTIONS
Without an explicit nudge, models can be conservative about side-effecting actions (starring a repo, sending a payment, creating an issue) - they'll describe what they would do instead of actually calling the tool. TOOL_USE_INSTRUCTIONS is a short, framework-agnostic string that fixes this; concatenate it into whatever your provider calls its system prompt / instructions. It's scoped to only the tools this library provides, so it's safe to combine with instructions for other, unrelated tools in the same system prompt:
from swytchcode_runtime import TOOL_USE_INSTRUCTIONS
system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
Quickstart: Anthropic SDK
Here is a clean example of building a simple agent using the Anthropic SDK. It stars the Swytchcode Examples repo on GitHub - a genuine OAuth-connected action (not just an API key passed on the request), so the setup below covers the real one-time flow: installing the CLI, logging in, and connecting a GitHub account.
One-time setup (run once per machine/project):
# 1. Install the CLI (macOS/Linux; see https://cli.swytchcode.com for other platforms)
curl -fsSL https://cli.swytchcode.com/install.sh | sh
# 2. Scaffold .swytchcode/ + tooling.json in your project
swytchcode init
# 3. Fetch the GitHub integration
swytchcode get github
# 4. Enable the "star a repo" tool - the trust boundary for what this project can call
swytchcode add method github.user.starred.update
# 5. Connect your GitHub account (opens a browser for the OAuth flow)
swytchcode auth connect github
Then add your Anthropic key to a .env file in your project root (used by python-dotenv below):
# .env
ANTHROPIC_API_KEY=sk-ant-...
Installation:
pip install swytchcode-runtime anthropic python-dotenv
(Note: You only need to install the SDK for the framework you are actually using. You do not need to install openai-agents or langchain if you are only using Anthropic. The swytchcode-runtime isolates these dependencies via lazy loading.)
Example:
import os
from dotenv import load_dotenv
import anthropic
from swytchcode_runtime import Swytchcode, TOOL_USE_INSTRUCTIONS
from swytchcode_runtime.providers.anthropic import AnthropicProvider
load_dotenv() # Loads .env automatically
def run_agent():
client = anthropic.Anthropic()
# 1. Initialize Swytchcode with the Anthropic provider
swx = Swytchcode(provider=AnthropicProvider())
# 2. Fetch the tools you want your agent to use (e.g., GitHub tools)
tools = swx.tools.get(toolkits=["github"])
# 3. Build the system prompt: your own instructions plus TOOL_USE_INSTRUCTIONS,
# which tells Claude to call the tool directly for action requests instead of
# just describing what it would do
system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
messages = [{"role": "user", "content": "Star the swytchcodehq/swytchcode-examples repo on GitHub for me."}]
# 4. Loop until Claude stops requesting tool calls: run any tool calls
# Claude made and send the results back so it can keep working toward
# a final natural-language reply instead of stopping after one round
while True:
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
system=system,
tools=tools,
messages=messages,
)
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason == "max_tokens":
raise RuntimeError("Response truncated at max_tokens - increase the limit and retry")
if response.stop_reason != "tool_use":
break
tool_results = swx.handle_tool_calls(response)
messages.append({"role": "user", "content": tool_results})
for block in response.content:
if block.type == "text":
print(block.text)
if __name__ == "__main__":
run_agent()
Selecting tools - swx.tools.get(...)
Pass exactly one selector; IDs resolve against your local Swytchcode state and remote search:
toolkits=["stripe"]- every enabled tool whose integration matches a toolkit.tools=["charges.charge.create"]- explicit canonical IDs.search="refund a charge"- natural-language discovery (viaswytchcode discover).
Each returned tool carries a full input schema - every field is surfaced to the model, with
only the truly-required ones marked required - and an execute callback that runs swytchcode exec for you (empty optional values are stripped before the call so APIs like Stripe don't reject them).
Supported providers
| Framework | Import | Who runs the tool loop |
|---|---|---|
| Anthropic Claude | from swytchcode_runtime.providers.anthropic import AnthropicProvider |
you (Messages API + swx.handle_tool_calls) |
| OpenAI Agents SDK | from swytchcode_runtime.providers.openai_agents import OpenAIAgentsProvider |
the SDK |
| Vercel AI SDK | from swytchcode_runtime.providers.vercel import VercelProvider |
the SDK |
| LangGraph | from swytchcode_runtime.providers.langgraph import LangGraphProvider |
the prebuilt agent |
| CrewAI | from swytchcode_runtime.providers.crewai import CrewAIProvider |
the crew |
Non-agentic APIs (Anthropic Messages)
When you run the tool loop yourself, handle_tool_calls executes each tool_use block and
returns the tool_result blocks to send back:
import anthropic
client = anthropic.Anthropic()
msg = client.messages.create(
model="claude-sonnet-5", max_tokens=1024, tools=tools,
messages=[{"role": "user", "content": "Refund charge ch_123 for $20"}],
)
results = swx.handle_tool_calls(msg) # runs the tool calls, returns tool_result blocks
One runnable file per framework lives in sdk-examples/. Install the matching framework SDK
(pip install openai-agents / anthropic / ai / langgraph / crewai) alongside the
swytchcode CLI.
Metadata
Release files for swytchcode-runtime 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| swytchcode_runtime-1.2.0.tar.gz | 31.6 kB | With provenance | Details for swytchcode_runtime-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| swytchcode_runtime-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for swytchcode_runtime-1.2.0-py3-none-any.whl |
Total release size: 59.3 kB
Release files / swytchcode_runtime-1.2.0.tar.gz
| Download URL | swytchcode_runtime-1.2.0.tar.gz |
|---|---|
| Size | 31.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8a11405726a9a6c4d77a43270e96361731a869355624217b684b129ae50f2689
|
|
BLAKE2b-256 checksum How to use checksums |
0ab6e1e25c9d8946f98f37f45e0154dc3274a8da359a862523cf0b12ddf93530
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logRelease files / swytchcode_runtime-1.2.0-py3-none-any.whl
| Download URL | swytchcode_runtime-1.2.0-py3-none-any.whl |
|---|---|
| Size | 27.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4dad48eb6043f5908a7688382f56a990321b2aa781d5e2009f3e186826b70a11
|
|
BLAKE2b-256 checksum How to use checksums |
b506d7ac3ca6985b0c074520f65f977a093afce192bdb53b23e05268589da6e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logSecurity for swytchcode-runtime 1.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for swytchcode_runtime-1.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.