# ForkTTY full agent context

> ForkTTY is a Linux-native terminal multiplexer for coding agents, built in Rust with GTK4/libadwaita and embedded Ghostty terminal panes. It coordinates Codex, Claude Code, Pi, Antigravity, OpenCode, and shell agents in tiled workspaces with git worktrees, an owner-only local Unix socket API, a stdio MCP bridge, and resume-aware Agent HUD metadata. ForkTTY is local-first, AGPL-3.0-only, Linux-only, and currently alpha.

Use this file when an assistant or crawler wants one high-signal Markdown document instead of parsing HTML. For implementation details, treat the linked raw repository files as the source of truth.

## Current status

- Current public release line: `0.2.0-alpha.x`.
- Latest recorded release in the public changelog: `0.2.0-alpha.16`, dated 2026-06-27.
- Supported platform for release artifacts: Linux x86_64.
- Primary packaged runtime: GTK4/libadwaita with embedded Ghostty terminal panes.
- Release artifacts: AppImage, AppImage zsync metadata, Debian package, and SHA256SUMS.
- Bring your own agent CLI, account, and subscription. ForkTTY does not provide model access.
- Source-only browser panes exist behind the optional `browser` feature and are not included in release artifacts.

## Install and first run

Use the AppImage for the portable alpha path, or the Debian package on modern Debian and Ubuntu baselines.

```sh
sha256sum -c SHA256SUMS --ignore-missing
chmod +x forktty-*.AppImage
./forktty-*.AppImage
forktty --version
forktty doctor
```

- `forktty doctor` is local-only and reports config, session, socket, and hook config diagnostics. Use `forktty --json doctor` for socket, environment, executable, hook config, MCP config, and agent skill paths resolved from the current environment, including managed skill status/checksums/repair commands; managed skill files are inspected through bounded regular-file reads, and symlinked skill directory entries are reported invalid without a repair command unless a regular `SKILL.md` marker was already verified.
- AppImage is the recommended portable Linux x86_64 artifact for alpha releases.
- AppImages prefer the host GTK/libadwaita stack when available and keep the bundled GTK copy as a fallback. Use `FORKTTY_APPIMAGE_GTK_RUNTIME=bundled`, `host`, or `auto` to force or debug the runtime choice.
- Debian package baseline is Debian 13/Trixie+ and Ubuntu 24.04 LTS+.
- Debian 12/Bookworm is below the documented package baseline.
- Source builds require Rust 1.96+, GTK4/libadwaita development files, git, Zig, and the Ghostty submodule.
- If a GTK renderer issue appears on a distro or driver stack, ForkTTY defaults `GSK_RENDERER` to `ngl` and still honors an explicit `GSK_RENDERER` override for QA.

## Daily use

- Open the command palette with `Ctrl+Shift+P`.
- Use split panes and tabs to keep multiple agents visible without mixing scrollback; drag pane headers to swap panes.
- Session restore writes native state to `~/.local/state/forktty/session-v2.json`; live PTYs are not persisted by default, but Settings > Worktrees can enable `general.persist_terminal_processes` for plain terminals when `dtach` is available. Those processes survive a UI restart and re-attach on relaunch; AppImage-launched brokers close inherited runtime file descriptors before `dtach` starts so surviving brokers do not keep FUSE mounts alive. Explicit pane close or restart terminates the matching managed broker process tree and removes the broker socket so reused surface ids start fresh. Disabling persistence preserves currently visible panes until they close; closing the GTK window with persistence disabled cleans visible managed brokers too, and startup with persistence disabled cleans old managed sessions before restore.
- `dtach` install quick reference for PTY persistence: Debian/Ubuntu/Mint/Pop!_OS use `sudo apt update && sudo apt install dtach` (enable Ubuntu `universe` first if apt cannot find it); Fedora uses `sudo dnf install dtach`; RHEL/CentOS Stream/Rocky/Alma need matching EPEL first, then `sudo dnf install dtach`; Arch/CachyOS/EndeavourOS/Manjaro use AUR or upstream source because dtach is not in official Arch repos; openSUSE Tumbleweed uses `sudo zypper install dtach`; openSUSE Leap may need the openSUSE package page/backports; Alpine uses `sudo apk add dtach`; Gentoo uses `sudo emerge app-misc/dtach`; NixOS/Nix should add `pkgs.dtach` to the system or shell environment; Void can use `sudo xbps-install -S dtach` when available, otherwise build upstream source. Universal fallback: clone `https://github.com/crigler/dtach`, run `./configure`, `make`, `sudo make install`, then restart ForkTTY and check `forktty capabilities | grep -i pty`.
- Prompt-aware notifications can come from socket calls, hooks, Ghostty OSC events, bell/child-exit events, or bounded prompt fallback detection.
- Quake/dropdown behavior uses gtk4-layer-shell where the compositor supports it and falls back to normal GTK behavior elsewhere.
- ForkTTY leaves Ghostty-owned terminal appearance and runtime behavior to Ghostty configuration, except ForkTTY-managed embedded panes force `wait-after-command` so clean shell exits remain inspectable as Closed panes.
- Live embedded panes follow Ghostty's `scrollback-limit` budget, default to 10 MB per surface, and honor `scrollbar = system|never`.

