tyghos-terminal-driver

name	tyghos-terminal-driver
description	Drive real desktop terminal sessions through the local tyghos WebDriver-style HTTP daemon. Use when Codex needs to launch Terminal.app, iTerm2, or Ghostty on macOS, enter text or Ghostty key events, capture rendered terminal text or screenshots, verify terminal UI behavior, or inspect which desktop terminal operations are available.

Tyghos Terminal Driver

Use tyghos when validation must happen in a real desktop terminal window instead of a synthetic PTY or ordinary shell command. Treat each launched session as user-visible UI state and close it after the task.

Workflow

1. Locate the tyghos repository or binary. When working in its repository, run commands from that root.
2. Check whether a daemon is already listening with curl -sS http://127.0.0.1:4445/healthz. If not, start one with cargo run -- serve --listen 127.0.0.1:4445 and keep that process running while using the API.
3. Fetch GET /v1/targets before choosing a target. Use only a target with driver_status: "implemented", available: true, and support for each operation the task requires.
4. Create a session, retain the returned session.id, and interact only through that id.
5. Capture text or a screenshot to verify the observable result. Do not treat a successful request as evidence that the rendered terminal behaved correctly.
6. Delete every created session when finished, including after a failed validation where the session id is known. Stop a daemon process that you started unless it is intentionally needed for subsequent work.

HTTP Operations

Set the service base URL when issuing multiple requests:

BASE=http://127.0.0.1:4445
curl -sS "$BASE/v1/targets"

Create a Ghostty session that runs an initial command:

curl -sS "$BASE/v1/sessions" \
  -H 'content-type: application/json' \
  -d '{"target":"ghostty@macos","cwd":"/tmp","command":"printf \"ready\\n\""}'

For an existing <session-id>, use:

curl -sS "$BASE/v1/sessions/<session-id>"
curl -sS "$BASE/v1/sessions/<session-id>/text" \
  -H 'content-type: application/json' -d '{"text":"echo hello\n"}'
curl -sS "$BASE/v1/sessions/<session-id>/key" \
  -H 'content-type: application/json' -d '{"key":"enter","modifiers":[]}'
curl -sS "$BASE/v1/sessions/<session-id>/capture" \
  -H 'content-type: application/json' -d '{"scope":"visible"}'
curl -sS "$BASE/v1/sessions/<session-id>/capture" \
  -H 'content-type: application/json' -d '{"scope":"scrollback"}'
curl -sS "$BASE/v1/sessions/<session-id>/screenshot" \
  -H 'content-type: application/json' -d '{"scope":"window"}'
curl -sS -X DELETE "$BASE/v1/sessions/<session-id>"

Creation also accepts env as an array such as [{"key":"TERM_MODE","value":"demo"}]. Use valid shell environment keys only.

Target Selection

• Prefer ghostty@macos for end-to-end interaction requiring raw text, key input, visible or scrollback capture, or screenshots.
• Use iterm2@macos for raw text, visible capture, screenshots, and closing sessions. Do not request key input or scrollback capture unless the live target catalog reports support.
• Use terminal.app@macos when immediate command execution is acceptable. Its text operation runs input rather than inserting unsubmitted raw text, and key input is not implemented.
• Do not create sessions for catalog entries marked planned or unsupported.

Observation And Side Effects

• Treat /capture text as the primary assertion surface for terminal output. Use scope: "scrollback" only when the selected target reports that it supports it.
• Use /screenshot when checking rendering, chrome, color, or layout. The response contains base64 PNG bytes; decode to a temporary .png file and inspect that image when visual verification is required.
• Expect macOS automation and screen-capture permission prompts when the host has not granted them. Surface a permission failure rather than substituting a PTY test for a requested desktop-terminal check.
• Remember that screenshot capture activates the terminal window. Ghostty text capture temporarily interacts with the clipboard; the driver is designed to restore clipboard contents, but avoid unnecessary captures while the user is actively using it.

Failure Handling

• If GET /v1/targets lists an app as unavailable, report that the app is not installed or discoverable and select another implemented target only when that still tests the requested behavior.
• Treat HTTP 501 responses as unsupported operations and re-check the target matrix instead of retrying blindly.
• Treat HTTP 502 responses as adapter or macOS automation failures; include the returned error message when reporting the blocked validation.