opencode-py 0.2.0

Python SDK for Opencode — the open source AI coding agent

Opencode Python SDK

Python SDK for Opencode — the open source AI coding agent.

pip install opencode-py

Quick start

One-shot (spawns server, asks, cleans up)

from opencode import opencode

answer = opencode("What is the capital of France?")
print(answer)

Context manager (recommended)

from opencode import Opencode

with Opencode() as ai:
    answer = ai.ask("Explain dependency injection")
    print(answer)

Streaming

with Opencode() as ai:
    for chunk in ai.ask_stream("Write a Python function"):
        print(chunk, end="")

Conversations

with Opencode() as ai:
    session = ai.create_session()
    msg1 = session.prompt("Suggest a project name")
    print(f"AI: {msg1}")
    msg2 = session.prompt("Now write a tagline for it")
    print(f"AI: {msg2}")

Multi-turn (keep mode)

from opencode import opencode

# keep=True — server and session stay alive between calls
r1 = opencode("My name is Alice", keep=True)
r2 = opencode("What's my name?", keep=True)   # remembers the conversation
r3 = opencode("That's all", keep=False)        # keep=False closes the server

Auto-tools (agentic tool execution)

r = opencode("Create a file called hello.txt", auto_tools=True)

Available tools: bash, write, edit, read, glob, grep.

By default, bash asks for permission in the console, all others run without prompting.

Custom permissions via Session.ask():

from opencode import Opencode, ToolExecutor

with Opencode() as ai:
    session = ai.create_session()
    msg = session.ask(
        "Write test.py with print('hello')",
        tool_executor=ToolExecutor(permissions={"write": "allow"}),
    )

Low-level API (any endpoint)

with Opencode() as ai:
    content = ai.client.file_read("src/main.py")
    diff = ai.client.vcs_diff("HEAD~3")
    config = ai.client.config_get()
    session = ai.client.session_create()
    ai.client.v2_session_prompt(session.id, {"text": "Hello"})

All client methods return typed Pydantic models — IDE autocomplete, validation, .model_dump(), .model_dump_json().

Retry & error handling

from opencode import OpencodeClient, RateLimitError, InternalServerError

client = OpencodeClient(max_retries=3)  # exponential backoff with jitter

try:
    health = client.health()
    print(health.version)
except RateLimitError:
    print("too many requests — retried but failed")
except InternalServerError:
    print("server error")

Debug logging

OPENCODE_LOG=debug python my_script.py

Shows all HTTP requests/responses with timing.

Web UI (zero dependencies)

python web/server.py
# → open http://127.0.0.1:3000

Built-in HTTP server + proxy to opencode serve — no extra dependencies.

Interactive dialog

python live.py

Multi-turn dialog with keep=True, server cleaned up on exit via atexit.

Configuration

with Opencode(
    model="claude-sonnet-4-20250514",
    directory="/path/to/project",
    port=4096,
) as ai:
    ...

Async API

import asyncio
from opencode import AsyncOpendcode

async def main():
    async with AsyncOpendcode() as ai:
        answer = await ai.ask("Explain async/await in Python")
        print(answer)

asyncio.run(main())

Async streaming

async with AsyncOpendcode() as ai:
    async for chunk in ai.ask_stream("Write a poem"):
        print(chunk, end="")

Async conversations

async with AsyncOpendcode() as ai:
    session = await ai.create_session()
    msg1 = await session.prompt("Suggest a project name")
    msg2 = await session.prompt("Now write a tagline for it")

Async low-level client

from opencode import AsyncOpendcodeClient

async with AsyncOpendcodeClient() as client:
    health = await client.health()
    print(health.version)  # typed Pydantic model

Development

# Install in editable mode
pip install -e ".[dev]"

# Run tests
pytest

# Build
python -m build --wheel