## Agent integrations

ForkTTY targets Codex, Claude Code, Pi, Antigravity, OpenCode, and shell agents. Managed hooks for Codex, Claude Code, Antigravity, and OpenCode persist session ids, cwd, lifecycle state, last activity, permission prompts, token details where available, and status entries consumed by the Agent HUD; agent rows group lifecycle states with scan-friendly labels such as Working, Needs input, Done, and Idle, mark the current pane, surface risky permission modes, show compact workflow loop chips for bound surfaces, and add diagnostic `lifecycle_evidence` and `effective_project_cwd` so clients can correlate persisted lifecycle/freshness and the actual project cwd with the current workspace/provider status row without treating it as proof of fresh live hook output, terminal child exit marks attached sessions ended so stopped agents do not remain running, and provider-scoped HUD metadata is cleared when the last matching session ends, closes, hibernates, or is forgotten. The GTK sidebar uses a tracked agent `resume_cwd` as the visible project path when it differs from the workspace launch directory. Team worker launch can omit `agent`/`--agent` or use `auto`; Settings > Agents controls the default provider, fallback, provider order, disabled providers, PATH detection, and direct command overrides for non-default harness install locations, while `forktty capabilities`/`system.capabilities` reports the active policy, resolved harnesses, and PTY persistence broker availability. 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. Managed skills add the policy layer that tells agents when to inspect ForkTTY context, teams, workflows, and terminal state.

```sh
forktty agents
forktty agent-health
forktty resume-agent
forktty set-status
forktty set-progress
forktty log
forktty notify
forktty notifications
```

- Provider keys and remote agent traffic stay outside ForkTTY.
- ForkTTY coordinates local panes, metadata, hooks, skills, socket calls, and notifications.
- Prompt notification feed entries distinguish pending, approved, denied, dismissed, and stale states. Dismiss/clear syncs in-app state with matching desktop notifications and OSC 99 close reports; the latest-target action prioritizes unread prompts before lower-urgency history; only pending approvals raise the `pending_approval` snapshot risk flag, and approve/deny decisions are accepted only while the approval is pending.
- The Agent HUD can group, focus, resume, inspect persisted agent sessions, and show compact workflow loop chips for bound live surfaces.

## Hooks

Hooks install provider-specific config entries that report lifecycle and status to ForkTTY.

```sh
forktty hooks setup
forktty hooks setup --dry-run
forktty hooks setup codex
forktty hooks doctor codex
forktty hooks test codex
forktty hooks remove codex
forktty hooks remove gemini   # legacy cleanup only
```

Managed destinations:

