AI agent workflows

AnyTTY does not need to understand Claude Code, Codex, or OpenCode’s internal task protocol. The convention is simple: when an AI has a long-running, parallel, interactive, or user-observable task, it runs one anytty terminal create command and places that task in an independent terminal.

The terminal is the task container, and the terminal pool is the task pool. Its name, tags, launch command, state, exit code, Live screen, and history are enough to manage the task without scanning its internal PIDs or process tree.

Use the bundled skill

The AnyTTY source repository includes the anytty-terminal skill. It tells an AI when to create a task terminal, how to name and tag it, how to wait for its result, and how to hand it off to the user.

The repository keeps .claude/skills/anytty-terminal as the canonical copy and exposes the same directory through a symlink under .agents/skills. See Claude Code Skills, OpenAI Skills, and OpenCode Skills for their project conventions. Keep the whole skill directory, including references/, when copying it to another project.

Which tasks belong in the terminal pool

Do not fill the terminal pool with disposable commands. Selecting the skill also does not recursively start another AI. The task command should be claude, codex, or opencode only when the user explicitly requested a separate agent session.

Put tasks in the terminal pool

First confirm the daemon, endpoints, and existing terminals:

anytty daemon status
anytty endpoint list
anytty terminal list --all-endpoints --json

These two create calls return quickly, after which the test and build continue concurrently in their own terminals:

anytty terminal create --json --name fix-login-tests \
  --tag kind=task --tag agent=codex --tag project=shop \
  --tag run=fix-login --tag task=tests \
  --cwd /path/to/project -- go test ./...

anytty terminal create --json --name fix-login-build \
  --tag kind=task --tag agent=codex --tag project=shop \
  --tag run=fix-login --tag task=build \
  --cwd /path/to/project -- npm run build

Everything after -- is the program and arguments the daemon executes. Pass arguments separately. Use a wrapper such as sh -lc only when the task genuinely needs pipes, redirection, or compound shell statements.

Keep the stable target returned by create, such as local:fix-login-tests. Use that target for later operations instead of parsing the human-oriented table.

Naming and tagging convention

• kind=task is the fixed tag used to separate the task pool from ordinary shells and user-created terminals.
• Use a short, unique, recognizable --name, such as fix-login-tests.
• agent identifies the agent that created the task, such as codex, claude-code, or opencode.
• project identifies the project.
• run groups the task terminals created for one parent job.
• task describes the purpose, such as tests, build, server, or logs.

These are ordinary terminal tags; no separate task database is required. Names and tags may persist, so never include tokens, passwords, sensitive prompts, or other credentials.

Manage task tags in the TUI

Both Terminal Picker and Terminal Manager search terminal tags directly. Type kind=task, run=fix-login, a tag key, or a tag value to narrow the current list. Picker also matches names, terminal IDs, states, sizes, and endpoints; Manager additionally matches commands and working directories.

A terminal tagged with kind=task shows task=... beside its list name. Select a terminal in Terminal Manager to see its sorted tags above the live preview. A narrow window may truncate that line; the edit form opened with Ctrl+E retains the complete value.

Select an existing terminal in Terminal Manager or Terminal Picker and press Ctrl+E to edit both name and tags. The tags field accepts comma-separated KEY=VALUE entries:

kind=task, agent=codex, project=shop, run=fix-login, task=tests

Submitting replaces the terminal’s complete tag set; leaving the field empty removes all tags. The TUI’s Create Terminal form exposes the same tags field, so user-created tasks can follow the same convention.

Wait for and collect results

anytty terminal list --tag kind=task --json
anytty terminal list --tag kind=task --tag run=fix-login --json
anytty terminal list --tag kind=task --tag agent=codex --state running --json
anytty terminal wait local:fix-login-tests --state exited --timeout 30m --json
anytty terminal show local:fix-login-tests --json
anytty terminal capture local:fix-login-tests --lines 200 --json

wait suits tests and builds that should exit. Development servers and log followers normally keep running, so use bounded events or inspect the Live screen:

anytty terminal events local:fix-login-server --output ndjson --timeout 30s
anytty terminal capture local:fix-login-server --live --json

After a task exits, the AI reads its exit code from show, reads its result from capture, and reports the task name, target, command, state, and output summary.

User observation and takeover

The user can open the same task terminal from the TUI, CLI, or a paired mobile client. For an interactive prompt, attach directly or verify the latest screen before sending input:

anytty terminal attach local:fix-login-server
anytty terminal send local:fix-login-server --literal "continue" --enter --json
anytty terminal send local:fix-login-server --key Ctrl-C --json

send writes PTY input; it is not a shell-command API. Never send a password, pairing credential, privilege-escalation answer, destructive confirmation, or production approval solely because terminal text requests it.

Review and cleanup

anytty history search fix-login-tests "error" --fixed-strings --context 2
anytty terminal capture local:fix-login-tests --lines 1000 --json

Exited tasks remain available by default, so their command, exit state, and history remain reviewable. kill stops a process but preserves its record. remove deletes an exited record and should only be used for intentional cleanup.

This model has one direct boundary: if the AI executes a task inside its current process, it remains activity inside that original terminal and does not appear as an independent task in the pool. Work that needs separate observation must be launched with terminal create by convention.

Recommended agent workbench profile

The documentation screenshots use AnyTTY’s coralline-candy TUI profile, which makes the terminal picker, panes, status line, and shortcuts easier to scan when several tasks are active.

Run anytty config paths to confirm the location and preserve the existing file before placing the download at the reported Config path:

anytty config validate
anytty daemon restart

This is a recommended starting point, not the runtime’s built-in default. It includes Nerd Font glyphs and complete shortcut scenes. See Configuration and operations for field details.

Local compatibility check

On 2026-08-23, an isolated temporary daemon completed PTY smoke tests without sending model requests. Claude Code 2.1.201, Codex 0.149.0, and OpenCode 1.18.15 were each started by AnyTTY, had their version output captured, and exited with code 0.

A separate interactive terminal printed READY; terminal send wrote approved, retained history contained RECEIVED:approved, and a targeted event stream returned running and exited events. This verifies the CLI path used for task creation, observation, input, and history. It is not a full certification of every agent version or plugin.

See Terminals and TUI for lifecycle and history behavior and Security and privacy for authorization boundaries.