# 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, Grok Build, 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 cleanup orchestration`, `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, plan-mode reviewer support, parallel session capacity, 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 accept goals up to 4096 UTF-8 bytes without terminal control characters other than newline or tab and recommend solo work, workflow loops, reviewers, teams, worktrees, MCP, hooks, and harness roles before launching workers or mutating orchestration state, return planner_version plus 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 including multiple lanes on one capable harness, use mutating `task_kind` hints plus high-confidence English goal wording to infer likely user-visible edit intent, clear high-confidence English wording to infer fast/conservative/parallel/review-heavy profiles when omitted, and explicit `task_kind` for caller-normalized intent across languages, keep primary review goals and explicit read-only parallel reviews read-only even in dirty repos, 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, with an optional cooldown_kind (quota, auth, crash, or timeout) that scales the soft penalty with the cause and reason text bounded to 512 UTF-8 bytes without control characters, while harnesses without caller signals get an inferred advisory soft cooldown from recent failed task-strategy workflows. `forktty task-apply` / `task.strategy.apply` / MCP `task_strategy_apply` accept goals up to 4096 UTF-8 bytes without terminal control characters other than newline or tab, require explicit approvals, and stage visible workflow/team/task/message state by default, bootstrapping an initial planned workflow loop record for loop_metadata plans without starting a scheduler; MCP apply defaults to the current ForkTTY workspace and leader surface when explicit target selectors are omitted; apply independently recomputes dirty-repo edit isolation from the selected surface/workspace plus any explicit cwd, normalized plan task_class, and mutating strategy shape, 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` is canonicalized before submit-mode worker launch/retry checks and launches panes in that repo when no worktree is used, worktree-layer prompts name the selected worktree and effective cwd, and with `submit=true`, supported team plans validate assignment harness launchability before workflow/team mutation (launchability and worker launch failures append an advisory next-best-harness hint for the same role, without automatic retry), launch visible worker panes, and dispatch role prompts with lane scopes for parallel researcher assignments, but refuse to reuse a live deterministic worker whose harness, role, task, worktree, launch cwd, effective target cwd, or reusable status no longer matches; superseded deterministic role prompts stay in full team history but cannot be dispatched or acknowledged and are excluded from normal team inbox and pending counts; worktree creation, arbitrary commands, push, merge, destructive work, and hidden scheduling stay blocked. `forktty cleanup orchestration` / socket `orchestration.cleanup` / MCP `orchestration_cleanup` is dry-run-first stale record maintenance: it closes only records whose recorded worker surfaces no longer exist in the workspace model or terminal runtime, supersedes their pending prompts, and reports live or unrecorded worker surfaces for manual review; `--apply`/`apply=true` is required for writes. `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` with workflow `surface_present`/`stale_binding` signals, `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 including `loop_never_recorded` for finished bootstrapped loops still at iteration 0 with no gates 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, supports compact responses without full team/message bodies, can close only current-runtime launch-owned disposable worker panes, normalizes missing worker surfaces as closed, marks the team done only after all requested worker surface closes succeed, restores any already-closed runtime surfaces when a later worker close fails, and keeps normal surface.close replacement behavior for root worker panes in inactive workspaces without closing the worker when replacement spawn fails, `team_worker_health` includes `final_state`, `heartbeat_state`, report presence, and agent-session lifecycle evidence, and uses model-plus-runtime liveness to treat workers as live when their surface still exists in both the workspace model and terminal backend; readiness is reported separately, 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, can close current-runtime launch-owned worker surfaces with `close_surface`, and leaves worker store state unchanged when that close fails, team dispatch submit sends Codex/Claude/Pi/Grok 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, and non-dry-run setup/remove keep only the three newest ForkTTY-managed backups per target while leaving backup-like directories without the marker untouched. 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 including multiple lanes on one capable harness, 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, mandatory workflow_loop_set verify-loop progress recording after apply bootstraps loop_metadata plans plus workflow loop state/gates, worktree boundaries for mutating parallel workers, compact snapshot defaults, skill drift repair through doctor/setup, dry-run stale cleanup before `forktty cleanup orchestration --apply` or MCP `orchestration_cleanup` with `apply=true`, 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, and launches without either target fall back from a stale leader surface to the team workspace focus before using the selected surface cwd. 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, normalized plan task_class, and mutating strategy shape while keeping primary review goals and explicit read-only parallel reviews read-only, 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`; explicit cwd must be inside a Git repository already represented by an open ForkTTY workspace, surface, or effective project cwd and is canonicalized before worker launch/retry checks; `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, stale persisted launch records without a current terminal runtime do not block relaunch or count as live after restart, and a close failure leaves the worker store state unchanged.

## 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