untether: Skill for Claude Code

JSONL Subprocess Runner Framework

All Untether engine runners (Claude, Codex, OpenCode, Pi; deprecated Gemini and AMP) extend JsonlSubprocessRunner, which manages subprocess lifecycle, JSONL parsing, session locking, and error handling.

Key files

Class hierarchy

Runner (Protocol)
  BaseRunner (SessionLockMixin)
    JsonlSubprocessRunner
      CodexRunner
      OpenCodeRunner (wraps run_impl: refuses OpenCode 2.x before spawning, #970)
      PiRunner
      GeminiRunner, AmpRunner (deprecated, unsupported)
      ClaudeRunner (overrides run_impl for PTY support)
  (each concrete runner also mixes in ResumeTokenMixin)

Template methods to override

When creating a new runner, override these methods on JsonlSubprocessRunner:

class MyRunner(JsonlSubprocessRunner):
    engine: EngineId = "myengine"

    def command(self) -> str:
        """CLI binary name (e.g. 'codex', 'opencode', 'pi')."""

    def build_args(self, prompt, resume, *, state) -> list[str]:
        """Build CLI arguments. Called once per run."""

    def translate(self, data, *, state, resume, found_session) -> list[UntetherEvent]:
        """Translate a decoded JSON dict to Untether events. Core logic."""

    def new_state(self, prompt, resume) -> Any:
        """Create per-run state (e.g. EventFactory, accumulators)."""

    # Optional overrides:
    def stdin_payload(self, prompt, resume, *, state) -> bytes | None:
        """Data to send on stdin. Default: prompt.encode()."""

    def env(self, *, state) -> dict[str, str] | None:
        """Extra environment variables for the subprocess."""

    def decode_jsonl(self, *, line: bytes) -> Any | None:
        """Custom JSON decoder. Default: json.loads."""