Thanks to visit codestin.com
Credit goes to forktty.dev

Skip to content
forktty_
Documentation

ForkTTY wiki.

Install ForkTTY, wire up agents, use the local socket and MCP bridge, manage git worktrees, and check the privacy and security model from one stable onsite reference.

Start here

Overview

ForkTTY is a Linux-native GTK/Ghostty terminal for coordinating coding agents in tiled workspaces.

ForkTTY is built for running Codex, Claude Code, Pi, Antigravity, OpenCode, Grok Build, and plain shell tools side by side without losing track of sessions, panes, or repo state. The app is written in Rust and uses GTK4/libadwaita with an embedded Ghostty terminal renderer.

  • Use tiled workspaces and split panes for parallel agent work.
  • Back tasks with git worktrees so each branch has an isolated workspace.
  • Drive the app through the same local socket surface used by the CLI and MCP bridge.
  • Keep project contents, terminal text, and agent metadata local by default.

The current alpha is Linux-only. The packaged runtime is focused on GTK/Ghostty terminal panes; source-only browser panes remain behind the optional browser feature for intentional testing.

Quick start

Install and first run

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

PathUse it when
AppImageRecommended portable Linux x86_64 build. Verify SHA256SUMS, mark executable, and launch directly.
.debDebian 13/Trixie+ and Ubuntu 24.04 LTS+ package path. Debian 12 is below the documented baseline.
Source buildUse when developing ForkTTY or testing source-only browser panes. Requires Rust 1.96+, GTK4/libadwaita dev files, git, Zig, and the Ghostty submodule.
$ 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 with 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.

The AppImage prefers the host GTK/libadwaita stack when available and keeps its bundled GTK copy as a fallback. Set FORKTTY_APPIMAGE_GTK_RUNTIME=bundled, host, or auto to force that choice while debugging renderer issues; ForkTTY also honors explicit GSK_RENDERER overrides.

Operate

Daily use

ForkTTY keeps terminal work dense: workspaces, tabs, split panes, search, settings, notifications, and quake mode are all native GTK surfaces.

  • Open the command palette with Ctrl+Shift+P for actions such as new workspace, split, settings, notifications, and shortcuts; Ctrl+? (or F1) opens Keyboard Shortcuts, Ctrl+, opens Settings, and F10 opens the Main Menu when focus is outside terminal content.
  • Use split panes and tabs to keep multiple agents visible without mixing their scrollback; drag pane headers to swap panes.
  • Session restore writes native state to ~/.local/state/forktty/session-v2.json. By default live PTYs are not persisted, 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.
  • 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.

The app follows a compact native design: quiet chrome, dense status rows, native dialogs, and terminal-owned theme behavior instead of marketing-style panels inside the product UI.

Plain terminal process persistence is optional because it needs a detach broker on PATH. ForkTTY currently uses dtach: install it with the native package manager where available, then enable Settings > Worktrees > Persist terminal processes and check forktty capabilities for PTY broker availability.

Distro familydtach install command
Debian / Ubuntu / Mint / Pop!_OSsudo apt update && sudo apt install dtach; on minimal Ubuntu bases, enable universe first if apt cannot find it.
Fedorasudo dnf install dtach
RHEL / CentOS Stream / Rocky / AlmaEnable the matching EPEL repository first, then sudo dnf install dtach.
Arch / CachyOS / EndeavourOS / Manjarodtach is not in the official Arch repos; install dtach from AUR or build upstream dtach from source.
openSUSE Tumbleweedsudo zypper install dtach
openSUSE LeapUse the openSUSE package page/backports if your Leap release does not expose an official dtach package.
Alpinesudo apk add dtach
Gentoosudo emerge app-misc/dtach
NixOS / NixAdd pkgs.dtach to your system or shell environment, then restart ForkTTY so it is on PATH.
Void Linuxsudo xbps-install -S dtach if available for your repository; otherwise build upstream dtach from source.
# universal source fallback
git clone https://github.com/crigler/dtach.git
cd dtach
./configure
make
sudo make install
forktty capabilities | grep -i pty
Agents

Agent integrations

The Agent HUD is powered by hooks and socket metadata so running agents can be scanned, focused, resumed, and inspected.

