cocofhu/grasp: a visual FSM canvas for parallel coding agents

The two problems Grasp was written against

The README opens with a personal claim rather than a market one: the author shipped over 150 side projects and kept hitting two obstacles. Multi-project switching is expensive, because run state and context live in separate IDEs. Parallel agent work is hard to read, because models emit long walls of text and the signal is buried.

Grasp is aimed at the second problem more than the first. Its answer is not a better chat window but a canvas where agent work becomes nodes with success, fail and rollback edges, plus a Visual clarify step that turns a one-sentence requirement into a spec, a plan and an optional page.html. That framing tells you who it is for: someone running several agents at once who wants review to be a reading task with a fixed shape, not an archaeology exercise. If you run one agent on one repository and read its diffs directly, the canvas adds a layer you do not need.

How the canvas, the Go engine and the sandbox gateway fit together

The architecture diagram in the README shows three tiers. A Vue 3 front end renders the FSM canvas using Vue Flow. A Go backend holds the engine, the API and an MCP endpoint. A sandbox-gateway acts as the control plane for sandboxes.

The docker-compose.yml comments fill in a detail the diagram does not: the backend no longer talks to Docker directly. Sandboxes are created and managed entirely by the gateway (the comment points at server/internal/sandbox/gateway.go). That split is why the compose file runs the server with network_mode: host. Sandbox ports for ACP, code-server and SSH are published by the gateway onto the host loopback, and the backend has to reach those loopback ports, so it shares the host network. The same comment states this is only verified on Linux hosts, and that Mac and Windows Docker Desktop do not support true host networking.

A second constraint follows from the same design. ConfigHome, which holds rules, skills and mcp.json, is a host directory bind-mounted into sandboxes by the gateway's Docker driver. The comment is explicit that the path must be identical inside and outside the backend container, because the host dockerd resolves the mount source on the host filesystem. That is why GRASP_SANDBOX_WORK_DIR is mounted onto itself in the compose file. Move the repository and you must move that variable with it.

Installing Grasp with ./start.sh and publishing a first run

The README lists three requirements: a Linux host, Git, and Docker with Docker Compose. The default path pulls published GHCR images and does not build them locally, so the clone and start sequence is short. The first command copies .env.example to .env on first run, per the comment at the top of that file.

git clone https://github.com/cocofhu/grasp.git
cd grasp
./start.sh -d

After the stack is up, the README gives four endpoints to check. The UI and API are on port 8080, the API health endpoint is at /api/health, the gateway health endpoint is on port 8899 at /healthz, and the local demo login is admin with the password demo1234.

The sandbox runtime is pulled on demand the first time you create a sandbox, and the Inbox or run page shows the pull. To avoid that wait, the README offers a warm-up command.

./start.sh pull

Other subcommands listed in the README are logs to follow output, down to stop the stack, and dev -d for a source stack with Go plus Vite HMR. Image tags and digests are overridden in .env. Note what the README says about a fresh installation: it starts with an empty project and does not create a sample pipeline. You build the first workflow yourself. Create an agent in Agent Studio, pick one of cursor, claude_code, codebuddy, trae or opencode, and configure the matching API key. Then open the canvas, connect a Grasp node after start followed by Visual, gate and implement nodes, and draw the success, fail and rollback edges. Mark checkpoints where a retry should re-enter. Publish, then start a run, or launch from Home with a single sentence.

Human gates, artifact isolation and the cost of an empty first canvas

The capability table maps each feature to its FSM primitive. Human gates become inbox items, run detail views and shareable temporary links. Parallel runs mean many machines at once with approvals from one inbox. The Artifact MCP is isolated per run, and required outputs gate transitions, so a run cannot advance past a node whose declared artifacts are missing. Git delivery happens through gh, glab or SSH inside the sandbox. Observability covers the timeline, sandbox logs, artifacts and token usage.

The repository ships role packs named Clarify, Visual, Research, Proposal, Plan, Implement, Test, Preview and Review. The README says to run agents/pack.sh and import them in Agent Studio. That script is the intended distribution mechanism for those roles, and the README does not describe an alternative import path.

