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

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.2
File Size Uploaded Provenance Actions
optio_claudecode-0.7.2.tar.gz 281.5 kB Without provenance Details for optio_claudecode-0.7.2.tar.gz

Built distribution (wheel)

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

Total release size: 414.6 kB

Release files / optio_claudecode-0.7.2.tar.gz

Download URL optio_claudecode-0.7.2.tar.gz
Size 281.5 kB
Tags Source
SHA-256 checksum
How to use checksums
a5ba6fbec9b034716e479e53527643ddaef3bb05c73ddb8f5936584d5b762741
BLAKE2b-256 checksum
How to use checksums
9580782557b385519174fd7f754fbbe6bef7276aae926f3ae4ca744c5a63f55a
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.2-py3-none-any.whl

Download URL optio_claudecode-0.7.2-py3-none-any.whl
Size 133.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a2dd59f064d1e1f7f85840eb2aa08c2702b4a0934c88eb8cf480c1b6a9c61307
BLAKE2b-256 checksum
How to use checksums
89f989d1277377cb7d6c5f58961add7cb808692ff2b7a9821ae6d744fded9481
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.2

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