scgopi/GraphCode

Website · Download .dmg · All releases · Shortcuts

You can run one coding-agent session in a terminal. GraphCode lets you run ten — connected, unattended, and still yours to attach to and correct mid-run. Each node is a unit of work inside a real CLI coding-agent session: 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 asks which agent is on either end — a Codex loop hands off to a Claude Code loop that messages a Copilot one. They are live terminals, not headless jobs.

Graph Engineering, simplified → — the mental model, then the machinery.

Every loop type is "an agent runs repeatedly" — they differ in what you stop doing:

Two design choices explain most of the rest:

• GraphCode schedules nothing. A time-based loop's recurrence lives inside its session, written into the prompt with the agent's own /loop skill; the daemon only keeps the session alive. That is what makes a running loop something you can attach to and correct, rather than a job that already finished somewhere. Codex, OpenCode and pi have no such skill, so a time-based loop on them needs the experimental Daemon heartbeat switched on in Settings.
• Sessions outlive everything. Each loop's terminal is a zmx session, so it survives quitting the app and rebooting — the backend's session ID is persisted, so relaunching resumes the conversation with --resume rather than starting a duplicate.

Requires macOS 15+ on Apple Silicon (arm64), with at least one agent CLI on your PATH — claude, copilot, codex, opencode, or pi. GraphCode launches whichever one a loop names; it bundles none of them.

brew install --cask scgopi/graphcode/graphcode

Or drag GraphCode to Applications from the latest .dmg. Releases are Developer ID signed and notarized.

If GraphCode runs a loop you'd otherwise have babysat, a ⭐ on the repo helps other people find it.

1. Add a project — the sidebar's ⊕ menu: a local folder, a clone from a URL, or a remote repository over SSH (key auth and zmx on the server; loops run there while this Mac steers them).
2. Create a loop — ⊕ on the canvas. Write the prompt, pick the agent it runs as (Claude Code unless you change Settings ▸ New loops use), and hit Create; the type chooser explains what each kind hands off, and a goal's done check has a Test button that runs it as the daemon will. From a shell, graphcode node create takes the same choice as --backend claudeCode | copilotCLI | codex | openCode | pi; a loop that creates children without naming one hands them its own.
3. Open it — click the node for that loop's terminal workspace: tabs, splits, ⌘K to jump to any loop, ⌘⇧R to walk the ones asking for you (shortcuts). You attach to the live session.
4. Connect loops — drag between nodes. An edge is a hand-off by default (fires when the source resolves); it can also be a message or a spawn, with a condition and a cycle guard. The agents on either end can differ.

State lives in ~/.graphcode/ — graphs, recents, layouts, the daemon socket and logs, and the installed binaries. Nothing is ever written inside a project folder you open.

Copilot loops follow the CLI's own version selection. To hold a specific published version, install it on every machine that runs Copilot, including remote hosts:

npm install -g @github/copilot@1.0.84-5
copilot --prefer-version 1.0.84-5 --version

Then set Settings ▸ Preferred versions ▸ Copilot CLI to that version. GraphCode passes it to new and resumed Copilot sessions, locally and over SSH, and to Copilot title and summary requests; sessions already running are unaffected. Without the app, set "copilotPreferredVersion": "1.0.84-5" in ~/.graphcode/settings.json — it is read on each launch, so no daemon restart is needed.

Clear the field to return to the CLI's own selection. GraphCode installs nothing itself, so a version you have not installed on the host will not be there when a loop launches.

File ▸ Workspace ▸ New Workspace… opens a second GraphCode with projects, loops and terminal sessions entirely its own — for keeping unrelated lines of work apart when one sidebar of loops has grown past what you can monitor. It is a separate window with its own Dock tile, so it can live on a second screen.

A workspace is a directory: ~/.graphcode-<name>, beside the default ~/.graphcode, with its own graphs and its own graphcoded. Nothing is shared between them — a loop in one is invisible in the other — and the switcher at the foot of the sidebar says which one you are in. The CLI follows the same variable the app sets: GRAPHCODE_SUPPORT_DIR=~/.graphcode-work graphcode status <project>.

⌥⌘1 … ⌥⌘9 switch between them and ⌘** steps to the next one (**⌘⇧ back), both in the order the workspaces were created; ⌥⌘N makes a new one. Rename Workspace moves its folder, taking its projects and loops with it; Delete Workspace ends that workspace's terminal sessions, stops its daemon, and moves its folder to the Trash. Neither is offered for the default workspace or for whichever one you are in.

Not to be confused with a loop's terminal workspace, which is the tabs and splits inside one loop. A workspace holds projects; a terminal workspace holds panes.

Windows contributors should start with the Windows contributor quick start. It uses the pinned Windows toolchains and a checkout-owned profile for the production daemon and shell; the Windows port remains a preview rather than a shipping-platform claim.

Needs mise (Xcode, tuist, swiftlint, zig come through it) and the submodules. Start with make doctor — it checks every prerequisite and prints the fix for anything missing.

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, optionally copy .env.example to .env.local, choose your own bundle-ID prefix, then run:

make dev-run-app

This build is ad-hoc signed for the current Mac and keeps its app identity and state separate from the installed release. No production signing profile is needed.

Inspired by Supacode — same spine of daemon-kept terminal sessions; its unit is the worktree, GraphCode's is the graph of loops. Built on Ghostty and zmx.

The app and the daemon are under the Functional Source License v1.1 with an MIT future license (FSL-1.1-MIT): use it, change it, self-host it, redistribute it — the one thing it does not permit is shipping a competing commercial product built from it, and every release converts to plain MIT two years after it goes out. GraphcodeKit/ and graphcode-cli/ stay MIT. Contributions come in under the Developer Certificate of Origin — add Signed-off-by with git commit -s.