- Codex: `$CODEX_HOME/hooks.json` or `~/.codex/hooks.json`.
- Claude Code: `$CLAUDE_CONFIG_DIR/settings.json` or `~/.claude/settings.json`.
- Antigravity: `~/.gemini/config/hooks.json` plus generated wrappers.
- OpenCode: `$OPENCODE_CONFIG_DIR/plugins/forktty.generated.js` or `~/.config/opencode/plugins/forktty.generated.js`.

Setup is explicit on first install. Once ForkTTY-managed entries exist, newer builds can refresh managed hook, MCP, and skill entries while preserving unrelated user configuration. When setup records an AppImage launcher for hook CLI calls, generated commands set `APPIMAGE_EXTRACT_AND_RUN=1` so short hooks do not keep FUSE AppImage mounts alive. Antigravity lifecycle hooks such as PreInvocation use flat handler entries; tool hooks use the nested matcher/hooks shape. Gemini setup is removed; remove commands only keep a legacy cleanup path for old ForkTTY-managed `~/.gemini/settings.json` entries.

## MCP setup

The MCP bridge exposes ForkTTY socket capabilities to local agent clients over stdio.

```sh
forktty mcp
forktty mcp setup
forktty mcp setup codex
forktty mcp setup claude
forktty mcp setup antigravity
forktty mcp remove gemini   # legacy cleanup only
```

- The MCP server is local-only.
- It bridges stdio to the owner-only ForkTTY Unix socket.
- It does not open a network listener.
- It exposes workspace, surface, context snapshot, task strategy planning and approved apply, agent, worktree, notification, feed, workflow, team, topology, browser, and status tools where supported by the running app.
- Codex MCP setup preserves hand-edited TOML comments/formatting and uses the larger MCP config size budget for `$CODEX_HOME/config.toml` or `~/.codex/config.toml`.
- If setup registers an AppImage launcher, the managed MCP server env includes `APPIMAGE_EXTRACT_AND_RUN=1` so persistent MCP clients do not keep a FUSE AppImage mount alive.

Config locations:

- Codex: `$CODEX_HOME/config.toml` or `~/.codex/config.toml` under `[mcp_servers.forktty]`.
- Claude: `~/.claude.json` under `mcpServers.forktty`.
- Antigravity: `~/.gemini/config/mcp_config.json`.

## Agent skills

The managed ForkTTY skill teaches agents when and how to use the MCP surface instead of waiting for the user to name each tool.

```sh
forktty skills setup
forktty skills setup agents --dry-run
forktty skills setup pi
forktty skills setup claude
forktty skills remove agents
```

