cocofhu/grasp: Grasp helps you manage multiple projects and parallel coding agents in one visual workflow, so humans can understand faster and ship more.

Coding agent workflow orchestration with human approval gates in one workspace

English | 简体中文

Website · Quick start · Features · Architecture · Docs · Contributing

This release requires a fresh install: an empty database and an empty data directory.

Why Grasp

Over the past two years I built 150+ personal projects with coding agents, and two problems kept slowing me down:

1. Switching across projects is expensive: bouncing between IDEs makes it hard to track which project is running and where it stopped.
2. Parallel agent output is hard to read: models dump long walls of text, burying the actual changes and open questions in chat logs.

Supported agent backends: Cursor, Claude Code, CodeBuddy, Trae, OpenCode, and Codex. Each agent step runs inside an isolated Docker sandbox.

Demo

https://github.com/user-attachments/assets/47728d1f-54a1-485e-967e-28d8c716ed36

Features

• FSM workflow canvas: Six node types (agent, input, output, assign, branch, human gate), with explicit success, fail, and rollback edges, when guards, and checkpoints.
• Visual requirement clarification: Start a task from the home page with one sentence. A clarify agent aligns on scope through multi-turn Q&A and produces a structured spec, execution plan, and optional page.html preview.
• Human gates and unified inbox: Runs pause at gate nodes for approval or rejection from a single inbox; one-time share links let reviewers without an account inspect and approve.
• Structured artifacts (Artifact MCP): Artifacts are isolated per run. Nodes must submit their declared required artifacts before the engine transitions forward.
• Docker sandboxes and Git delivery: Agents run in isolated containers and can push branches or open PRs / MRs via gh, glab, or SSH.
• Observability: State transition timeline, node handoff notes, sandbox logs, live desktop preview (noVNC), and token / cost tracking by workflow, source, and model.

Workflow canvas	Artifact review
Agent Studio	Token usage

Quick start

Requirements: a Linux host with Git, Docker, and Docker Compose (services use host networking).

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

This pulls the published GHCR images without building locally. Once started:

• Web UI / API:
• API health:
• Gateway health:

Running your first workflow

1. Sign in with the demo account. Opening the workspace for the first time launches the setup wizard.
2. In Settings → Credentials, save a tool platform credential or a model service key with a preset or custom API base. In the Models tab, save a named combination of coding tool, credential and selected model, then choose that configuration in Agent Studio. Supported tools are Cursor, Claude Code, CodeBuddy, Trae, OpenCode, Codex and DeepSeek Harness; third-party protocols are filtered by tool support. Codex accepts a ChatGPT ~/.codex/auth.json login file or a Responses connection. Git credentials are optional. Finishing the first-time setup wizard creates the default agent team and publishes the default workflow (Clarify → Implement → Test & review).
3. Start a run from the home page with a single prompt, or open the canvas to customize nodes and success / fail / rollback edges.
4. When a run pauses at a human gate, review the spec, preview page, or code diff from the inbox to approve or reject.

Common commands

./start.sh logs        # follow logs
./start.sh gw-logs     # gateway logs only
./start.sh restart     # restart in background
./start.sh down        # stop and remove containers
./start.sh pull        # update service images and pre-pull sandbox runtime
./start.sh dev -d      # run source stack (Go + Vite HMR)

Image tags and digests can be overridden in .env; see .env.example.

Bundled role agents

agents/ includes five prebuilt roles: PMAgent, ClarifyAgent, ImplementAgent, TestReviewAgent, and DeliverAgent.

./agents/pack.sh               # pack all into agents/dist/
./agents/pack.sh ClarifyAgent  # pack a single role

Import the generated ZIPs in Agent Studio. ZIP import currently defaults acpBackend to cursor; update the backend in the UI after importing if needed.

Architecture

flowchart LR
    UI["Web UI<br/>Vue 3 + Vue Flow"] <--> S["Go server<br/>FSM engine · API · MCP · SQLite"]
    S <--> G["sandbox-gateway<br/>sandbox control plane"]
    G --> B["Docker sandbox<br/>ACP bridge + agent CLI"]
    B -- "artifacts (Artifact MCP)" --> S

Typical delivery workflow (with failure and rollback paths defined on the same canvas):

Clarify → Research → Human gate
        → Plan → Implement → Test → Review
        → Human confirm → PR / MR

Repository layout:

• web/ — Vue 3 + Vue Flow frontend (workflow canvas, home clarification, run details, inbox, Agent Studio)
• server/ — Go backend (FSM engine, HTTP API, SQLite, Artifact MCP, scheduler, audit)
• sandbox-gateway/ — Sandbox lifecycle control plane (gateway/) and universal sandbox image/runtime (sandbox/)
• agents/ — Importable role agent workspaces
• docs/ — Project website and bilingual help docs

Deployment notes

• Store API keys and Git credentials only in the workspace credentials settings; never commit them to the repository.
• Pin images by digest in production; see Release images and smoke.
• Preserve the original Host header behind a reverse proxy (e.g. nginx proxy_set_header Host $host); temporary approval share links are generated from it. See SECURITY.md.
• SQLite (./.localdata/db) and attachments (./.localdata/app-data) are mounted separately. Back them up and clean them up together so existing runs do not end up with broken blob: references.

Docs

• Concepts · Quick start
• Configuration · Server · Gateway contract
• Security · Support · Changelog

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md, AGENTS.md, and the Code of Conduct for module lint, test, and E2E commands before submitting changes.

License

MIT © 2026 cocofhu