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

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.7.1
File Size Uploaded Provenance Actions
optio_claudecode-0.7.1.tar.gz 282.7 kB Without provenance Details for optio_claudecode-0.7.1.tar.gz

Built distribution (wheel)

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

Total release size: 415.8 kB

Release files / optio_claudecode-0.7.1.tar.gz

Download URL optio_claudecode-0.7.1.tar.gz
Size 282.7 kB
Tags Source
SHA-256 checksum
How to use checksums
2adf62c64b3c0d1a04b678d811b0cd0f110adfd90d1e51cc6d0ccd4391c3e661
BLAKE2b-256 checksum
How to use checksums
85b58eed8b7960543a901c8d9d621197608de07f547bfa68e0c8bb6ee31b9b6e
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.7.1-py3-none-any.whl

Download URL optio_claudecode-0.7.1-py3-none-any.whl
Size 133.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
39a548093fbff650a74cd1c3a7b19d256f187270b75e24f4f93f3f33f20668cd
BLAKE2b-256 checksum
How to use checksums
97b3d961f4bac2ed5903be201b23858ee5fde706a7c2484fbb0adbbac190f942
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.7.1

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