- The skill is named `forktty-agent-orchestration`.
- Agent Skills-compatible tools use `~/.agents/skills/forktty-agent-orchestration`.
- `codex` is an alias for the interoperable `agents` target.
- `pi` is an alias for the interoperable `agents` target.
- Claude Code uses `$CLAUDE_CONFIG_DIR/skills/forktty-agent-orchestration` or `~/.claude/skills/forktty-agent-orchestration`.
- The skill tells agents to call `task_strategy_plan` before choosing team, workflow loop, worktree, or multi-harness execution for non-trivial tasks; task planning returns a selected router profile, ranked candidate strategy scores plus role-specific harness assignment scores with factor breakdowns, uses capabilities, provider policy as the harness assignment tie-break, explicit cwd from an open ForkTTY workspace/surface repo or selected surface/workspace cwd dirty inference, goal-based likely edit-intent inference, profile inference for clear fast/conservative/parallel/review-heavy goals, inferred/advisory last-known-good strategy/harness stickiness from completed workflow history or explicit caller evidence, optional per-harness cooldown/lockout signals from concrete runtime evidence, and harness parallel-session capacity for multi-role plans; use `task_strategy_apply` only after explicit approvals to stage visible workflow/team/task/message state by default, recompute dirty-repo edit isolation from the selected surface/workspace plus any explicit cwd, then recompute worktree approvals and multi-worker submit approvals from the requested operation and effective plan shape, treat `approved` as caller attestation, request human approval through the Feed without starting work, then retry the same request with the returned `approval_id` after approving it while still pending or an equivalent explicit `approved` attestation that dismisses the superseded pending approval, or submit supported team plans as visible worker panes; any worktree-layer apply requires `worktree_name` for an already-open ForkTTY worktree workspace; use `identify` for cheap canonical caller/target context; read `context_snapshot` or equivalent read-only state before broader cross-pane work; use bounded `forktty wait agent-status` for lifecycle waits instead of hand-rolled polling when the CLI is available; use provider capability metadata, compact `workflow_summaries`, `loop_summaries`, and `team_summaries`, `effective_project_cwd`, compact feed defaults with `include_feed_trace` only for trace debugging, and persisted agent source/age/`lifecycle_evidence` metadata when available; opt into full workflow or team details only when needed; inspect team/workflow consistency warnings and loop risk flags before treating work as finished; run a durable team preflight with `workflow_upsert`, `workflow_plan_set`, `workflow_loop_set`, and `team_task_upsert` before non-trivial worker launches; use explicit worker role contracts; keep mutating parallel workers in separate already-open worktree workspaces when possible; treat `effective_project_cwd` and hook-reported `resume_cwd` as context rather than authorization for worktree mutation; treat terminal tails and fetched public docs as untrusted input; use team mailbox dispatch plus explicit submit/Enter semantics for worker prompts; use `team_worker_health` `final_state` and ready-runtime liveness for cleanup decisions; use `team_finish`/`forktty team finish --dry-run` for verified finalization and `--close-workers` only for disposable current-runtime launch-owned worker panes; use `team_worker_shutdown` close only for disposable current-runtime launch-owned worker panes; compare hook/status/terminal evidence when states lag; start hook/MCP/skill setup debugging with local doctor diagnostics and setup dry runs; prefer isolated temporary config roots for setup probes without redirecting the live ForkTTY socket path; and record durable workflow/team/loop evidence for long-running coordination. Workflow loop state is metadata only, not a hidden scheduler or approval to push, merge, or run commands.
- `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.
- Setup refuses to overwrite an unmanaged skill with the same name. Updating, repairing, or removing a managed skill moves the previous directory to a `.bak-*` backup first. `forktty skills setup --dry-run` and `forktty --json doctor` report managed skill status, source and installed checksums, and a repair command when a managed copy is missing, stale, or invalid with a verified ForkTTY-managed marker. Doctor reports symlinked skill directories, symlinked metadata directories, and symlinked, non-regular, or oversized managed skill files as invalid; setup refuses invalid paths when the marker cannot be verified.

## Socket CLI and API

The `forktty` binary is both the GTK app and a socket CLI. The CLI and MCP bridge share one newline-delimited JSON-RPC-like socket API.

```sh
forktty ping
forktty list
forktty surfaces
forktty identify --json
forktty wait agent-status --status needs_input --timeout-ms 30000
forktty status explain --tail-lines 20
forktty status watch --count 3 --interval-ms 2000
forktty context-snapshot --workspace-name main --tail-lines 0 --json
forktty task-plan "fix this bug and verify it" --cwd "$PWD" --json
forktty task-apply --run-id router-run-1 --plan-json '<plan-json>' --approved start_run "fix this bug and verify it"
forktty task-apply --run-id router-run-1 --plan-json '<team-plan-json>' --approved start_run,launch_parallel_workers --submit "review this implementation"
forktty workflow-loop-set loop-runtime --stage verify --iteration 2 --max-iterations 4
forktty team ask review-team review-worker --task-id review-head --prompt "Review HEAD read-only" --submit
forktty team review review-team review-worker --task-id review-head --commit HEAD --submit
forktty team watch review-team --stale-after-ms 120000 --limit 10
forktty team finish review-team --dry-run
forktty team finish review-team --close-workers
forktty read-screen
forktty capture-tail
forktty split-surface --axis vertical
forktty send-text "echo hello"
forktty capabilities
forktty events
forktty examples
forktty completions bash
```

- Default socket: `$XDG_RUNTIME_DIR/forktty.sock`.
- Fallback socket: `/tmp/forktty-<uid>/forktty.sock`.
- Override: `FORKTTY_SOCKET_PATH=/absolute/path`.
- High-level team wrappers compose existing socket methods for common coordination flows.
- `forktty task-plan`, socket `task.strategy.plan`, and MCP `task_strategy_plan` are read-only task routing surfaces. They recommend solo work, workflow loops, reviewer roles, teams, worktree isolation, MCP, hooks, and harness roles before agents launch workers or mutate orchestration state. Responses include a selected router profile, ranked candidate strategy scores plus role-specific harness assignment scores with factor breakdowns; configured team provider order is the harness assignment tie-break, harness parallel-session capacity is respected for multi-role plans, explicit `cwd`/`--cwd` inside an open ForkTTY workspace/surface repo or selected surface/workspace cwd is used to infer simple git dirty state when `repo_dirty` is omitted, goal wording is used to infer likely user-visible edit intent and clear fast/conservative/parallel/review-heavy profiles when omitted, completed task-strategy workflow history can infer advisory `last_known_good` strategy/harness stickiness when callers omit explicit evidence, optional `harness_signals` lets callers pass concrete cooldown/lockout evidence, and reviewer strategies include an explicit reviewer assignment.
- `forktty task-apply`, socket `task.strategy.apply`, and MCP `task_strategy_apply` require explicit approvals and stage visible workflow/team/task/message state by default. It recomputes dirty-repo edit isolation from the selected surface/workspace plus any explicit `cwd`, then recomputes `create_worktree` and multi-worker `launch_parallel_workers` approval requirements from the requested operation and effective plan shape before trusting the plan's approval list. The `approved` array is a programmatic caller attestation, not proof of a human decision; `request_approval` can publish a pending Feed approval without starting work, and a later retry can consume that approval only for the same request while the returned `approval_id` is still pending, including remaining approvals that the same request covered when explicit attestations cover another part. Any worktree-layer apply requires `worktree_name` for an already-open ForkTTY worktree workspace. Optional `cwd` launches submit-mode worker panes in that repo and names it in role prompts when no `worktree_name` is used. With `submit=true`, supported team plans launch visible worker panes, assign tasks, queue deterministic role prompts, and dispatch them through the team mailbox, 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 team ask` and `forktty team review` create the task before launching a fresh worker surface, assign it after launch, and bind the worker to the invoking ForkTTY pane/workspace when available so the worker opens nearby and inherits that cwd; low-level `team_worker_launch` with `worktree_name` opens the worker in that already-open worktree workspace and inherits that cwd, optional `cwd` launches the worker in that directory when no worktree is used, while launches without either target inherit the selected surface's recorded terminal cwd rather than hook-reported `resume_cwd`. Submit mode uses provider-aware terminal input: Codex/Claude/Pi get staged text, a short settle, and a separate Enter, while providers that accept it reliably keep text plus carriage-return Enter in one write. Human CLI output reports the worker, selected provider when known, task, target surface, and whether the prompt was dispatched or submitted. `team-message-send` plus `team-message-dispatch` handle follow-up prompts to an existing worker. Dispatch selects the worker workspace/tab, waits briefly for the embedded terminal surface to become socket-ready before typing, and gives fresh provider TUI launch-owned workers an initial prompt settle before the first message. `team_worker_health` includes `final_state` for cleanup decisions and uses ready-runtime liveness to treat workers as live only when their surface still has a ready terminal runtime.
- MCP `team_upsert` uses the same pane defaults: `FORKTTY_SURFACE_ID` becomes the leader surface when present, otherwise `FORKTTY_WORKSPACE_ID` is used.
- `forktty identify`/`system.identify` is the compact read for canonical workspace/surface/effective_project_cwd plus caller id validation; ForkTTY pane environment ids are caller context, so stale caller surface ids fall back to the active workspace focus instead of failing the read. `effective_project_cwd` clarifies where an agent is working, but worktree authorization trusts only visible workspace/surface cwd. `forktty wait agent-status` performs bounded read-only lifecycle polling through short `context.snapshot` reads without terminal text reads. `workflow_loop_set` / `forktty workflow-loop-set` records closed-loop state on an existing workflow: recipe, stage, iteration budget, stop reason, and compact gate statuses. It does not run commands, launch agents, schedule background work, push, merge, or approve actions; moving to a new iteration clears prior gate rows and stop reason unless replacements are supplied, and compact `loop_summaries` omit full workflow goals, memory, evidence, and gate notes.
- `forktty status explain/watch` and `forktty context-snapshot` expose compact context snapshot reads for delayed state, stale-looking agents, diagnostic source/age/`lifecycle_evidence` metadata, compact workflow/loop/team summaries, risk flags, and per-surface plus aggregate-bounded untrusted terminal tails.
- `forktty completions bash|zsh|fish` prints shell completions for the curated ergonomic command set and grouped team/status subcommands.
- System methods cover ping, identify, capabilities, provider capability discovery, and event subscriptions.
- Workspace and surface methods cover list, focus, split, close, text input, visible text, and tail capture.
- Task methods cover read-only strategy planning plus approved apply that can stage coordination state or submit supported team plans as visible worker panes.
- Agent methods cover agent listing, health, diagnostic source/age/`lifecycle_evidence` metadata, resume, and reclaim planning; the CLI `wait agent-status` wrapper polls those read-only surfaces for lifecycle waits.
- Notification/feed methods keep desktop, in-app, OSC 99, and persisted approval state aligned: targeted desktop notifications expose a best-effort Open action, clear/dismiss marks pending prompt approvals dismissed, task-strategy apply dismisses superseded pending approvals when equivalent explicit `approved` attestations are used, stale target approvals are reported as stale, only pending approvals set the snapshot `pending_approval` risk flag, and approve/deny decisions are accepted only while the approval is pending.
- Metadata methods publish status, progress, logs, and statusline output.
- Worktree methods validate target paths against repos already opened by the user.
- Error codes include `method_not_found`, `missing_param`, `not_found`, `payload_too_large`, `conflict`, `precondition_failed`, `already_exists`, `not_ready`, `invalid_param`, and `error`.

