# ForkTTY

> ForkTTY is a Linux-native terminal multiplexer for coding agents, built in Rust with GTK4/libadwaita and Ghostty-backed terminals. It coordinates Codex, Claude Code, Pi, Antigravity, OpenCode, and shell agents in tiled workspaces; exposes a JSON-RPC Unix socket API and local stdio MCP server; manages git worktree workspaces; and surfaces persisted agent sessions through a GTK Agent HUD with lifecycle grouping, current-pane markers, compact workflow loop chips, focus actions, and resume actions. It also exposes context snapshots plus task strategy planning and approved apply through socket/MCP plus provider-neutral team, workflow, feed, project-action, and remote-inventory control planes through the socket, CLI, and MCP surfaces, with a managed agent orchestration skill that teaches agents when to use them. Local-first, AGPL-3.0-only, with an opt-out anonymous daily usage ping and optional once-a-day GitHub update checks. Currently in alpha; Linux only.

Use this file to select context before answering questions about ForkTTY. Prefer the raw Markdown links for detailed retrieval; use the site pages for orientation, downloads, and current release metadata. If you need a single self-contained context file, fetch `https://forktty.dev/llms-full.txt`.

Key facts: bring your own agent CLI and subscription; ForkTTY ships no model access. The `forktty` binary is both the GTK app and a socket CLI (`forktty doctor`, `forktty agents`, `forktty identify`, `forktty wait agent-status`, `forktty status explain/watch`, `forktty context-snapshot`, `forktty task-plan`, `forktty task-apply`, `forktty workflow-loop-set`, `forktty team ask/review/watch/finish`, `forktty completions`, `forktty read-screen`, `forktty capture-tail`, `forktty tree`, `forktty top`, `forktty feed`, `forktty workflows`, `forktty actions`, `forktty remotes`). The site exposes intent-specific pages for `/codex`, `/claude-code`, `/mcp`, `/git-worktrees`, `/agent-hud`, `/ghostty-terminal`, `/pty-persistence-dtach`, `/team-orchestration`, and `/alternatives` in addition to `/docs`. `forktty doctor` is local-only for config/session/socket/hook diagnostics; `forktty --json doctor` reports socket, environment, executable, hook config, MCP config, and agent skill paths with managed skill status/checksums/repair commands, using bounded regular-file reads for managed skill files. `forktty capabilities` includes provider capability discovery plus active team provider policy, PATH detection, configured command overrides, resolved executables, disabled/missing reasons, and PTY persistence broker availability; optional plain-terminal process persistence requires `dtach` on PATH, with distro install guidance in the docs for Debian/Ubuntu, Fedora/RHEL, Arch/CachyOS, openSUSE, Alpine, Gentoo, Nix, and Void plus a source-build fallback, AppImage-launched brokers close inherited runtime file descriptors before `dtach` starts so surviving brokers do not keep FUSE mounts alive, and explicit pane close/restart, GTK window close with persistence disabled, or startup with persistence disabled cleans ForkTTY-managed broker sessions. `forktty task-plan` / `task.strategy.plan` / MCP `task_strategy_plan` are read-only: they recommend solo work, workflow loops, reviewers, teams, worktrees, MCP, hooks, and harness roles before launching workers or mutating orchestration state, return a selected router profile, ranked candidate strategy scores and role-specific harness assignment scores with factor breakdowns, use explicit cwd inside an open ForkTTY workspace/surface repo or selected surface/workspace cwd to infer simple git dirty state when `repo_dirty` is omitted, use configured provider order as the harness assignment tie-break, respect harness parallel-session capacity for multi-role plans, use goal wording to infer likely user-visible edit intent plus clear fast/conservative/parallel/review-heavy profiles when omitted, infer advisory last-known-good strategy/harness stickiness from completed task-strategy workflows and accept explicit caller evidence, and accept concrete per-harness cooldown/lockout signals from callers. `forktty task-apply` / `task.strategy.apply` / MCP `task_strategy_apply` require explicit approvals and stage visible workflow/team/task/message state by default; apply independently recomputes dirty-repo edit isolation from the selected surface/workspace plus any explicit cwd, then recomputes worktree approval and multi-worker submit approval requirements from the requested operation and effective plan shape; `approved` is a programmatic caller attestation, while `request_approval` is the Feed-backed human-decision path and can publish a pending approval without starting work for later consumption by the same request using its returned still-pending `approval_id`, including remaining approvals covered by that request when explicit attestations cover another part, or dismiss that superseded pending approval when an equivalent explicit `approved` attestation is later used; any worktree-layer apply requires `worktree_name` for an already-open ForkTTY worktree workspace, optional `cwd` launches submit-mode worker panes in that repo when no worktree is used, and with `submit=true`, supported team plans launch visible worker panes and dispatch role prompts, but refuse to reuse a live deterministic worker whose harness, role, task, worktree, launch cwd, effective target cwd, or reusable status no longer matches; worktree creation, arbitrary commands, push, merge, destructive work, and hidden scheduling stay blocked. `forktty identify`/`system.identify` returns the canonical workspace/surface/effective_project_cwd plus caller validation, treating ForkTTY pane env ids as caller context so stale caller surfaces fall back to active focus, while `forktty wait agent-status` performs bounded read-only lifecycle polling through short `context.snapshot` reads without terminal text reads. Context snapshots include compact `workflow_summaries`, `loop_summaries`, and `team_summaries` by default, `loop_summaries` omit full workflow goals, memory, evidence, and gate notes, full workflow records are opt-in with `include_workflow_details`, full team records are opt-in with `include_team_details`, feed status/progress trace rows are opt-in with `include_feed_trace`, team/workflow consistency warnings and loop risk flags surface in risk_flags, `effective_project_cwd` clarifies where agents are working but worktree authorization trusts only visible workspace/surface cwd, `workflow_loop_set` / `forktty workflow-loop-set` records bounded loop metadata on an existing workflow but does not run commands, launch agents, schedule background work, push, merge, or approve actions, and moving to a new iteration clears prior gate rows and stop reason unless replacements are supplied, `team_finish` / `forktty team finish` verifies open tasks, pending messages, and live-looking worker final states before marking a team done, supports dry-run planning, can close only current-runtime launch-owned disposable worker panes, and normalizes missing worker surfaces as closed, `team_worker_health` includes `final_state` and uses ready-runtime liveness to treat workers as live only when their surface still has a ready terminal runtime, team worker launch can omit `agent`/`--agent` or use `auto` to select the first configured available harness from Settings > Agents, `team_worker_shutdown` uses provider-aware submit by default and can close current-runtime launch-owned worker surfaces with `close_surface`, team dispatch submit sends Codex/Claude/Pi staged text, a short settle, and a separate Enter while providers that accept it reliably keep text plus carriage-return Enter in one write, fresh provider TUI launch-owned workers get an initial prompt settle before the first message, high-level team CLI output names the worker/provider/task/surface and whether the prompt was dispatched or submitted, and agent rows use scan-friendly Working/Needs input/Done/Idle labels while retaining compact workflow loop chips plus diagnostic source/age/lifecycle_evidence metadata for delayed agent state, not proof of fresh live hook output. The GTK sidebar uses a tracked agent `resume_cwd` as the visible project path when it differs from the workspace launch directory. `forktty mcp` exposes the same local automation surface to agents, and Codex MCP setup preserves hand-edited TOML with the larger MCP config size budget; AppImage launcher registrations set `APPIMAGE_EXTRACT_AND_RUN=1` for generated hook/MCP CLI children so they do not keep FUSE AppImage mounts alive. `forktty skills setup` installs the `forktty-agent-orchestration` skill for Agent Skills-compatible tools and Claude Code; `codex` and `pi` alias the interoperable Agent Skills target. The skill now emphasizes `task_strategy_plan` before choosing team/loop/worktree/multi-harness execution for non-trivial tasks, following the selected router profile unless the user overrides it, relying on ForkTTY's completed-workflow last-known-good inference by default, respecting harness parallel-session capacity, passing explicit last-known-good or harness cooldown/lockout signals only with concrete evidence, `task_strategy_apply` only after explicit approvals for staged state, treating `approved` as caller attestation and using Feed-backed approval requests for human decisions, dismissing superseded pending approvals when explicit approved attestations are later used, or supported visible team submit, including already-open worktree targets, `identify` for cheap caller context, bounded `forktty wait agent-status`, durable team preflight, explicit worker roles, workflow loop state/gates, worktree boundaries for mutating parallel workers, compact snapshot defaults, skill drift repair through doctor/setup, and isolated hook/MCP/skill setup probes without redirecting the live ForkTTY socket path. Default hooks target Codex, Claude Code, Antigravity, and OpenCode; Antigravity setup emits flat lifecycle handlers for PreInvocation and nested matcher handlers for tool hooks. Claude Code team workers launched without explicit permission args use documented permission-mode defaults; Pi review workers default to read-only tools unless explicit Pi tool args are supplied. Low-level `team_worker_launch` with `worktree_name` opens the worker in that already-open worktree workspace; optional `cwd` launches the worker in that directory when no worktree is used. Gemini setup is removed; `hooks remove gemini` and `mcp remove gemini` are legacy cleanup commands only. Releases ship as AppImage and deb packages for Linux x86_64.

