# ForkTTY

> ForkTTY is a Linux-native GTK4/libadwaita terminal workspace with embedded Ghostty-backed panes. It focuses on projects, tabs, splits, git worktrees, notifications, session restore, a command palette, an owner-only local socket, and optional manual agent lifecycle hooks. Coding agents are ordinary terminal processes; ForkTTY does not include task routing, teams, workflows, a feed, approval orchestration, an MCP bridge, or managed agent skills.

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. For one self-contained context file, fetch `https://forktty.dev/llms-full.txt`.

Key facts:

- Linux-only, AGPL-3.0-only, Rust, GTK4/libadwaita, embedded Ghostty terminal panes.
- AppImage auto mode runs a real eager loader compatibility probe with the effective loader environment. Host GTK/libadwaita is used only when both the ForkTTY binary and embedded Ghostty library load; otherwise AppRun selects its bundled fallback. Terminal child environments are sanitized only after the GTK-linked helper has loaded.
- Packaging runs `ghostty-gtk-lib-probe.sh --ensure --print-path`; every invocation enters the incremental Zig build graph and verifies every mandatory embedding ABI symbol.
- Embedded Bash, Zsh, fish, Elvish, and Nushell preserve Ghostty shell integration and `TERM=xterm-ghostty`; Ghostty widget close requests use ForkTTY confirmation while socket/API close remains noninteractive.
- Bring your own agent CLI, account, and subscription; ForkTTY provides no model access.
- Agent hooks are explicit and reversible: Settings > Agent hooks names installed providers, confirms writes, and removes only ForkTTY-managed entries while preserving unrelated configuration. Hooks report lifecycle and attention state; they never move focus or rearrange panes.
- Codex hooks launched by its shared app-server can recover the lifecycle badge for a local `codex-tui` session only when one unclaimed same-cwd Codex TUI process belongs to one eligible ForkTTY surface; additional or external same-cwd TUIs stay unassigned.
- Core UI: a compact overlay workspace sidebar, tabs, split panes with consistent global zoom, keyboard navigation, drag and drop, notifications, unread state, attention rings, command palette, and layout restore with each local terminal pane's last live working directory. Opening the sidebar does not resize terminal panes; its dense flat rows use restrained selection and reorder cues, pane counts read as borderless metadata, and routine activity summaries appear only for attention, error, or terminal-exit states. Quiet GTK chrome uses one permanent global titlebar, compact split-pane headers whose pane-action hover fills remain inset from the focus hairline, no redundant bottom status bar, a seven-step type scale, a single warm accent, AA-readable muted text, and consistent 4/6/8px radii. Settings uses General, Integrations, and System navigation with subtle raised preference groups. Captured pane actions do not retarget after focus changes, and failed new-tab spawns restore the prior pane layout and focus; maximize requires multiple real panes and clears on collapse; the visible notification panel reconciles every 500 ms with immediate Dismiss/Clear refresh; SSH rows show `ssh:<host> · connected|disconnected` from local terminal readiness.
- Live `/proc/<pid>/cwd` values containing non-UTF-8 Unix bytes are ignored so the last valid cwd remains safe for JSON responses and session persistence.
- Optional lifecycle hooks log non-attention notifications without changing lifecycle, so informational notifications after `Stop` do not revive an idle agent.
- The Worktree manager keeps the source workspace and path visible, uses one mode-specific target form, and states that removal leaves the git branch intact. For the exact worktree-name/canonical-path identity, Git worktree Create/Attach retries reuse the same existing modeled workspace ID and allocate no new modeled surface. GTK/socket mutations serialize process-locally (not as a cross-process Git lock), and Remove suppresses automatic terminal respawn until the exact target commits or rollback attempts restoration; if terminal respawn fails, ForkTTY records a blocking terminal error status before suppression ends.
- The owner-only JSON-RPC Unix socket exposes 50 workspace, pane, terminal, notification, metadata, worktree, project-action, remote, and thin agent-lifecycle methods.
- `notification.list` returns one oldest-to-newest page: `limit` defaults to 200 and accepts 1–200, optional `before_id` is an exclusive retained-item cursor, and the CLI never aggregates pages automatically. `context.snapshot` includes the newest 100 matching notifications, omits `terminal_metadata.icon_data`, and checks unread-prompt risk across the full matching set.
- Normal response lines are capped at 64 MiB including the terminating newline; an oversized result becomes `response_too_large` with the original request id.
- Official clients and startup collision checks share a deadline-bounded nonblocking AF_UNIX connector. A full Linux accept backlog retries with a fresh descriptor until the deadline; timeout means occupied/foreign, so the existing socket inode is never removed or replaced.
- Cooperative GTK shutdown first stops new socket dispatch while the UI remains alive, then drains admitted requests and waits for the socket runtime to drop. Only afterward finalization snapshots bounded terminal scrollback, synchronizes live working directories, saves the session, cleans up configured PTY persistence, and closes the window.
- Optional hooks are installed and updated only through explicit `forktty hooks setup`; startup never changes agent configuration.
- Hook-backed permission, elicitation, and recognized attention notifications carry normalized provider/session prompt identities. Accepted results retain only the matching in-app notification as read history and close its desktop notification; stale retries are inert, and cleanup/removal preserves unrelated prompts.
- External MCP clients and servers run normally inside terminal panes. ForkTTY itself does not ship or register an MCP server.
- Upgrades do not edit external agent configuration automatically. Before replacing an orchestration build, use that older binary's `forktty mcp remove --dry-run` and `forktty skills remove --dry-run`, then apply the removals; also marker-check and delete the `forktty-agent-orchestration.bak-*` directories preserved by the old skill remover.
- Optional dtach-backed persistence keeps plain terminal processes alive across UI restarts.
- Source-only browser panes remain behind the optional `browser` feature and are not included in release artifacts.