## Git worktrees

Worktrees are first-class ForkTTY workspaces for isolated parallel tasks.

```sh
forktty worktree-status
forktty worktree-list
forktty worktree-create feature/my-task --cwd /path/to/repo
forktty worktree-attach feature/my-task --cwd /path/to/repo
```

- ForkTTY uses native git operations to create, attach, remove, and merge worktrees.
- Socket worktree calls require an explicit cwd.
- Socket worktree calls are constrained to repositories the user has opened.
- Dirty-state protection blocks destructive worktree actions that would drop uncommitted work.
- Optional `.forktty/setup` and teardown hooks let projects prepare or clean a worktree.
- Repo-local `forktty.json` can describe project actions and workflow hints for automation.

## Configuration and local files

Common local files:

- `~/.config/forktty/config.toml`: user configuration for ForkTTY-owned behavior.
- `~/.local/state/forktty/session-v2.json`: workspace, pane, and recent scrollback session state.
- `~/.local/share/forktty/browser_profiles/profiles.json`: source-only browser profile index.
- `~/.local/share/forktty/browser_profiles/<id>/`: source-only WebKit profile data.
- `~/.local/state/forktty/telemetry-ping.json`: last UTC date when the app attempted the anonymous ping.

Example config:

```toml
[general]
worktree_layout = "nested"
enable_pr_lookup = false
notification_command = ""
persist_terminal_processes = false

[appearance]
persistent_scrollback_lines = 0
sidebar_position = "left"
sidebar_visible = true
window_mode = "normal"

[notifications]
desktop = true
sound = true

[telemetry]
anonymous_ping = true
```

