메뉴
Codex CLI, OpenCode CLI, and Pi CLI runner protocols for Untether. Covers JSONL event types, event translation, resume mechanisms, and key differences between engines. All three are non-interactive (no control channel).
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Release workflow for Untether — issue audit, version decisions, changelog drafting, pre-release validation, tagging, and post-release verification. Use when preparing a release or debugging release failures.
Untether overall architecture, event model, data flow, config system, engine backend registration, progress tracking, approval notifications, ephemeral cleanup, and key abstractions. Use when working on core infrastructure or understanding how the pieces fit together.
Claude Code CLI stream-json protocol as consumed by Untether. Covers JSONL event types, content blocks, control channel protocol, permission modes, auto-approve, progressive cooldown, and ExitPlanMode handling. This is the CONSUMER side — Untether spawns Claude Code as a subprocess.
Raw Telegram Bot API patterns used by Untether. Covers httpx async HTTP client, inline keyboards, callback queries, long polling, rate limiting, outbox model, forum topics, voice transcription, and media group coalescing. NOT aiogram, python-telegram-bot, or grammY — Untether uses raw HTTP.
JSONL subprocess management patterns for Untether engine runners. Covers JsonlSubprocessRunner base class, template methods, event translation, session locking, resume tokens, process lifecycle, PTY usage, and concurrent session registries.
Prepare and ship a Untether release. Use when asked to cut a release, bump release versions, update changelog/spec/readme, tag v<major.minor.patch>, or trigger the GitHub release workflow.
| name | codex-opencode-pi |
| description | Codex CLI, OpenCode CLI, and Pi CLI runner protocols for Untether. Covers JSONL event types, event translation, resume mechanisms, and key differences between engines. All three are non-interactive (no control channel). |
| triggers | ["working on Codex runner code","working on OpenCode runner code","working on Pi runner code","adding support for a new engine","comparing engine event models","debugging non-Claude runner streams"] |
These three engines are non-interactive only — no control channel, no permission prompts. They extend JsonlSubprocessRunner directly (unlike ClaudeRunner which overrides run_impl).
| Aspect | Codex | OpenCode | Pi |
|---|---|---|---|
| CLI | codex exec --json | opencode run --format json | pi --print --mode json |
| Event model | Turn-based (items in turns) | Step-based (tools in steps) | Agent-based (messages + tools) |
| Resume line | `codex resume <thread_id>` | `opencode --session ses_XXX` | `pi --session <token>` |
| Resume token | thread_id (UUID) | ses_XXXX (26+ chars) | UUID short (8 chars) or path |
| Final answer | agent_message item | Accumulated text events | message_end assistant content |
| Error signal | turn.failed | error event / missing step_finish | stopReason in message_end |
| File | Purpose |
|---|---|
src/untether/runners/codex.py | CodexRunner implementation |
src/untether/schemas/codex.py | msgspec structs for Codex events |
docs/reference/runners/codex/exec-json-cheatsheet.md | JSONL event shapes |
docs/reference/runners/codex/untether-events.md | Event mapping spec |
codex exec --json --skip-git-repo-check --color=never \
[--model MODEL] [--session THREAD_ID -] [-]
- means read stdin)--session <thread_id> ---skip-git-repo-check --color=never for clean output| Event | Untether mapping |
|---|---|
thread.started | StartedEvent(resume=thread_id) |
item.started | ActionEvent(phase="started") |
item.updated | ActionEvent(phase="updated") |
item.completed | ActionEvent(phase="completed") |
turn.completed | CompletedEvent(ok=True, answer=final_answer) |
turn.failed | CompletedEvent(ok=False, error=message) |
error (transient) | Progress note (reconnect handling) |
| Item type | ActionKind | Notes |
|---|---|---|
command_execution | command | ok = (status=="completed" && exit_code==0) |
mcp_tool_call | tool | Title: server.tool |
file_change | file_change | detail.changes = [{path, kind}] |
web_search | web_search | Title: query |
todo_list | note | detail.done, detail.total |
reasoning | note | Reasoning text |
agent_message | (not emitted) | Stored as final answer candidate |
error (item) | warning | Non-fatal error |
Multiple agent_message items may appear. Selection:
phase == "final_answer"agent_messageCompletedEvent.answer[codex]
profile = "Codex" # Codex profile name
extra_args = [] # additional CLI flags
| File | Purpose |
|---|---|
src/untether/runners/opencode.py | OpenCodeRunner implementation |
src/untether/schemas/opencode.py | msgspec structs for OpenCode events |
docs/reference/runners/opencode/runner.md | Runner spec |
docs/reference/runners/opencode/stream-json-cheatsheet.md | JSONL event shapes |
docs/reference/runners/opencode/untether-events.md | Event mapping spec |
opencode run --format json [--session SESSION_ID] [--model MODEL] -- <prompt>
----session ses_XXXses_ prefix + 20+ chars| Event | Untether mapping |
|---|---|
step_start (first, with sessionID) | StartedEvent(resume=sessionID) |
tool_use (status="completed") | ActionEvent(phase="completed", ok=exit==0) |
tool_use (status="error") | ActionEvent(phase="completed", ok=False) |
text | Accumulated as final answer (no action) |
step_finish (reason="stop") | CompletedEvent(ok=True, answer=text) |
error | CompletedEvent(ok=False, error=message) |
| Tool | ActionKind |
|---|---|
bash, shell | command |
edit, write, multiedit | file_change |
read, glob, grep | tool |
websearch, web_search, webfetch, web_fetch | web_search |
todowrite, todoread | note |
task | tool |
| (other) | tool |
Usage accumulation: OpenCode's step_finish may include token/cost data but the runner does not currently extract it. CompletedEvent.usage is not populated.
[opencode]
model = "claude-sonnet-4-5-20250929"
| File | Purpose |
|---|---|
src/untether/runners/pi.py | PiRunner implementation |
src/untether/schemas/pi.py | msgspec structs for Pi events |
docs/reference/runners/pi/runner.md | Runner spec |
docs/reference/runners/pi/stream-json-cheatsheet.md | JSONL event shapes |
docs/reference/runners/pi/untether-events.md | Event mapping spec |
pi --print --mode json [--session SESSION_PATH] \
[--provider PROVIDER] [--model MODEL] <prompt>
-)--session <token> (short ID or full path)NO_COLOR=1, CI=1 (set by runner)| Event | Untether mapping |
|---|---|
session | Session ID extraction, possible ID promotion |
agent_start | StartedEvent(resume=session_token) |
tool_execution_start | ActionEvent(phase="started") |
tool_execution_end | ActionEvent(phase="completed", ok=!isError) |
message_end (assistant) | Final answer + usage stored |
agent_end | CompletedEvent(ok=..., answer=last_text) |
Pi has a unique resume mechanism:
.jsonl file pathsession header arrives with a UUID, the resume token is promoted to the 8-char short IDallow_id_promotion flag ensures this only happens onceSession path format: ~/.pi/agent/sessions/--<sanitized-cwd>--/<date>-<uuid>.jsonl
| Tool | ActionKind | Title source |
|---|---|---|
bash | command | args.command |
edit, write | file_change | args.path |
read, grep, find, ls | tool | tool: <path> or tool: <pattern> |
| (other) | tool | tool name |
stopReason in message_end: "error" or "aborted" -> ok=Falseagent_end received -> CompletedEvent(ok=False, error="stream ended...")[pi]
provider = "anthropic" # or "openai", "google", etc.
model = "claude-sonnet-4-5-20250929"
extra_args = []
To add a new engine runner:
src/untether/runners/myengine.pysrc/untether/schemas/myengine.pyMyEngineRunner(JsonlSubprocessRunner) with required template methodsBACKEND = EngineBackend(id="myengine", build_runner=..., cli_cmd="myengine")pyproject.toml entry points:
myengine = "untether.runners.myengine:BACKEND"
docs/reference/runners/myengine/tests/test_*_runner.py patterns