ForkTTY targets Codex, Claude Code, Pi, Antigravity, OpenCode, Grok Build, 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, add source/age metadata and diagnostic lifecycle_evidence for freshness checks against the workspace/provider status row, and provider-scoped HUD metadata is cleared when the last matching session ends, closes, hibernates, or is forgotten. The 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 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 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.

  • Use forktty agents to list known agent sessions.
  • Use forktty agent-health to inspect stale or resumable sessions.
  • Use forktty resume-agent when a provider supports reopening a saved session.
  • Use forktty set-status, set-progress, log, notify, and notifications for custom tools that publish agent state without a managed hook.
  • Prompt notifications keep approval state as pending, approved, denied, dismissed, or stale; dismiss/clear syncs in-app state with desktop notifications and OSC 99 close reports, the latest-target action prioritizes unread prompts before lower-urgency history, and approve/deny decisions are accepted only while the approval is pending.

Provider keys and remote agent traffic stay outside ForkTTY. Bring your own agent CLI and credentials; ForkTTY coordinates local panes, metadata, hooks, socket calls, and notifications.

Automation

Hooks

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

$ 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
ProviderManaged destination
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, ForkTTY sets APPIMAGE_EXTRACT_AND_RUN=1 for those generated commands so short hooks do not keep FUSE AppImage mounts alive. Antigravity lifecycle hooks such as PreInvocation use flat handler entries; its 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

MCP setup

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

$ 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 and does not open a network listener. It exposes identify, workspace, surface, context snapshot, task strategy planning, agent, worktree, notification, feed, workflow, team, topology, browser, and status tools where supported by the running app. identify treats ForkTTY pane workspace/surface env ids as caller context instead of mandatory targets. 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.

ClientConfig location
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
Skills

Agent skills

The ForkTTY orchestration skill tells agents when to use context snapshots, provider capabilities, team workers, status checks, worktree boundaries, and local setup diagnostics.

$ forktty skills setup
$ forktty skills setup agents --dry-run
$ forktty skills setup pi
$ forktty skills setup claude
$ forktty skills remove agents

The managed skill is named forktty-agent-orchestration. It is instruction-only: agents learn to call task_strategy_plan before choosing team, workflow loop, worktree, or multi-harness execution for non-trivial tasks; task planning returns planner_version plus 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, mutating task_kind hints plus high-confidence goal-based likely edit-intent inference, profile inference for clear fast/conservative/parallel/review-heavy goals (goal keyword inference is English-only), caller-normalized task_kind hints for multilingual intent, primary read-only review goals and explicit read-only parallel reviews do not force dirty-repo worktree isolation, 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 plus inferred advisory soft cooldowns from recent failed task-strategy workflow history, and harness parallel-session capacity including multiple lanes on one capable harness; use task_strategy_apply only after explicit approvals to stage visible workflow/team/task/message state by default, bootstrap an initial planned workflow loop record for loop_metadata plans without starting a scheduler, default MCP apply to the current workspace/surface when explicit target selectors are omitted, recompute dirty-repo edit isolation from selected target cwd plus normalized plan task_class and mutating strategy shape, worktree approvals, and multi-worker submit approvals from the selected target, requested operation, and effective plan shape, require explicit cwd to be inside a Git repository already represented by an open ForkTTY workspace, surface, or effective project cwd and canonicalize it before launch/retry checks, 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 after assignment harness launchability is validated before workflow/team mutation, with launch failures appending an advisory next-best-harness hint for the same role without automatic retry; any worktree-layer apply requires worktree_name for an already-open ForkTTY worktree workspace and role prompts name that worktree plus its effective cwd; 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 including plan-mode reviewer support and parallel capacity, compact workflow_summaries, loop_summaries, 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 including `loop_never_recorded` for finished bootstrapped loops still at iteration 0 with no gates and loop risk flags before treating work as finished; run forktty cleanup orchestration --dry-run or MCP orchestration_cleanup before applying stale record cleanup; 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 for non-superseded messages with explicit submit/Enter semantics for worker prompts; 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 persist worker final reports with team_worker_upsert.report or a team mailbox message plus durable workflow/team/loop evidence for long-running coordination, with workflow_loop_set advancing loop state after apply bootstraps loop_metadata plans. Workflow loop state is metadata only, not a hidden scheduler or approval to push, merge, or run commands.

TargetSkill location
Agent Skills-compatible tools~/.agents/skills/forktty-agent-orchestration
Codex aliasSame interoperable agents target
Pi aliasSame interoperable agents target
Claude Code$CLAUDE_CONFIG_DIR/skills/forktty-agent-orchestration or ~/.claude/skills/forktty-agent-orchestration