Legacy TOML keys for terminal font, theme, bell, renderer, and scrollback still load for compatibility but are not exposed in newly saved settings.

## Privacy and telemetry

ForkTTY is local-first and limits network activity to update checks and an anonymous daily ping that can be disabled.

- The app does not send crash reports.
- The app does not send terminal contents, project paths, repository paths, branches, shell names, socket payloads, agent metadata, usernames, hostnames, or install identifiers.
- Anonymous app telemetry is at most one daily HTTPS POST to `https://forktty.dev/api/telemetry/ping` when enabled.
- The ping payload contains only `schema`, `kind`, `app`, `version`, and `date`.
- GitHub update checks are once-a-day release metadata checks when enabled.
- Desktop notifications are local OS notifications, except for what the desktop environment needs to display them.
- Disable app telemetry from the first-launch privacy prompt or config.
- CLI invocations, agent hooks, socket clients, and the local MCP bridge do not send telemetry pings.

## Security model

ForkTTY assumes a local same-user trust boundary and defends the socket, config, session, and package runtime accordingly.

- The Unix socket is owner-only and local to the user's desktop session.
- Request lines, config, and session files are bounded.
- Notification commands are executed as argv, not through shell pipelines.
- Config and session recovery quarantine malformed, oversized, or invalid state.
- Embedded Ghostty library loading canonicalizes candidate paths and rejects relative, non-regular, untrusted, or writable-by-others paths.
- Worktree operations from socket automation are limited to repos opened by the user.
- Supported security updates track the current `0.2.0-alpha.x` line.
- Older `0.1.x` releases are not covered by the current supported-version policy.
- Security reports should use GitHub private vulnerability reporting.

