README
¶
graith
Run a fleet of AI coding agents in parallel — each in its own git worktree, each in a session that outlives your terminal.
graith is a terminal multiplexer built for AI coding agents (Claude, Codex, OpenCode, Cursor, Agy). Spin up an agent per task, let them work isolated and unattended, and jump between them with a tmux-style prefix key. A long-lived daemon owns the sessions, so closing your terminal — or losing your SSH connection — doesn't stop the work.
graith (Scots) — noun: equipment, tools, gear for a specific trade. verb: to make ready, prepare, equip. Your agents, graithed and ready to work.
📖 Documentation — full guide, CLI reference, configuration, and architecture.
Why
Running several agents at once shouldn't mean juggling terminal tabs and stepping on your own branches. graith gives you:
- Isolation — every agent gets its own git worktree and branch, so parallel work never collides
- Persistence — a daemon owns the PTYs; sessions survive terminal closures, daemon restarts, and SSH drops
- Switching — hop between agents instantly with a tmux-style prefix key
- Visibility — see every session at a glance, with a "Needs Attention" view that surfaces what's blocked or waiting
- Coordination — agents message each other over pub/sub, and you drive them remotely with
type,logs, and a live dashboard
It owns the PTY, manages the worktrees, and otherwise gets out of your way.
Install
With Homebrew:
brew install d0ugal/tap/graith
For apt, dnf, prebuilt binaries, Go, and source installs, see the installation guide. Then follow the getting started guide to create your first session.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
covreport
command
Command covreport renders a per-file Go coverage table (Markdown) for the PR coverage comment.
|
Command covreport renders a per-file Go coverage table (Markdown) for the PR coverage comment. |
|
graith
command
cmd/graith/main.go
|
cmd/graith/main.go |
|
internal
|
|
|
agent/transcript
Package transcript reads an AI coding agent's on-disk conversation transcript and renders it to a neutral, agent-agnostic Markdown document.
|
Package transcript reads an AI coding agent's on-disk conversation transcript and renders it to a neutral, agent-agnostic Markdown document. |
|
approvals
Package approvals provides pluggable backends that make (or decline to make) automated tool-approval decisions on behalf of the graith daemon.
|
Package approvals provides pluggable backends that make (or decline to make) automated tool-approval decisions on behalf of the graith daemon. |
|
approvals/localmost
Package localmost is a clean-room, behaviourally-compatible reimplementation of the federicotdn/localmost rule engine.
|
Package localmost is a clean-room, behaviourally-compatible reimplementation of the federicotdn/localmost rule engine. |
|
atomicfile
Package atomicfile provides a crash-safe file write primitive: write to a temp file in the target directory, fsync it, atomically rename it into place, then fsync the parent directory.
|
Package atomicfile provides a crash-safe file write primitive: write to a temp file in the target directory, fsync it, atomically rename it into place, then fsync the parent directory. |
|
capabilities
Package capabilities is the source of truth for which graith capabilities each frontend surface (CLI, iOS, macOS) supports.
|
Package capabilities is the source of truth for which graith capabilities each frontend surface (CLI, iOS, macOS) supports. |
|
covreport
Package covreport turns Go coverage profiles into a per-file Markdown table for the PR coverage comment (see .github/workflows/coverage.yml).
|
Package covreport turns Go coverage profiles into a per-file Markdown table for the PR coverage comment (see .github/workflows/coverage.yml). |
|
cronx
Package cronx is graith's single, owned abstraction for cron schedules.
|
Package cronx is graith's single, owned abstraction for cron schedules. |
|
headless
Package headless drives a Claude Code agent in headless stream-json mode (`claude -p --output-format stream-json`) instead of an interactive PTY.
|
Package headless drives a Claude Code agent in headless stream-json mode (`claude -p --output-format stream-json`) instead of an interactive PTY. |
|
ignore
Package ignore provides a small, graith-owned interface over a Git-compatible gitignore matcher.
|
Package ignore provides a small, graith-owned interface over a Git-compatible gitignore matcher. |
|
sandbox
Package sandbox wraps agent processes in an OS-level sandbox.
|
Package sandbox wraps agent processes in an OS-level sandbox. |
|
scenariofile
Package scenariofile parses graith scenario TOML files.
|
Package scenariofile parses graith scenario TOML files. |
|
testutil
Package testutil provides shared helpers for graith's Go tests.
|
Package testutil provides shared helpers for graith's Go tests. |
|
tools
Package tools resolves the external executables graith shells out to: git, gh, gcx, the notification shell, osascript, ps, and lsof.
|
Package tools resolves the external executables graith shells out to: git, gh, gcx, the notification shell, osascript, ps, and lsof. |
|
version
Package version holds build-time version information injected at link time.
|
Package version holds build-time version information injected at link time. |
Click to show internal directories.
Click to hide internal directories.