Skip to main content

optio-claudecode

Run Anthropic Claude Code as an optio task — either as a local subprocess or on a remote host over SSH — with the interactive TUI embedded in the optio dashboard via an iframe widget served by ttyd.

Install

pip install optio-claudecode

Requires Python 3.11+. Pulls optio-core, optio-host, and asyncssh.

On task start the package auto-installs the host binaries it needs unless told otherwise:

  • claude — via Anthropic's vendor script (https://claude.ai/install.sh)
  • ttyd — static binary from tsl0922/ttyd GitHub Releases

Quick start

from optio_claudecode import (
    ClaudeCodeTaskConfig,
    create_claudecode_task,
)

def get_tasks():
    return [
        create_claudecode_task(
            process_id="example-task",
            name="Example",
            config=ClaudeCodeTaskConfig(
                consumer_instructions="Please write a haiku about MongoDB.",
                credentials_json=load_user_creds_from_db(user_id),
                # Optional: skip interactive permission prompts for autonomous flows.
                permission_mode="bypassPermissions",
            ),
        )
    ]

credentials_json is treated as an opaque payload and written verbatim to <workdir>/home/.claude/.credentials.json (mode 0600) before claude launches. Format follows whatever Anthropic's CLI currently expects.

How it works

Each task gets a workdir tempdir (/tmp/optio-claudecode-<uuid>/). The ttyd process is launched with HOME=<workdir>/home, so claude reads all its state — credentials, settings, session history — strictly from the per-task workdir and never touches the host user's real ~/.claude/. Two tasks on the same host can run concurrently without shared-state races.

The agent is given a <workdir>/CLAUDE.md that includes the optio.log coordination protocol — STATUS: / DELIVERABLE: / DONE / ERROR — verbatim from optio_host.agents. The same protocol is used by optio-opencode, so the same consumer_instructions can be swapped between the two packages.

See docs/2026-05-28-optio-claudecode-design.md for the full design.

Messages

  • use_client_messages (bool, default False) — enable the CLIENT_MESSAGE: log keyword: the agent can push {keyword, data} messages to the browser session that launched the task (surfaced via optio-ui's onClientMessage).
  • on_caller_message (async callback, default None) — enable the CALLER_MESSAGE: log keyword: the agent can push {keyword, data} messages to your application. Signature (hook_ctx, keyword, data) -> str | None; a non-None return is sent back to the agent as feedback. Keywords that are not enabled are absent from both the parser and the agent-facing protocol documentation.

Conversation mode

With mode="conversation" the task runs claude headlessly (no ttyd, no iframe) over its bidirectional stream-json stdio protocol, and the launching code receives a live Conversation object — send messages, subscribe to events and answers, gate tool permissions, interrupt, close:

config = ClaudeCodeTaskConfig(
    consumer_instructions=None,   # defaults to a plain conversation prompt
    credentials_json=...,
    mode="conversation",
    host_protocol=False,          # no optio.log keyword channel
    permission_mode="acceptEdits",
)
# ... register the task, then:
conv = await optio.launch_and_await_result("example-task", session_id=None)
conv.on_message(lambda text: print("claude:", text))
await conv.send("hello")
await conv.close()

All new config fields default to existing behavior (mode="iframe", host_protocol=True, permission_gate=False), so existing callers run unchanged. See docs/2026-06-10-claudecode-conversation-gate-design.md.

Dashboard conversation UI

With the opt-in conversation_ui=True (conversation mode only) the task additionally starts a per-task listener that streams the raw conversation events (replay + live) through the optio widget proxy and accepts send / interrupt / permission requests, so the session can be monitored and driven from the browser. The matching React chat widget ships in the engine-neutral optio-conversation-ui package; register it in your host app via registerConversationWidget() (one registration serves both claudecode and opencode — each task self-declares its engine via widgetData.protocol). See docs/2026-06-10-claudecode-conversation-ui-design.md.

config = ClaudeCodeTaskConfig(
    consumer_instructions="",     # defaulted conversation prompt
    credentials_json=...,
    mode="conversation",
    conversation_ui=True,
    permission_gate=True,         # approve/deny tool use in the browser
)

Metadata

Release files for optio-claudecode 0.6.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for optio-claudecode 0.6.8
File Size Uploaded Provenance Actions
optio_claudecode-0.6.8.tar.gz 198.9 kB Without provenance Details for optio_claudecode-0.6.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for optio-claudecode 0.6.8
File Interpreter ABI Platform Actions
optio_claudecode-0.6.8-py3-none-any.whl Python 3 none any Details for optio_claudecode-0.6.8-py3-none-any.whl

Total release size: 301.4 kB

Release files / optio_claudecode-0.6.8.tar.gz

Download URL optio_claudecode-0.6.8.tar.gz
Size 198.9 kB
Tags Source
SHA-256 checksum
How to use checksums
cab3b135c61b58b3ebe3eeb182325b2423e66dd8975316e18ecf18a979d6e789
BLAKE2b-256 checksum
How to use checksums
1fb59c1a70a6f300cf4352f86ad4a806bd32bd54d32ea0fc231af6154bbb4272
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / optio_claudecode-0.6.8-py3-none-any.whl

Download URL optio_claudecode-0.6.8-py3-none-any.whl
Size 102.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
73023b07c70e11dd77f8caf05b5cf01b6d84f929b85d35af63a23f66e7af9a33
BLAKE2b-256 checksum
How to use checksums
b14fd4895f69242c7caa5d113a8b20f3bd2c236135c3abc7e1f41af285cdd579
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for optio-claudecode 0.6.8

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A 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.

Release history Release notifications | RSS feed

This release

0.6.8 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page