# ForkTTY full agent context

> ForkTTY is a Linux-native terminal workspace for coding agents, built in Rust with GTK4/libadwaita and embedded Ghostty-backed panes. It provides projects, tabs, splits, git worktrees, notifications, session restore, a command palette, an owner-only local socket, and optional manual agent lifecycle hooks. It is local-first, Linux-only, AGPL-3.0-only, and currently alpha.

This file is the concise, single-fetch public context. For exact behavior, the repository README, SPEC, CHANGELOG, and source are authoritative.

## Product boundary

ForkTTY is a terminal workspace, not an agent platform. Codex, Claude Code, Pi, Antigravity, OpenCode, Grok Build, shells, editors, and servers run as ordinary terminal processes.

ForkTTY includes:

- Embedded Ghostty terminal panes in a native GTK4/libadwaita shell; ForkTTY's
  current global zoom carries across newly opened panes.
- A compact vertical workspace overlay, tabs, split panes with compact headers
  and a focused-pane accent, focus navigation, drag and drop, and layout
  restore. Opening the sidebar does not resize terminal panes; 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 with one permanent global titlebar, compact split-pane
  headers whose pane-action hover fills remain inset from the focus hairline,
  and no redundant bottom status bar. It uses 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.
- OSC notifications, desktop notifications, unread state, attention rings, and generic progress/status metadata.
- Git branch and directory information plus git worktree workspace flows.
  The Worktree manager keeps the source workspace and path visible, uses one
  mode-specific target form, and makes clear that removal leaves the branch
  intact.
- A command palette and an owner-only Unix socket for terminal workspace primitives.
- Optional, explicitly installed lifecycle hooks and a thin Agent HUD for focus, health, hibernate, reclaim, and resume.
- Optional dtach-backed persistence for plain terminal processes.

ForkTTY does not include:

- A task router, task-strategy planner, provider selector, role assignment, or harness ranking.
- Team records, team mailboxes, workflow state, workflow loops, orchestration cleanup, or approval state machines.
- A right-side orchestration rail, Team sidebar section, or bottom workflow feed.
- A built-in MCP bridge, managed MCP registration, or managed agent skill installer.
- Automatic hook installation or update at startup.
- Model access, provider credentials, prompt proxying, or a hidden background scheduler.

External MCP clients and servers remain compatible because they are normal processes. Configure MCP in the agent tool that owns it, then run that client or server inside a ForkTTY pane.

### Upgrade cleanup

Older orchestration builds may have left MCP registrations and the `forktty-agent-orchestration` skill in external agent configuration. The terminal-core build does not mutate those files automatically. Before replacing the old binary, run:

```sh
forktty mcp remove --dry-run
forktty mcp remove gemini --dry-run
forktty skills remove --dry-run
forktty mcp remove
forktty mcp remove gemini
forktty skills remove
```

The old skill remover preserves removed installs as sibling `forktty-agent-orchestration.bak-*` directories. Whether or not the old binary is available, remove those backups only when each candidate is a real directory, not a symlink, and its `SKILL.md` contains `<!-- forktty-managed-agent-skill -->`. If the old binary is unavailable, back up the affected files and remove only MCP entries with `FORKTTY_MCP_MANAGED=forktty` and active skill directories carrying the same skill marker. The README lists the exact Codex, Claude Code, Antigravity, Agent Skills, and Claude skill paths.

## Install and first run

Release artifacts are AppImage and deb packages for Linux x86_64. The AppImage is the portable path; the deb targets Debian 13/Trixie+, Ubuntu 24.04 LTS+, and compatible derivatives.

```sh
chmod +x ForkTTY-*.AppImage
./ForkTTY-*.AppImage
forktty doctor
```

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, immediately before it executes the real command.

Packaging runs `ghostty-gtk-lib-probe.sh --ensure --print-path`. Every invocation enters the incremental Zig build graph and then verifies every mandatory embedding ABI symbol before the library is accepted.

Embedded Bash, Zsh, fish, Elvish, and Nushell sessions preserve Ghostty shell integration and `TERM=xterm-ghostty`. A close request from the Ghostty widget uses ForkTTY's confirmation dialog; socket/API close remains noninteractive.

ForkTTY uses a DBus single-instance application. A second launch delegates to the running app. Source-only browser panes are behind the optional `browser` feature and are excluded from release artifacts.

## Terminal workspace