Setup refuses to overwrite an unmanaged skill with the same name. Updating, repairing, or removing a ForkTTY-managed skill moves the previous directory to a .bak-* backup first. Non-dry-run setup/remove keep the three newest ForkTTY-managed backups per target and prune older managed backups, while leaving backup-like directories without the ForkTTY marker untouched. 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.

Reference

Socket CLI and API

The CLI and MCP bridge share one newline-delimited JSON-RPC-like socket API.

ForkTTY binds an owner-only Unix socket at $XDG_RUNTIME_DIR/forktty.sock, with fallback /tmp/forktty-<uid>/forktty.sock. Set FORKTTY_SOCKET_PATH=/absolute/path to override it for both the app and CLI.

$ 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 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
$ forktty cleanup orchestration --dry-run
$ 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

High-level CLI wrappers compose existing socket methods for common agent coordination flows. task-plan accepts goals up to 4096 UTF-8 bytes without terminal control characters other than newline or tab and asks the read-only task router whether work should stay solo, use a workflow loop, add review, use team workers, or isolate in a worktree before anything is launched or mutated; the response includes planner_version plus 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, explicit --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, mutating task_kind hints plus high-confidence goal wording are used to infer likely user-visible edit intent, clear high-confidence wording can infer fast/conservative/parallel/review-heavy profiles when omitted, and callers can pass task_kind when they have normalized clear user intent across languages, primary review goals and explicit read-only parallel reviews remain read-only review work even in dirty repos, completed task-strategy workflows can infer advisory last-known-good strategy/harness stickiness when optional last_known_good is omitted, optional harness_signals let callers pass concrete cooldown/lockout evidence with reason text bounded to 512 UTF-8 bytes without control characters and an optional cooldown_kind (quota, auth, crash, or timeout) that scales the soft penalty with the cause, harnesses without caller signals get an inferred advisory soft cooldown from recent failed task-strategy workflows, and reviewer strategies include an explicit reviewer assignment. identify is the compact read for canonical workspace/surface/effective_project_cwd plus caller 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. wait agent-status performs bounded read-only lifecycle polling through short context.snapshot reads without terminal text reads. workflow-loop-set records closed-loop state on an existing workflow: recipe, stage, iteration budget, stop reason, and compact gate statuses. It is metadata only; 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. team ask and team review create or update the team, create the task before launching a fresh worker surface, assign it after launch, queue the prompt, and dispatch it with provider-aware terminal submit behavior when submit mode is requested; Codex/Claude/Pi/Grok 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. The worker is bound to the invoking ForkTTY pane or workspace when available, and MCP team_upsert uses the same pane defaults. Low-level team_worker_launch with worktree_name opens the worker in that already-open worktree workspace and inherits that cwd; task-strategy explicit cwd is canonicalized before launch/retry checks, worktree prompts name both the worktree and effective cwd, and without worktree_name it falls back from a stale leader surface to the team workspace focus before inheriting the selected surface's recorded terminal cwd, not hook-reported resume_cwd. Re-run the wrappers to launch a new worker, or use team-message-send plus team-message-dispatch for follow-up prompts to an existing worker. Superseded deterministic role prompts remain in full team history but cannot be dispatched or acknowledged and are excluded from normal team inbox and pending counts. team finish / team_finish verifies open tasks, pending messages, and live-looking worker final states, 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. cleanup orchestration / 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. team_worker_shutdown uses the same provider-aware submit behavior by default, and its close_surface option immediately closes only disposable surfaces created by team_worker_launch in the current ForkTTY runtime; it is cleanup, not proof that 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. 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. Context snapshots include compact workflow_summaries with surface_present/stale_binding signals, loop_summaries, and team_summaries for leader monitoring; loop_summaries omit full workflow goals, memory, evidence, and gate notes, full workflow records, team records, and mailbox message bodies are opt-in with include_workflow_details/include_team_details, feed status/progress trace rows are opt-in with include_feed_trace, effective_project_cwd clarifies the actual project directory but worktree authorization trusts only visible workspace/surface cwd, workflow/team consistency warnings and loop risk flags surface in risk_flags, and team_worker_health includes final_state for cleanup decisions while using model-plus-runtime liveness to treat workers as live only when their surface still exists in both the workspace model and terminal backend; readiness is reported separately.

  • 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 strategy methods cover read-only routing plus approved apply that recomputes dirty edit isolation and approval gates before visible team/workflow mutation.
  • Agent methods cover agent listing, health, 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 align desktop, in-app, OSC 99, and persisted approval state; only pending approvals raise the context snapshot pending_approval risk flag.
  • Metadata methods publish status, progress, logs, and statusline output.
  • Status helpers explain context snapshots, watch delayed state, and expose the context-snapshot alias used by CLI and MCP automation with per-surface plus aggregate-bounded terminal tails.
  • Generated bash, zsh, and fish completions cover the curated ergonomic command set and grouped team/status subcommands.
  • 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.