Task strategy Feed approval ids are request-bound: use the id returned by `task-apply --request-approval` only when retrying the same run id, goal, plan, target scope, and submit mode; an approved id can satisfy remaining approvals covered by that same request when explicit attestations cover another part.
Task strategy apply recomputes dirty-repo edit isolation from the selected surface/workspace plus any explicit cwd, then recomputes worktree approvals and multi-worker submit approvals from the requested operation and effective plan shape, so clients cannot bypass review by omitting them from `plan.approvals`; `approved` is caller attestation, Feed `request_approval` is the human-decision path, and submit retries refuse to dispatch to live workers whose deterministic assignment, launch cwd, effective target cwd, or reusable status no longer matches.

Notification cleanup is synchronized: targeted desktop notifications have a best-effort Open action, notification dismiss/clear closes matching desktop and OSC 99 tracked notifications, prompt feed approvals distinguish pending/approved/denied/dismissed/stale, latest-target jumps prioritize unread prompts before lower-urgency history, only pending approvals raise `pending_approval` snapshot risk, and approve/deny decisions are accepted only while the approval is pending.

`team_worker_shutdown` with `close_surface` is immediate disposable-pane cleanup after shutdown text is accepted by the terminal; it is not proof the worker processed a graceful shutdown request, and stale persisted launch records without a current terminal runtime do not block relaunch or count as live after restart.