## Troubleshooting

Start with diagnostics and package baseline checks.

```sh
forktty doctor
forktty ping
FORKTTY_APPIMAGE_GTK_RUNTIME=host ./forktty-*.AppImage
GSK_RENDERER=gl ./forktty-*.AppImage
FORKTTY_SOCKET_PATH=/absolute/path forktty ping
```

- `forktty doctor` is local-only and includes config, session, socket, and hook config diagnostics. Use `forktty --json doctor` when MCP config and agent skill path diagnostics matter.
- If packaged terminal panes fail to start, confirm the release artifact includes `ghostty-gtk-embed.so`, then try `FORKTTY_APPIMAGE_GTK_RUNTIME=host` or `bundled` to isolate host-vs-bundled GTK renderer issues.
- If `.deb` install fails on Debian 12/Bookworm, use Debian 13/Trixie+ or Ubuntu 24.04 LTS+.
- If socket commands cannot connect, launch ForkTTY first or set an absolute `FORKTTY_SOCKET_PATH`.
- If config or session files are corrupt, ForkTTY should quarantine the bad file and start from defaults.
- For bug reports, include `forktty doctor` output, distro and desktop environment, install method, reproduction steps, and relevant logs.

## Changelog highlights

Latest recorded release: `0.2.0-alpha.16` from 2026-06-27.

- Fixed AppImage hook/MCP setup so generated ForkTTY CLI commands set `APPIMAGE_EXTRACT_AND_RUN=1` and avoid leaving FUSE runtime mounts behind.
- Fixed GTK window close so the embedded Unix-socket server shuts down instead of keeping the GUI/AppImage process alive.
- Fixed AppImage terminal launches with opt-in PTY process persistence so detached `dtach` brokers do not inherit AppImage runtime file descriptors or keep FUSE mounts alive.
- Fixed opt-in PTY process persistence cleanup so disabling the setting, closing the GTK window with it disabled, starting with it disabled, or explicitly closing/restarting a pane does not leave ForkTTY-managed `dtach` process trees behind.
- Fixed official CLI/MCP socket timeout and response-budget mismatches for valid bounded responses and slower server-side operations.
- Fixed team/workspace race conditions around duplicate dispatches, duplicate worker launches, close rollback, and concurrent surface creation during close.
- Restricted opt-in PTY process persistence to plain interactive terminal shell spawns.
- AppImages prefer host GTK/libadwaita when available and keep bundled GTK as a fallback/override.
- Embedded Ghostty redraws now follow the 16ms wakeup-check cadence instead of a 100ms floor during continuous output.
- AppImage packaging verifies the embedded Ghostty GTK library dependencies, not only the main binary.
- Embedded panes now honor Ghostty `scrollback-limit`, with a bounded default of 10 MB per surface.
- Embedded panes now pack the raw Ghostty surface inside a GTK scrolled window and honor Ghostty `scrollbar = system|never`.
- Clean shell exits in embedded panes now remain inspectable as Closed panes instead of immediately removing the split.
- Agent health, explicit resume, and restore-time auto-resume now preserve hook-reported bypass-permissions sessions for Codex and Claude Code.
- Security fixes hardened restored session identifiers, command-spawn values, library loading, OSC99 icon sizing, and Kitty image snapshots.
- Docs, package metadata, the first-run privacy link, and the telemetry endpoint now use `https://forktty.dev`.