- Open the command palette with `Ctrl+Shift+P`.
- Use the workspace sidebar for projects and tabs/splits for concurrent processes. Pane and tab actions remain bound to the surface that opened them even if focus changes before activation. If a new tab cannot start, the previous pane layout and focus are restored.
- Pane chrome is hidden for a single-pane workspace by design. Maximize applies only to real multi-pane trees, counts multiple tabs as one pane, and clears when a split collapses.
- Drag pane headers to rearrange panes.
- While visible, the notification panel reconciles rows, count, Clear, and Open Latest every 500 ms from one current snapshot; Dismiss and Clear refresh immediately.
- SSH workspace metadata displays `ssh:<host> · connected` or `ssh:<host> · disconnected` from local terminal readiness, not a separate network/authentication heartbeat.
- Session restore saves layout and each local terminal pane's last live working directory in `~/.local/state/forktty/session-v2.json`. 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.
- Plain terminal processes do not survive UI restarts by default. Enable `general.persist_terminal_processes` when `dtach` is installed to opt in.
- Terminal scrollback is bounded; `persistent_scrollback_lines = 0` leaves persistent disk scrollback disabled.

## Agent lifecycle

Agents require no ForkTTY-specific setup. Optional hooks for Codex, Claude Code, Antigravity, and OpenCode publish provider-neutral lifecycle metadata such as session id, cwd, status, last activity, attention, and resume information.

Non-attention hook notifications are logged without changing lifecycle, so informational notifications received after `Stop` do not revive an idle agent.

Restored agent panes resume only through a validated provider command. Invalid persisted session IDs, resume directories, or unsupported providers produce a visible terminal error and never fall back to an unrelated plain shell.

Persisted `Suspended` is a durable tombstone. Late hooks cannot revive that session, emit metadata or notifications, resolve prompts, or advance its event-order watermark; only explicit resume can replace the state.

Hook-backed permission, elicitation, and recognized attention notifications carry normalized provider/session prompt identities. Accepted result events retain only the matching in-app notification as read history and close its desktop notification; stale retries do nothing. Session cleanup, target remap, and surface/workspace removal retire affected correlations while preserving unrelated unread prompts and terminal output attention.

Hook changes are always explicit:

```sh
forktty hooks setup --dry-run
forktty hooks setup codex
forktty hooks setup claude
forktty hooks setup antigravity
forktty hooks setup opencode
```

The managed event sets contain Codex 10, Claude 25 lifecycle / 28 full, Antigravity 3, and OpenCode 11 events. Claude lifecycle excludes only `PreToolUse`, `PostToolUse`, and `PostToolUseFailure`; `PostToolBatch` remains for prompt-result correlation. Claude `SessionStart` enrichment requires workspace ID, surface ID, and an absolute socket path together. Partial provenance returns the exact continue response without socket I/O.

Codex may run hooks through a shared app-server without the originating pane's `FORKTTY_*` environment. A local session whose `session_meta` originator is `codex-tui` may use the default owner-only socket, but ForkTTY binds it only when one unclaimed same-cwd Codex TUI process belongs to one eligible surface. Another unclaimed same-cwd TUI, including one outside ForkTTY, leaves the hook unassigned instead of falling back to active focus.

`forktty hooks doctor <agent>` is local and read-only. Its additive version-1 `installationCheck` regenerates the canonical setup plan and gates top-level health on complete configs/plugins, one usable launcher, and exact regular executable Antigravity wrappers. Missing, malformed, partial, modified, or non-executable assets are unhealthy.

Startup does not install or refresh hooks and does not nag about missing hooks. Optional setup remains available from the first-run welcome flow, Settings > Agent hooks, and the CLI. Settings names installed providers, confirms setup and updates before writing, and removes only ForkTTY-managed entries while preserving unrelated provider configuration. Hooks report lifecycle and attention state; they never move focus or rearrange panes.

The thin agent surface consists of:

```sh
forktty agents
forktty agent-health
forktty agent-reclaim-plan
forktty hibernate-agent
forktty reclaim-agent
forktty resume-agent
```

Persisted lifecycle data is not proof that a process is live. Consumers should inspect source, age, lifecycle evidence, surface presence, and current terminal state.

## Socket CLI and API

The GTK app and CLI share an owner-only newline-delimited JSON-RPC-like Unix socket. The core registry exposes 50 public/connection methods. Browser builds add browser-specific methods behind the source-only feature.

Useful reads:

```sh
forktty capabilities
forktty identify --json
forktty context-snapshot --tail-lines 0 --json
forktty workspaces
forktty surfaces
forktty tree
forktty top
forktty read-screen
forktty capture-tail
forktty notifications
forktty actions
forktty remotes
```

Method families cover:

- System capabilities and canonical caller/target identification.
- Workspace and surface list, create, focus, rename, split, close, restart, and tree operations.
- Bounded visible-text and scrollback-tail reads with complete-source line
  counts, plus terminal input.
- Generic notification, status, progress, log, and statusline publication.
- Workspace-scoped plus global notification rows in context snapshots; unread prompts add `notification_needs_input` to risk flags.
- Git worktree and repository-local project actions.
- Remote inventory.
- Six thin agent lifecycle operations: list, health, reclaim plan, hibernate, reclaim, and resume.

