Grackle

[!WARNING] Grackle is pre-1.0 and still experimental. It may have unresolved security issues, annoying bugs, and broken workflows. Not recommended for use in production systems.

A plague of grackles

That's the collective noun. Also what you get when you stop babysitting one agent in a terminal and start running many — each on its own wire, with its own key, leaving its own name in the log.

Grackle is a self-hosted control plane for AI agents. Spawn one and watch it work. Spawn a hundred and close the laptop. When one does something stupid at 3 AM, you know which one — not "the platform," not "your token," that one.

Run Claude Code, Copilot, Codex, GenAIScript, or any ACP agent — on Docker, an SSH box, a Codespace, or this machine. Grackle handles the provisioning, the credentials, the transport, the lifecycle. You get a CLI, web UI, and MCP server out of the box.

Try the interactive demo — no install required. Explore the full UI with realistic mock data.

What makes Grackle different

Agent IPC — Parent sessions spawn children with bidirectional pipes. Structured communication between agents — no polling, no shared files, no prompt-stuffing.

Knowledge persistence — A semantic knowledge graph backed by Neo4j. One agent's architectural insight becomes another agent's context automatically. Search by concept, not keyword.

Session resilience — Environments auto-reconnect on disconnect. Suspended sessions resume where they left off. Events buffer during outages and drain on reconnect. No lost work.

Multi-vendor, one interface — Swap runtimes per persona or per task. Your orchestration doesn't break when you switch from Claude to Codex or add Copilot as a second opinion.

Script personas — Not everything needs an LLM loop. GenAIScript personas run deterministic TypeScript workflows — linters, formatters, analyzers — under the same session and task primitives as any agent.

See it in action

Live agent stream

Watch tool calls, code output, and reasoning as they happen. Specialized cards for each tool type — file edits show diffs, grep results show matches, bash commands show output, and todo lists track progress.

Task trees and dependencies

Decompose work into parent/child hierarchies. Chain tasks with dependency gates. Every task gets its own git worktree — agents never step on each other's branches.

DAG visualization

Interactive dependency graph showing hierarchy and blocking relationships. Click any node to see its stream, findings, or overview.

Knowledge graph

Agents write findings to a semantic knowledge graph. Other agents query it by concept. The UI explorer shows nodes (concepts, decisions, snippets, insights) and their relationships.

Findings

Categorized discoveries shared across agents within a workspace — architecture decisions, bugs, API patterns, dependency issues. Tagged and searchable.

Personas

Named agent configurations that bundle a system prompt, runtime, model, tool allowlists, and MCP permissions. Assign a "Software Architect" to decompose work, a "Code Reviewer" to audit diffs read-only, or a "Lint & Format" script persona for deterministic workflows.

Environments

Each agent runs inside an isolated environment. Connect one or many:

Themes

9 built-in themes — Grackle, Glassmorphism, Matrix, Neubrutalism, Monokai, Ubuntu, Sandstone, Verdigris, and Primer (several with light/dark variants). Switch in Settings or match your system preference.

Features

Quick Start

Docker (recommended)

One command — includes the server, web UI, knowledge graph (Neo4j), and a local agent environment:

docker run -d --name grackle -p 3000:3000 -p 7434:7434 -p 7435:7435 -v grackle-data:/data ghcr.io/nick-pape/grackle:latest

(Port 7434 is the gRPC server the host CLI talks to; 7435 exposes the MCP HTTP endpoint for MCP clients — omit 7435 if you only need the web UI.)

Open http://localhost:3000, pair with the code from docker logs grackle, and start working. Run grackle pair (or docker exec grackle grackle pair) to regenerate a pairing code.

To mount your Claude Code credentials so agents can authenticate:

docker run -d --name grackle -p 3000:3000 -p 7435:7435 -v grackle-data:/data \
  -v "${HOME}/.claude:/home/node/.claude:ro" \
  ghcr.io/nick-pape/grackle:latest

Windows note: The Claude Desktop app stores OAuth tokens in Windows Credential Manager (DPAPI), not ~/.claude/. Use -e ANTHROPIC_API_KEY=sk-... instead of the volume mount. Same for GH_TOKEN — pass -e GH_TOKEN=$(gh auth token).

docker run -d --name grackle -p 3000:3000 -p 7435:7435 -v grackle-data:/data \
  -v "${HOME}/.claude:/home/node/.claude:ro" \
  -v "${HOME}/.copilot:/home/node/.copilot" \
  -v "${HOME}/.codex:/home/node/.codex" \
  -e GH_TOKEN=$(gh auth token) \
  ghcr.io/nick-pape/grackle:latest

cp deploy/docker-compose.yml deploy/.env.example .
cp .env.example .env  # edit as needed
docker compose up -d

npm

# 1. Install the CLI
npm install -g @grackle-ai/cli

# 2. Start the server (gRPC + Web UI — all in one)
grackle serve

# 3. Open the dashboard at http://localhost:3000

# 4. Add a Docker environment and start working
grackle env add my-env --docker

Or skip the global install entirely — prefix every command with npx:

npx @grackle-ai/cli serve
npx @grackle-ai/cli env add my-env --docker

pnpm users: pnpm v8+ blocks package install scripts by default. If grackle serve crashes with a Could not locate the bindings file error, run pnpm approve-builds after installing and then reinstall, or add the following to your package.json before installing:

hljs language-json

Copy

{ "pnpm": { "onlyBuiltDependencies": ["better-sqlite3"] } }

npm install -g @microsoft/rush
rush update && rush build
node packages/cli/dist/index.js serve

Progressive complexity

Grackle covers the whole spectrum — start simple, scale up.

One agent, one box — Manage a single agent in a remote environment. No task tree, no orchestration. Just grackle spawn.

Task trees — Decompose work into parent/child hierarchies. Chain siblings with dependencies. Review artifacts at each step.

Multi-agent — Multiple agents working in parallel on a shared workspace, coordinating through the knowledge graph and IPC pipes.

Autonomous swarms — Task decomposition, agent recruitment, and knowledge sharing — all through the same primitives.

Requirements

• Docker (recommended — the Grackle app and its dependencies are bundled in the image)
• Node.js >= 22, < 24 (for npm install — Node 24+ is not yet supported)

You still need to provide your own model credentials (via environment variables or mounted config files). Some features like the Docker adapter require access to the host Docker socket.

License

MIT