The honest limitation is the empty start. Because no sample pipeline is created, the first hour is canvas modelling, not agent running. You have to decide where your gates belong and which failures should roll back rather than retry. Teams expecting a template to edit will find none. The other constraint is environmental: the compose comments tie the supported setup to a Linux host with host networking, and the README's requirements section says the same.

Where Grasp is the wrong tool

If your work is a single repository with a single agent session, Grasp inserts a modelling step between you and the diff. The FSM only earns its keep when runs are parallel or when several people approve work asynchronously.

The second mismatch is platform. The docker-compose.yml comment states that Mac and Windows Docker Desktop do not support true host networking, and that you should switch back to bridge networking with port mappings and adjust paths such as GRASP_SANDBOX_WORK_DIR accordingly. That is a documented workaround, not a supported default, and the README's requirements section asks for a Linux host. If your team is on macOS laptops, budget for that adaptation before you plan a rollout.

The third is the demo credentials. The .env.example file carries SANDBOX_GATEWAY_API_KEY=grasp-local-demo and calls it a local-demo default, with the instruction to change it before exposing the stack beyond loopback. The same file warns not to put bcrypt hashes in .env because the dollar signs are mangled by the shell and compose. Treat any deployment reachable from outside the host as requiring both changes first.

How Grasp differs from running the agent CLIs directly

The obvious alternative is the agent backends themselves. Cursor, Claude Code, CodeBuddy, trae and opencode each provide a session where you read output and approve actions inline. Grasp does not replace those CLIs; the .env.example comment says the universal sandbox image has five CLIs preinstalled and the runtime AGENT_PROVIDER variable picks the live CLI. Grasp is the layer above.

The difference in approach is where state lives. With the CLIs directly, the conversation is the state, and it disappears when the session ends. With Grasp, state is the FSM: nodes, transitions, checkpoints and per-run artifact stores. That is what makes an inbox of pending approvals possible across parallel runs, and it is also what makes the initial setup heavier. A second difference is cost visibility. The README lists token analytics as a capability, tracking usage and cost distribution across projects and models, which the individual CLI sessions do not aggregate.

If you want a single agent loop with no orchestration layer, the CLIs are simpler and you should stay with them. If you want to see six runs at once and approve them from one queue, that is the gap Grasp fills.

Maintenance, licensing and upgrade mechanics

The repository is not archived, and the last push was on 2026-09-17. The most recent release listed is v1.0.0 from 2026-09-13, preceded by v0.5.4 and v0.5.2 on the same day. The .env.example comment notes that tag 1.0.1 matches the current public packages, and that you should prefer @sha256:... digests for immutable releases or for ./release-smoke.sh. That is the upgrade story: image tags or digests in .env, refreshed by ./start.sh pull, with a smoke script available for pinned releases.

The project is MIT licensed, and package.json declares the same for the repository root. The practical implication is that you can fork and redistribute under the licence terms, but the .env.example reminder about changing SANDBOX_GATEWAY_API_KEY before exposing the stack beyond loopback is an operational matter the licence does not cover. The README does not document a rollback procedure for a failed upgrade, so pinning a digest before you pull is the only mechanism the material actually describes.

Editorial conclusion

Adopt Grasp if you already run several agent backends and lose time re-reading their output: the canvas, gates and per-run artifact isolation are the parts that pay off, and the GHCR path means no local build. Skip it if you work on one project with one agent, or if your machine is macOS or Windows, since the compose file states host networking is only verified on Linux hosts. Before committing, verify three things: that ./start.sh -d brings up the UI on port 8080 and the gateway health endpoint on 8899, that your chosen acpBackend has an API key configured in Agent Studio, and that you have replaced the SANDBOX_GATEWAY_API_KEY value grasp-local-demo before the stack leaves loopback.

Frequently asked questions

Official sources

1. cocofhu/grasp on GitHub
2. Issues
3. License: MIT
4. README
5. Releases