`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.

The socket has no router, task strategy, team, workflow, feed, approval orchestration, MCP, or skill-management methods.

Security properties:

- Socket and parent paths must be controlled by the current user (symlinked parents are rejected) and use restrictive permissions; accepted connections must carry same-user (or root) SO_PEERCRED credentials.
- Request lines and terminal reads are size-bounded.
- Terminal output is untrusted input.
- Project actions use validated argv arrays and never `sh -c`.
- Worktree operations are limited to repositories visibly represented by a workspace or pane cwd.
- `FORKTTY_SOCKET_PATH` must be absolute when overriding the runtime socket.

## Git worktrees

ForkTTY treats git worktrees as visible project workspaces for parallel editing without checkout collisions.

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

Create, attach, merge, and remove flows validate the repository boundary. Dirty-state checks prevent destructive operations from silently discarding uncommitted work. Repository-local setup/teardown hooks and project actions remain explicit and argv-based.

For the exact worktree-name/canonical-path identity, Create and Attach retries reuse the same existing modeled workspace ID and allocate no new modeled surface; same-named worktrees at different canonical paths remain separate. GTK and socket worktree mutations serialize inside the running ForkTTY process through commit or rollback. That coordination is process-local, not a cross-process or distributed Git lock. Remove suppresses automatic terminal respawn while the exact target's terminals are quiesced, then either commits the model change or attempts to restore the prior runtime/model state. Terminal respawn during rollback can fail; ForkTTY then records a blocking terminal error status before suppression ends.

## Configuration and local files

Default paths:

- Config: `~/.config/forktty/config.toml`
- Session layout: `~/.local/state/forktty/session-v2.json`
- Runtime socket: `$XDG_RUNTIME_DIR/forktty.sock`
- Logs: `$XDG_STATE_HOME/forktty/logs` or `~/.local/state/forktty/logs`

Example:

```toml
[general]
restore_session = true
persist_terminal_processes = false

[terminal]
persistent_scrollback_lines = 0

[telemetry]
anonymous_ping = true
endpoint = "https://forktty.dev/api/telemetry/ping"
```

Older router, provider-policy, team, rail, and feed configuration keys are ignored because those product surfaces no longer exist.

## Privacy and telemetry

ForkTTY does not send terminal contents, project data, paths, socket payloads, agent metadata, usernames, hostnames, or install identifiers to ForkTTY infrastructure.

The app can send one anonymous usage ping per day. It contains coarse application and platform information and is controlled by `telemetry.anonymous_ping`. A separate optional once-daily update check reads GitHub release metadata. Both controls are disclosed at first launch.

The default ping endpoint is `https://forktty.dev/api/telemetry/ping`.

## Security model

ForkTTY assumes same-user local automation. The owner-only Unix socket is not a network service. Path ownership, request-size, terminal-read, argv validation, worktree boundary, and safe configuration-write checks remain enforced.

Provider credentials stay with the agent CLI. External MCP credentials and configuration stay with the MCP client or server. Hook setup changes only ForkTTY-managed entries and supports dry-run inspection.

## Troubleshooting

```sh
forktty doctor
forktty --json doctor
forktty capabilities
```

- If socket commands fail, launch ForkTTY or set an absolute `FORKTTY_SOCKET_PATH`.
- Corrupt config or session files are quarantined and replaced with safe defaults.
- If hook metadata is missing or stale, inspect `forktty hooks setup --dry-run` before applying setup again.
- For bug reports, include distro, desktop environment, install method, reproduction steps, and relevant doctor output.

## Current direction

The current unreleased simplification removes the task router, provider selection, team/workflow state, workflow feed, orchestration rail, Team sidebar section, approval orchestration, built-in MCP bridge, managed skill installer, and automatic hook refresh. It preserves the terminal workspace core: Ghostty rendering, workspace sidebar, tabs, splits, keyboard navigation, drag and drop, notifications, layout restore, command palette, worktrees, generic socket automation, and optional manual lifecycle hooks.

The design decision follows a comparison with cmux: keep the terminal workspace deep and let external tools own provider-specific coordination. See the repository's `docs/cmux-architecture-review.md` for the evidence and tradeoffs.

## Sources

- [Docs wiki](https://forktty.dev/docs)
- [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)
- [Alternatives](https://forktty.dev/alternatives)
- [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)
- [Agent lifecycle contract](https://raw.githubusercontent.com/Lucenx9/forktty/main/docs/agents.md)
- [Socket reference](https://raw.githubusercontent.com/Lucenx9/forktty/main/docs/socket-api.md)
- [Hook guide](https://raw.githubusercontent.com/Lucenx9/forktty/main/hooks/README.md)
- [cmux architecture review](https://raw.githubusercontent.com/Lucenx9/forktty/main/docs/cmux-architecture-review.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)
- [GitHub repository](https://github.com/Lucenx9/forktty)
- [Releases](https://github.com/Lucenx9/forktty/releases)