## Roadmap, limitations, and support

- Known limitations: Linux-only, libadwaita 1.4+ baseline, AppImage host dependencies, PTYs not persisted by default (opt-in `general.persist_terminal_processes` adds dtach-backed process survival for plain terminals), partial OSC notification coverage, compositor-dependent quake behavior, and source-only browser panes.
- Near-term roadmap areas include richer Agent HUD/statusline exports, remote daemon depth, sidebar/workspace organization, topology and tmux-like verbs, prompt composer work, agent catalog surfaces, project panels, QA matrix depth, command palette search, branch picker, deeper notification inbox controls, theme customization, and broader Ghostty options.
- Use GitHub Issues for bugs, GitHub Discussions for questions, and private vulnerability reporting for security issues.

## Site and crawler files

- `https://forktty.dev/sitemap.xml`: canonical indexable site pages for search crawlers.
- `https://forktty.dev/robots.txt`: allows public crawlers and advertises the sitemap.
- Intent-specific search pages: `https://forktty.dev/codex`, `https://forktty.dev/claude-code`, `https://forktty.dev/mcp`, `https://forktty.dev/git-worktrees`, `https://forktty.dev/agent-hud`, `https://forktty.dev/ghostty-terminal`, `https://forktty.dev/pty-persistence-dtach`, `https://forktty.dev/team-orchestration`, and `https://forktty.dev/alternatives`.
- `https://forktty.dev/llms.txt`: compact agent retrieval map.
- `https://forktty.dev/llms-full.txt`: this single-file agent context.
- `https://forktty.dev/admin/telemetry`: private telemetry dashboard, Basic Auth, `X-Robots-Tag: noindex, nofollow, noarchive`.
- `https://forktty.dev/api/telemetry/ping`: anonymous daily ping endpoint, POST-only, `X-Robots-Tag: noindex, nofollow, noarchive`.

## Source of truth links

- Docs wiki: https://forktty.dev/docs
- Landing page: https://forktty.dev/
- Site privacy: https://forktty.dev/privacy
- Repository: https://github.com/Lucenx9/forktty
- Releases: https://github.com/Lucenx9/forktty/releases
- README: https://raw.githubusercontent.com/Lucenx9/forktty/main/README.md
- SPEC: https://raw.githubusercontent.com/Lucenx9/forktty/main/SPEC.md
- CHANGELOG: https://raw.githubusercontent.com/Lucenx9/forktty/main/CHANGELOG.md
- AGENTS guide: https://raw.githubusercontent.com/Lucenx9/forktty/main/AGENTS.md
- Hooks README: https://raw.githubusercontent.com/Lucenx9/forktty/main/hooks/README.md
- Privacy: https://raw.githubusercontent.com/Lucenx9/forktty/main/PRIVACY.md
- Security: https://raw.githubusercontent.com/Lucenx9/forktty/main/SECURITY.md
- Roadmap: https://raw.githubusercontent.com/Lucenx9/forktty/main/ROADMAP.md
- Contributing: https://raw.githubusercontent.com/Lucenx9/forktty/main/CONTRIBUTING.md
- Support: https://raw.githubusercontent.com/Lucenx9/forktty/main/SUPPORT.md