Coding agent integrations

Coding Agent Integrations

QuickTTY treats coding-agent integration as three separate capabilities. Use only the layer you need; installing one does not silently enable the others.

Install integrations explicitly

Open QuickTTY → Agent Integrations…, choose Install or Uninstall, select eligible agents, inspect every planned file change, and confirm before Apply. The sheet and bundled CLI use the same installer core.

Native session restoration

When quicktty-restore-workspaces and quicktty-restore-agent-sessions are both true, QuickTTY may relaunch a version-verified agent with its opaque native session ID in the original pane. This is not PTY/process checkpointing. There is no arbitrary command or environment persistence; QuickTTY performs no output/title/process/store inference, and uses a fixed bundled quicktty trampoline with structured argv and a bounded canonical payload. Any ineligible binding takes the fresh shell fallback.

The authenticated local socket is scoped by five app-owned pane variables: QUICKTTY_PANE_ID, QUICKTTY_AGENT_SOCKET, QUICKTTY_INSTANCE_ID, QUICKTTY_PANE_TOKEN, and QUICKTTY_AGENT_HELPER. On shutdown, registration freezes, credentials are cleared, and later lifecycle messages are rejected.

Exact 20-entry registry

Totals: 11 native, 3 wrapper, and 6 blocked. Only Pi has a locally and runtime-verified launch policy: installed Pi versions reporting a valid semantic version and exposing the required public lifecycle extension API are accepted, and the integration is locally verified on current Pi 0.84.4. Every other launch-capable version policy is unverified/documented and therefore starts a fresh shell until a verified policy and tests are added.

Explicit installer

quicktty integrations status [ids...]
quicktty integrations install [ids...] [--yes]
quicktty integrations uninstall [ids...] [--yes]

Install and uninstall always show a mutation preview and require explicit confirmation: type the literal yes in a TTY, or place --yes last for non-interactive use. Existing files receive uniquely named backups. QuickTTY tracks ownership and uninstalls only matching owned content; conflicts and changed files are not overwritten. The Agent Integrations sheet uses the same core and makes no silent configuration writes. For Pi, one preview includes its lifecycle extension, the terminal SKILL at ~/.pi/agent/skills/quicktty-terminal/SKILL.md, and the shared launcher ~/.local/bin/quicktty when it is missing.

The sheet reports bounded states and redacted diagnostics without raw session IDs. Pane bindings show Active, Restoring, Unverified, or Failed. Retry rotates credentials and rechecks compatibility; Forget removes the binding and starts a fresh shell. Duplicate adapter/session claims all fail rather than selecting a winner.

OSC progress

Progress setup is independent from session restoration. Manual progress-only examples remain bundled at:

/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/

Claude Code 2.1.141+

Claude Code command hooks have no controlling TTY. In claude mode, the helper emits one JSON object containing the universal terminalSequence field and writes nothing else to stdout.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude working"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude waiting"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt|agent_needs_input",
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude waiting"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude working"
          }
        ]
      }
    ],
    "PostToolUseFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude working"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude completed"
          }
        ]
      }
    ],
    "StopFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude failed"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude completed"
          }
        ]
      }
    ]
  }
}

Event mapping

• UserPromptSubmit → working.
• PermissionRequest → waiting.
• Notification matching permission_prompt|idle_prompt|agent_needs_input → waiting.
• PostToolUse and PostToolUseFailure → working.
• Stop and SessionEnd → completed.
• StopFailure → failed.

The hook reads no stdin, prompt, transcript, or environment secrets.

Codex

Codex keeps its controlling TTY. In codex mode, the helper writes OSC directly to /dev/tty and writes exactly {} to stdout. If /dev/tty is unavailable, it still writes {} and exits successfully.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" codex working"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" codex waiting"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" codex working"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" codex completed"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" codex completed"
          }
        ]
      }
    ]
  }
}

Event mapping

• UserPromptSubmit → working.
• PermissionRequest → waiting.
• PostToolUse → working.
• Stop and SessionEnd → completed.

The hook reads no stdin, prompt, transcript, or environment secrets.

Helper contract

The bundled helper supports exactly these invocation forms:

quicktty-progress claude working|waiting|failed|completed
quicktty-progress codex working|waiting|failed|completed

States map to OSC 9;4 values as follows: working → 3, waiting → 4, failed → 2, and completed → 0.

An unknown mode, unknown state, or extra argument returns nonzero. The helper adds no new dependencies.