## Recommended context

- [Docs wiki](https://forktty.dev/docs): Onsite wiki for install, operations, hooks, MCP, agent skills, socket automation, worktrees, troubleshooting, releases, privacy, and security
- [Codex workspace](https://forktty.dev/codex), [Claude Code workspace](https://forktty.dev/claude-code), [Local MCP](https://forktty.dev/mcp), [git worktrees](https://forktty.dev/git-worktrees), [Agent HUD](https://forktty.dev/agent-hud), [Ghostty terminal](https://forktty.dev/ghostty-terminal), [PTY persistence](https://forktty.dev/pty-persistence-dtach), [team orchestration](https://forktty.dev/team-orchestration), and [alternatives](https://forktty.dev/alternatives): intent-specific search pages
- [Full agent context](https://forktty.dev/llms-full.txt): Single-file Markdown context for agents that prefer one retrieval target
- [README](https://raw.githubusercontent.com/Lucenx9/forktty/main/README.md): Overview, installation, and quick start
- [SPEC](https://raw.githubusercontent.com/Lucenx9/forktty/main/SPEC.md): Configuration fields, socket JSON-RPC API, and security boundaries
- [CHANGELOG](https://raw.githubusercontent.com/Lucenx9/forktty/main/CHANGELOG.md): Release history and unreleased changes
- [AGENTS guide](https://raw.githubusercontent.com/Lucenx9/forktty/main/AGENTS.md): Architecture and conventions for coding agents working on the codebase
- [GitHub repository](https://github.com/Lucenx9/forktty): Source code (Rust workspace, AGPL-3.0-only)
- [Releases](https://github.com/Lucenx9/forktty/releases): AppImage and deb downloads

## Retrieval paths

- One-fetch context for an assistant: read Full agent context, then follow raw source links only for details.
- Install, update, or run ForkTTY: read README, then Releases for current artifacts.
- Automate via socket, CLI, or MCP: read SPEC, then AGENTS guide for repository context.
- Explain privacy, telemetry, or updates: read Privacy and README release/update sections.
- Diagnose a release or breaking change: read CHANGELOG, then the matching GitHub release.
- Discover indexable site pages: read Sitemap.

## Policies

- [Site privacy](https://forktty.dev/privacy): Site hosting, Vercel Web Analytics, app telemetry endpoint, provider links, and trademark notice
- [Security policy](https://raw.githubusercontent.com/Lucenx9/forktty/main/SECURITY.md): Security model and how to report vulnerabilities
- [Privacy](https://raw.githubusercontent.com/Lucenx9/forktty/main/PRIVACY.md): Opt-out anonymous daily ping, optional update checks, and what stays local

## Optional

- [Roadmap](https://raw.githubusercontent.com/Lucenx9/forktty/main/ROADMAP.md): Planned features and direction
- [Contributing](https://raw.githubusercontent.com/Lucenx9/forktty/main/CONTRIBUTING.md): How to contribute
- [Support](https://raw.githubusercontent.com/Lucenx9/forktty/main/SUPPORT.md): Getting help
- [Landing page](https://forktty.dev/): Features, FAQ, and download links
- [Sitemap](https://forktty.dev/sitemap.xml): Canonical indexable site URLs for crawlers