Repos

Git worktrees

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

$ 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 and are constrained to repositories the user has opened, so automation cannot operate on arbitrary repos behind the user's back.

  • Default layout can place worktrees under a repo-local .worktrees directory or sibling layout depending on configuration.
  • 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.
Local state

Configuration and local files

ForkTTY stores bounded config, session, browser profile, and state files under normal XDG locations.

PathPurpose
~/.config/forktty/config.tomlUser configuration for ForkTTY-owned behavior.
~/.local/state/forktty/session-v2.jsonWorkspace, pane, and recent terminal text-tail session state.
~/.local/share/forktty/browser_profiles/profiles.jsonSource-only browser profile index.
~/.local/share/forktty/browser_profiles/<id>/Source-only WebKit profile data.

ForkTTY now leaves Ghostty-owned terminal appearance and runtime behavior to Ghostty configuration, except that 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. The opt-in persistent_scrollback_lines tail restore uses the embedded Ghostty visible-text path until a native bounded-tail ABI exists; use read-screen/surface_read_text scope=all for bounded full text reads. Legacy TOML keys for ForkTTY theme source, terminal font, theme, bell, renderer, and scrollback still load for compatibility but are not exposed in newly saved settings.

[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
Privacy

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, terminal contents, project paths, socket payloads, agent metadata, usernames, hostnames, or install identifiers to ForkTTY infrastructure.

  • Anonymous app telemetry is a daily ping 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 whatever your desktop environment needs to display them.
  • Disable app telemetry from the first-launch privacy prompt or config.
Security

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.
  • Socket payloads and list limits are bounded to avoid unbounded memory requests.
  • Notification commands are executed as argv, not through shell pipelines.
  • Config and session recovery quarantine malformed, oversized, or invalid state instead of repeatedly loading it.
  • Embedded Ghostty library loading canonicalizes candidate paths and rejects relative, non-regular, untrusted, or writable-by-others paths.
  • Security reports should use GitHub private vulnerability reporting.

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.

Fixes

Troubleshooting

Start with doctor output, package baseline checks, renderer overrides, and the socket path.

$ forktty doctor
$ forktty --json doctor
$ forktty ping
$ FORKTTY_APPIMAGE_GTK_RUNTIME=host ./forktty-*.AppImage
$ GSK_RENDERER=gl ./forktty-*.AppImage
$ FORKTTY_SOCKET_PATH=/absolute/path forktty ping
  • 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 a supported Debian 13/Trixie+ or Ubuntu 24.04 LTS+ baseline.
  • 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. Include forktty --json doctor when MCP or skill path diagnostics matter.
Releases

Changelog highlights

The latest recorded release is 0.2.0-alpha.18 from 2026-07-06.

  • 0.2.0-alpha.18 ships the attention-first Router rail and workflow feed pass with collapsible surfaces, notification controls, approval actions, feed filters, and tighter status styling.
  • 0.2.0-alpha.18 hardens hook-driven agent status, MCP/task-strategy routing, workflow-loop evidence, orchestration cleanup, worker reports, and release QA docs.
  • 0.2.0-alpha.17 adds Grok Build as a visible team/router harness and ships the first task-strategy router stabilization pass for multi-harness apply/submit flows.
  • 0.2.0-alpha.17 hardens Feed, team, workflow, and task-strategy persistence/retry paths found during router and store audits.
  • AppImages prefer the host GTK/libadwaita stack when available and keep the bundled GTK copy as a fallback/override for hosts without GTK4.
  • 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 and scrollbar, with a bounded default of 10 MB per surface.
  • 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 preserve Codex and Claude Code bypass-permissions sessions instead of restarting them in prompted mode.
  • 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 the canonical https://forktty.dev domain.
Project status

Roadmap, limitations, and support

ForkTTY is an early alpha with a Linux-first roadmap and explicit non-goals.

  • Known limitations: Linux-only, libadwaita 1.4+ baseline, AppImage host display/GL dependencies, PTYs not persisted by default unless dtach-backed persistence is enabled, 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.

Source references

This page is maintained from the public ForkTTY repository. Use these files when you need the raw source document behind the onsite wiki.