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 fromtsl0922/ttydGitHub 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, defaultFalse) — enable theCLIENT_MESSAGE:log keyword: the agent can push{keyword, data}messages to the browser session that launched the task (surfaced via optio-ui'sonClientMessage).on_caller_message(async callback, defaultNone) — enable theCALLER_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.