Quickstart

Install, scaffold a project, run your first plan

The fastest path

Grab a binary, scaffold a project, and hand the setup to your coding agent. A skill walks the agent through wiring a provider, adding tools, and drafting a first plan against your own data — then you review it in the workbench and run it. Prefer to do it by hand? The manual path is right below.

1. Install graph

   Grab the latest release binary — macOS (arm64) or Linux (x86_64). Each release publishes version-pinned tarballs with SHA-256 checksums:

   macOS (arm64)

   Download graph-v0.11.0-macos-arm64.tar.gz

   Linux (x86_64)

   Download graph-v0.11.0-linux-x86_64.tar.gz

2. Scaffold a project

   From your project directory:

   graph config init
   

   This writes a commented starter to ./.graph/config.toml. That directory is where a project’s config, plans, and tools live — checked into the repo, reviewed like any other code.

3. Let your agent finish the setup

   Install the setup skill, then ask your coding agent to run it:

   npx skills add tylerdavis/graph
   

   This installs /graph-project-setup for Claude Code, Cursor, Codex, and most other agents. Point your agent at it — “set up graph in this project” — and it asks a few questions, then picks a provider and models, finds and connects the MCP servers or tools you want, scaffolds a first plan against your real data, and runs it end to end. It reads the live docs and example plans as it goes, so the result matches the current release.

   The same npx skills add command installs two more: /graph-plan-authoring, which teaches the agent to build and repair plans with the authoring commands, and /graph-github-actions-setup, which scaffolds a merge gate or PR reviewer as a plan — see CI checks for the worked example.

4. Open it in the workbench

   Before you commit the plan, open it in the workbench — a dual-pane TUI for reviewing, tweaking, and test-running plans:

   graph workbench plan project_status   # alias: graph wb plan
   

   The plan renders as a flowchart on the right, an agent sits on the left. Read each step, v to validate, r to run it, or g to step through with a debugger that pauses on every tool call and shows the exact input and result. Ask the agent to change a step in plain English — “add a step that filters to open issues” — and watch the draft update and re-validate. Ctrl+S writes it back to ./.graph/plans/.

   

   A loaded plan in the workbench: chat agent left, step tree and detail right.

5. Run your first plan

   Once it’s right, run it headless — the same steps in the same order every time, for 0–1 LLM calls no matter how many steps it has:

   graph plan list
   graph plan run project_status '{"project":"New Relic"}'
   

   The deliverable goes to stdout; tool activity streams dimmed to stderr. This is the form you schedule on cron or wire into CI.

Manual setup

Not using an agent? The whole path is a few commands.

1. Write a minimal config

   A working config is a provider, a default model, and whatever tools your plan needs. Here it’s one MCP server:

   [providers.anthropic]
   type = "anthropic"
   api_key = "${ANTHROPIC_API_KEY}"   # read from your environment at load time
   
   [models]
   default = { provider = "anthropic", model = "claude-sonnet-5" }
   
   [mcp.linear]
   url = "https://mcp.linear.app/mcp"
   headers = { Authorization = "Bearer ${LINEAR_API_KEY}" }
   

   ${VAR} references fail loudly when the variable is unset — misconfigured secrets never silently send empty strings. For provider and MCP entries the failure comes at first use rather than at load, naming the variable, so the rest of graph keeps working without the secret.

2. Check your tools are live

   graph mcp test linear
   # ok: 'linear' initialized in 1.7s — 57 tools (0 declare output schemas)
   
   graph tools list
   
3. Probe the tools you'll build on

   Before writing a step, see each tool’s input schema and actual output shape:

   graph tools show linear__list_issues
   graph tools test linear__list_issues '{"priority":1,"limit":5}'
   

   Every probe also teaches graph what the tool returns (the shape cache), so the references you write next are grounded in real output — and the workbench’s drafting agent gets smarter too.

4. Build the plan in the workbench

   Open a blank draft and describe the goal — the agent drafts the plan into the side pane, where you inspect, validate, and test-run it:

   graph workbench plan     # alias: graph wb plan
   

   Prefer to write the YAML yourself? Authoring plans builds one from scratch. Either way, Ctrl+S (or a save in the workbench) writes it to ./.graph/plans/.

5. Run it headless

   graph plan run project_status '{"project":"New Relic"}'
   

   Same contract as the fast path: the deliverable on stdout, progress on stderr, and a file you can commit, schedule, and wire into CI.

Where things live

Path	What
./.graph/config.toml	project config, deep-merged over global
~/.config/graph/config.toml	optional global config (providers, models, MCP servers)
./.graph/plans/	your plan documents (~/.config/graph/plans/ for global ones)
./.graph/tools/	your user-defined tools (~/.config/graph/tools/ for global ones)
~/.local/share/graph/	threads and learned tool shapes, as plain files

What’s next

• Core concepts — plans, the tool catalog, the shape cache, and what a run costs.
• Author your first plan — freeze a workflow into a repeatable file.
• Add your own tools — wrap a CLI, a query, or an inline LLM prompt.
• Wire it into CI — exit codes, JSON output, ephemeral storage.