cocofhu 开源多项目多智能体编排平台 Grasp 1.0.0

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.

So I built Grasp: one platform for all your projects, and visual requirement clarification that turns agent verbosity into something you can grasp at a glance — raising human throughput. It also plugs into multiple agent backends, such as Cursor, CodeBuddy, and Claude Code.

Website · Quick start · Contributing · Configuration · Gateway

English | 简体中文

Demo

grasp-demo.mp4

Screenshots

_{Orchestrate multi-project, multi-agent development on one canvas.}

_{Turn agent output into structured artifacts that are quick to review.}

_{Manage projects, agent backends, and run configuration in one platform.}

_{Track token usage and cost distribution across projects and models.}

Core capabilities

The repository includes Clarify, Visual, Research, Plan, Implement, Test, Preview, and Review role packs. Run agents/pack.sh and import them in Agent Studio.

Typical workflow

Short pre-dev loop:

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

Fuller delivery machine:

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

Draw the fail and rollback edges on the same canvas. The next failure should follow a path you already designed.

Quick start

Requirements

• Linux host
• Git
• Docker and Docker Compose

Start

The default path pulls published GHCR images and does not build them locally:

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

Open:

• UI / API: http://localhost:8080
• API health: http://localhost:8080/api/health
• Gateway health: http://localhost:8899/healthz
• Local demo login: admin / demo1234

The sandbox runtime is pulled on demand when you first create a sandbox (Inbox / run page show pull loading). Warm it with ./start.sh pull.

Useful commands:

./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 workflow.
2. Open the project credential settings, select cursor, claude_code, codebuddy, trae, opencode, or codex, and save the matching API key there. Codex uses a ChatGPT login file (~/.codex/auth.json), not an API key. Agent env values remain available as a fallback.
3. Open the canvas: start from the default template (Clarify → Implement → Test & review), or drag Agents and gates from the palette. 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.

See server/README.md for backend authentication, project credential settings, and environment-variable fallback.

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.

Configuration precedence is explicit environment variables > mounted config file > defaults. See server/CONFIGURATION.md for all options and GATEWAY.md for the gateway contract.

Runtime credentials (ACP API keys, Git tokens and SSH keys) come only from the project credential UI; Agent env, project shared env and sandbox.env reject secret keys, and the server's own process environment is never injected into sandboxes. The precedence above applies to platform service configuration, not runtime credentials.

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.
• Manage ACP API keys and Git credentials in the project's credential UI only; never commit credentials.
• Pin production images by digest; see Release images and smoke.
• 1.0.0 is the first stable public release. 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