GraphCode

What does this agent do, and when should you use it?

GraphCode is a macOS app that arranges real CLI coding-agent sessions into a graph: each node is a loop, a unit of work inside one session run by Claude Code, GitHub Copilot CLI, Codex, OpenCode or pi, chosen per loop; each edge is a hand-off, message or spawn between them, and an edge never needs to know which agent sits on either end. Loops come in four types — turn-based, goal-based, time-based and composite — differing in what you stop doing by hand: the check, the stop condition, the trigger, or the prompt. GraphCode schedules nothing itself: a time-based loop's cadence lives inside its session as the agent's own `/loop` skill, while the `graphcoded` daemon only fires hand-off edges, polls goal predicates and keeps sessions alive. Every loop's terminal is a `zmx` session, so it survives quitting the app and rebooting, and relaunching resumes the conversation with `--resume` rather than starting a duplicate — which is what keeps a running loop attachable and correctable instead of a job that already finished. State lives in `~/.graphcode/` and nothing is written inside a project folder you open; separate Workspaces under `~/.graphcode-<name>` are entirely isolated.

GraphCode ships as four moving parts. The UI, graphcode.app, gives you the project sidebar, the graph canvas and a per-loop terminal workspace with tabs, splits, ⌘K to jump to any loop and ⌘⇧R to walk the loops asking for you. The background daemon graphcoded (a launchd agent) owns every project's graph, fires hand-off edges, polls goal predicates and keeps unattended sessions alive whether or not the app is open. The graphcode CLI drives the same daemon — graphcode projects, graphcode status <project>, graphcode node create --backend claudeCode|copilotCLI|codex|openCode|pi, graphcode node send --follow-up, graphcode reap --dry-run. Underneath, the third-party zmx session daemon keeps each loop's PTY alive and GhosttyKit renders each surface. In practice: add a project (local folder, clone from URL, or a remote repository over SSH where loops run while this Mac steers them), create a loop on the canvas with its prompt and agent (Claude Code unless you change Settings ▸ New loops use), open the node to attach to that live session, then drag edges between nodes and set each edge as a hand-off (fires when the source resolves), a message or a spawn, optionally with a condition and cycle guard. A goal loop's done check can be a shell predicate, testable at creation time the way the daemon will run it. Copilot loops can be pinned to a published CLI version via Settings ▸ Preferred versions or "copilotPreferredVersion" in ~/.graphcode/settings.json, applied to new and resumed Copilot sessions plus title and summary requests.

1. You are pushing several independent lines of work in one repo (a refactor, a broken build, an issue queue) and want a canvas showing when one should hand off to another instead of ten terminal windows you babysit. You express each as a loop, connect them with edges and watch the graph.
2. You want 'fix the build' to run until it is actually fixed: create a goal-based loop whose done check is a shell predicate such as make test exiting 0, leave it unattended, and attach when you want to intervene. Turn-based loops fit refactors you want to eyeball turn by turn.
3. You need recurring work such as hourly issue triage: a time-based loop puts the cadence in the prompt with /loop 1h …, so the recurrence lives in the session rather than an external scheduler.
4. You are wiring a multi-step pipeline where steps depend on each other: a composite loop runs a sub-graph end to end, and one loop can spawn children that inherit its own agent unless they name another.
5. You work across machines and want loops running on a remote host over SSH (key auth and zmx on the server) while you steer them from this Mac.
6. You run unrelated lines of business side by side: separate Workspaces (⌥⌘1…⌥⌘9 to switch) keep their own graphs, loops and terminal sessions fully apart, each with its own Dock tile.

How do you install or deploy this agent?

Requirements: macOS 15+ on Apple Silicon (arm64), with at least one agent CLI on your PATH — claude, copilot, codex, opencode or pi. GraphCode bundles none of them.

Install with Homebrew:

brew install --cask scgopi/graphcode/graphcode

Or drag GraphCode into Applications from the latest .dmg (releases are Developer ID signed and notarized):

open https://github.com/scgopi/GraphCode/releases/latest/download/graphcode-macos-arm64.dmg

Building from source needs mise (Xcode, tuist, swiftlint and zig come through it) plus the submodules:

git submodule update --init --recursive
make doctor
make third-party     # builds zmx and GhosttyKit (zig)
make install-zmx install-cli daemon-install
make run-app
make test            # unit tests
make check           # swiftlint + swift-format, both strict

To run a local build beside an installed release, copy .env.example to .env.local and choose your own bundle-ID prefix:

make dev-run-app

How do you use this agent?

Start by adding a project, then create a loop, then open and connect it.

In the app: the sidebar's ⊕ menu adds a project (local folder, clone from a URL, or a remote repo over SSH); ⊕ on the canvas creates a loop where you write the prompt and pick the agent that runs it (Claude Code unless you change Settings ▸ New loops use); clicking a node opens that loop's terminal workspace, with ⌘K to jump to any loop and ⌘⇧R to walk the ones asking for you; dragging between nodes creates an edge.

The same daemon is drivable from a shell:

graphcode projects
graphcode --help
graphcode status <project>
graphcode node create --backend claudeCode
graphcode node send --follow-up
graphcode reap --dry-run

To pin a Copilot CLI version, first install that version on every machine that runs Copilot, including remote hosts:

npm install -g @github/[email protected]
copilot --prefer-version 1.0.84-5 --version

Then set Settings ▸ Preferred versions ▸ Copilot CLI, or write the settings file directly (read on each launch, so no daemon restart):

{
  "copilotPreferredVersion": "1.0.84-5"
}

Switch between workspaces with ⌥⌘1…⌥⌘9, step with ⌘ / ⌘⇧ and create one with ⌥⌘N; from the CLI, follow the same variable the app sets:

GRAPHCODE_SUPPORT_DIR=~/.graphcode-work graphcode status <project>

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

FAQ