Useful commands:

```sh
forktty doctor
forktty capabilities
forktty identify --json
forktty context-snapshot --tail-lines 0 --json
forktty workspaces
forktty surfaces
forktty tree
forktty read-screen
forktty capture-tail
forktty notifications
forktty agents
forktty agent-health
forktty hooks setup --dry-run
```

## Recommended context

- [Docs wiki](https://forktty.dev/docs): Install, daily use, hooks, socket automation, worktrees, privacy, security, and troubleshooting
- [Codex workspace](https://forktty.dev/codex), [Claude Code workspace](https://forktty.dev/claude-code), [external MCP tools](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), [parallel panes](https://forktty.dev/team-orchestration), and [alternatives](https://forktty.dev/alternatives): intent-specific pages
- [Full agent context](https://forktty.dev/llms-full.txt): Single-file context for one-fetch retrieval
- [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, socket 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 repository conventions
- [GitHub repository](https://github.com/Lucenx9/forktty): Source code
- [Releases](https://github.com/Lucenx9/forktty/releases): AppImage and deb downloads

## Retrieval paths

- Install or run ForkTTY: read README, then Releases.
- Automate via socket or CLI: read SPEC and `docs/socket-api.md`.
- Configure optional lifecycle hooks: read `hooks/README.md` and `docs/agents.md`.
- Explain privacy, telemetry, or updates: read PRIVACY and README.
- Diagnose a breaking change: read CHANGELOG and the matching release.
- Discover indexable site pages: read the Sitemap.

## Policies

- [Site privacy](https://forktty.dev/privacy): Site hosting, analytics, app telemetry endpoint, and provider links
- [Security policy](https://raw.githubusercontent.com/Lucenx9/forktty/main/SECURITY.md): Security model and vulnerability reporting
- [Privacy](https://raw.githubusercontent.com/Lucenx9/forktty/main/PRIVACY.md): Anonymous usage ping, update checks, and local data boundaries

## Optional

- [Roadmap](https://raw.githubusercontent.com/Lucenx9/forktty/main/ROADMAP.md): Planned direction and explicit non-goals
- [Architecture comparison](https://raw.githubusercontent.com/Lucenx9/forktty/main/docs/cmux-architecture-review.md): Evidence-based cmux comparison and simplification rationale
- [Contributing](https://raw.githubusercontent.com/Lucenx9/forktty/main/CONTRIBUTING.md): Contributor workflow
- [Support](https://raw.githubusercontent.com/Lucenx9/forktty/main/SUPPORT.md): Getting help
- [Landing page](https://forktty.dev/): Product overview and downloads
- [Sitemap](https://forktty.dev/sitemap.xml): Canonical index of site pages