Grasp

Over the past two years, as large models got stronger, I explored widely and shipped 150+ personal projects. Two problems kept getting in the way:

1. Multi-project switching is expensive — bouncing between IDEs, with run state and context hard to keep straight;
2. Parallel agent work is hard to read — models dump long walls of text, burying what actually matters, so understanding costs a lot of time.

Website · Quick start · Contributing · Configuration · Gateway

English | 简体中文

One sentence → Grasp (clarify / plan / page.html) → Human gate → build

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

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

./start.sh logs          # follow logs
./start.sh down          # stop the stack
./start.sh pull          # refresh GHCR images
./start.sh dev -d        # source stack: Go + Vite HMR

Override image tags or digests in .env; see .env.example.

Build your first workflow

1. Sign in with the local demo account. A fresh installation starts with an empty project and does not create a sample pipeline.
2. Create an agent in Agent Studio, select cursor, claude_code, codebuddy, trae, or opencode, and configure the matching API key.
3. Open the canvas: connect a Grasp node after start, then Visual / gate / implement nodes. Draw success, fail, and rollback — mark checkpoints where a retry should re-enter.
4. Publish and start a run (or launch from Home in one sentence). Watch the state trace, page.html preview, and inbox items waiting at gates.

Architecture

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│ Vue 3 + Vue Flow │────▶│ Go Backend       │────▶│ sandbox-gateway  │
│ FSM canvas       │◀────│ engine + API+MCP │◀────│ control plane    │
└──────────────────┘     └────────┬─────────┘     └────────┬─────────┘
                                  │                        │
                                  │                        ▼
                                  │               ┌──────────────────┐
                                  └──────────────▶│ Docker sandboxes │
                                    artifacts     │ ACP backends     │
                                                  └──────────────────┘

• web/ — Vue 3 + Vue Flow canvas, Home clarify, run details, inbox, and Agent Studio.
• server/ — Go FSM engine, API, SQLite, artifact MCP, scheduling, and audit.
• sandbox-gateway/gateway/ — sandbox lifecycle control plane.
• sandbox-gateway/sandbox/ — universal sandbox image and ACP bridge.
• agents/ — importable role-agent workspaces.
• docs/ — project site and bilingual help content.

Development and quality

Development requirements: Go, Node.js, and Docker Compose; sandbox execution requires Linux.

./start.sh dev -d

Module-specific lint, test, coverage, and E2E commands are documented in AGENTS.md and CONTRIBUTING.md. The security workflow runs CodeQL, web npm audit, and gitleaks on pushes and pull requests.

Deployment and security notes

• The default account is for local demos only. Configure your own authentication users before any shared or production deployment.
• Keep ACP API keys and Git credentials in project or Agent env; never commit them.
• Pin production images by digest; see Release images and smoke.
• Grasp is still beta software. Perform your own security review, backups, and capacity validation before production use.
• Reverse proxy Host: temporary approval share links mint from this request's Host (never client X-Forwarded-Host). Preserve the browser Host (for example nginx proxy_set_header Host $host) and forward X-Forwarded-Proto when TLS terminates upstream. See SECURITY.md.
• DB ↔ attachment lifecycle: release Compose separates SQLite (./.localdata/db) from app-data/blobs (./.localdata/app-data). Backup and clean them as a pair (and include a custom GRASP_BLOBS_ROOT if set); otherwise Run inputs can keep blob: refs while GET /api/blobs/:id returns 404. Historical orphans are shown as permanent UI placeholders only—this release does not ship an orphan scanner. See Quick start · Database and attachments.

Documentation

• Core concepts
• Quick start
• Full configuration
• Gateway contract
• Contributing guide
• Security policy
• Support

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md, AGENTS.md, and CODE_OF_CONDUCT.md before contributing.

License

MIT © 2026 cocofhu

Star History