Coding agents in the terminal

A coding agent running inside a terminal (Claude Code today, Codex later) is treated as a first-class citizen. Terax detects its state transitions and routes them into the same notification surface as the built-in agent.

Detection

Detection is Rust-side, on the PTY reader's byte filter (pty/agent_detect.rs). It arms on OSC 133;C;<cmd> (the OSC 133 command-start marker emitted by shell integration) and watches for an explicit OSC 777 signal containing one of:

• started
• working
• attention
• finished
• exited

The marker self-arms the detector. Detection works in any shell - bash, zsh, pwsh, even inside tmux - without a shell preexec hook.

Crucially, transitions are only triggered by explicit OSC sequences, never by raw output. A TUI that repaints rapidly never flaps the notification state.

When no terminal agent is running, the byte filter is a no-op. Zero cost.

Claude Code hooks

Claude Code lost /dev/tty access in v2.1.139, so it cannot emit OSC sequences directly from its main process. Instead, Terax installs Claude Code hooks that return an OSC 777 marker through the terminalSequence field of the hook response.

Install with one click in Settings -> Agents -> Enable Claude Code hooks. The command is agent_enable_claude_hooks.

What gets installed

Three hooks in ~/.claude/settings.json, gated on TERAX_TERMINAL:

• UserPromptSubmit -> working
• Notification -> attention
• Stop -> finished

Each hook is a one-line shell command that prints a JSON object with terminalSequence set to an OSC 777;notify;Terax;<event> sequence. The TERAX_TERMINAL guard makes the hooks no-ops outside Terax, so they will not interfere when you run Claude Code in another terminal.

Safety

The installer is paranoid:

• Reads the existing settings.json and rejects if the file is present but not valid JSON. Never clobbers.
• Atomic write (temp file plus rename).
• Migrates older Terax-owned hooks from the pre-v2.1.139 /dev/tty variant.
• Prunes empty hook groups left behind by manual edits.
• Idempotent - re-running migrates rather than duplicates.

Status

agent_claude_hooks_status checks whether the hooks are currently installed. The Settings toggle reads from this.

To uninstall, flip the toggle off. Terax removes only the hooks it owns (identified by the notify;Terax; marker in the command string) and leaves any other hooks in your config untouched.