{"id":46653925,"url":"https://github.com/nick-pape/grackle","last_synced_at":"2026-06-11T16:01:35.300Z","repository":{"id":340733130,"uuid":"1163140873","full_name":"nick-pape/grackle","owner":"nick-pape","description":"Manage and orchestrate AI coding agents (Claude Code, Copilot, Goose, etc.) on remote machines — task decomposition, multi-agent coordination, and real-time visibility across environments.","archived":false,"fork":false,"pushed_at":"2026-06-10T01:54:04.000Z","size":78427,"stargazers_count":19,"open_issues_count":85,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-10T02:13:34.957Z","etag":null,"topics":["acp","agent-client-protocol","agentic-workflow","ai-agents","claude-code","cli","coding-agent","developer-tools","mcp","multi-agent","orchestration","remote-development","typescript"],"latest_commit_sha":null,"homepage":"https://nick-pape.github.io/grackle/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nick-pape.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-21T06:39:30.000Z","updated_at":"2026-06-07T01:38:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"6edd6127-fe42-46ad-8820-5f4394ffa8b0","html_url":"https://github.com/nick-pape/grackle","commit_stats":null,"previous_names":["nick-pape/grackle"],"tags_count":326,"template":false,"template_full_name":null,"purl":"pkg:github/nick-pape/grackle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nick-pape%2Fgrackle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nick-pape%2Fgrackle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nick-pape%2Fgrackle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nick-pape%2Fgrackle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nick-pape","download_url":"https://codeload.github.com/nick-pape/grackle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nick-pape%2Fgrackle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34206492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acp","agent-client-protocol","agentic-workflow","ai-agents","claude-code","cli","coding-agent","developer-tools","mcp","multi-agent","orchestration","remote-development","typescript"],"created_at":"2026-03-08T07:07:56.599Z","updated_at":"2026-06-11T16:01:35.245Z","avatar_url":"https://github.com/nick-pape.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Grackle\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@grackle-ai/cli\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@grackle-ai/cli.svg\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/nick-pape/grackle/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/nick-pape/grackle/actions/workflows/ci.yml/badge.svg?branch=main\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e [!WARNING]\n\u003e 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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/nick-pape/grackle/main/apps/docs-site/static/img/grackle-logo.png\" alt=\"Grackle\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n## A plague of grackles\n\nThat'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.\n\n**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_.\n\nRun [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview), [Copilot](https://github.com/features/copilot), [Codex](https://openai.com/index/codex/), [GenAIScript](https://microsoft.github.io/genaiscript/), or any [ACP](https://agentclientprotocol.com/) 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.\n\n![Dashboard — active sessions, task triage, environment health, and workspaces](screenshots/dashboard-projects-tasks.png)\n\n\u003e **[Try the interactive demo](https://nick-pape.github.io/grackle/demo/)** — no install required. Explore the full UI with realistic mock data.\n\n## What makes Grackle different\n\n**Agent IPC** — Parent sessions spawn children with bidirectional pipes. Structured communication between agents — no polling, no shared files, no prompt-stuffing.\n\n**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.\n\n**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.\n\n**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.\n\n**Script personas** — Not everything needs an LLM loop. [GenAIScript](https://microsoft.github.io/genaiscript/) personas run deterministic TypeScript workflows — linters, formatters, analyzers — under the same session and task primitives as any agent.\n\n## See it in action\n\n### Live agent stream\n\nWatch 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.\n\n![Live agent stream — tool cards, code output, and inline interaction](screenshots/task-stream-view.png)\n\n### Task trees and dependencies\n\nDecompose 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.\n\n![Task tree — hierarchical tasks with status indicators and dependency badges](screenshots/task-tree-hierarchy.png)\n\n### DAG visualization\n\nInteractive dependency graph showing hierarchy and blocking relationships. Click any node to see its stream, findings, or overview.\n\n![DAG visualization — interactive task dependency graph](screenshots/dag-visualization.png)\n\n### Knowledge graph\n\nAgents 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.\n\n![Knowledge graph — semantic search with interactive graph explorer](screenshots/knowledge-graph.png)\n\n### Findings\n\nCategorized discoveries shared across agents within a workspace — architecture decisions, bugs, API patterns, dependency issues. Tagged and searchable.\n\n![Findings — categorized discoveries shared across agents](screenshots/findings-panel.png)\n\n### Personas\n\nNamed 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 \u0026 Format\" script persona for deterministic workflows.\n\n![Personas — specialized agent templates with runtime, model, and MCP tool configuration](screenshots/persona-management-view.png)\n\n### Environments\n\nEach agent runs inside an isolated environment. Connect one or many:\n\n| Adapter          | Command                                                      |\n| ---------------- | ------------------------------------------------------------ |\n| 🐳 **Docker**    | `grackle env add my-env --docker`                            |\n| 💻 **Local**     | `grackle env add my-env --local`                             |\n| 🔒 **SSH**       | `grackle env add my-env --ssh --host ...`                    |\n| ☁️ **Codespace** | `grackle env add my-env --codespace --codespace-name \u003cname\u003e` |\n\n![Environment detail — adapter type, session count, cost, workspaces, and management actions](screenshots/agent-session-stream.png)\n\n### Themes\n\n9 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.\n\n![Themes — Grackle, Matrix, Grackle Light, Sandstone](screenshots/theme-grid.png)\n\n## Features\n\n|     | Feature                    | Description                                                                                                                                                                                    |\n| --- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 📡  | **Real-time streaming**    | Watch agent tool calls and output as they happen — specialized cards for each tool type                                                                                                        |\n| 🌳  | **Git worktree isolation** | Every task gets its own branch in its own worktree — zero interference between agents                                                                                                          |\n| 🧠  | **Knowledge graph**        | Semantic search over findings and task context — agents build shared understanding across sessions                                                                                             |\n| 🔄  | **Multi-runtime support**  | Claude Code, Copilot, Codex, and GenAIScript — plus experimental Agent Client Protocol (ACP) runtimes (Goose, codex-acp, copilot-acp, claude-code-acp) — swap runtimes per persona or per task |\n| 🌲  | **Task tree hierarchy**    | Parent/child subtrees with recursive tree view, expand/collapse, and progress badges                                                                                                           |\n| 🔗  | **Task dependencies**      | Dependency gating — blocked tasks wait for their dependencies to complete                                                                                                                      |\n| 🎭  | **Personas**               | Named agent configs with system prompts, runtime/model, and scoped MCP tool allowlists                                                                                                         |\n| 🔁  | **Session history**        | Every task tracks its full session history — retry failed runs and compare attempts                                                                                                            |\n| ✅  | **Task review \u0026 approval** | Approve or reject completed tasks with feedback that feeds into the next attempt                                                                                                               |\n| 🔌  | **MCP server**             | 80+ tools — any agent with MCP connected can create tasks, spawn sessions, query knowledge, and orchestrate work                                                                               |\n| 💬  | **Chat**                   | Talk to the orchestrator directly — it has access to every MCP tool in Grackle                                                                                                                 |\n| 💰  | **Usage tracking**         | Token counts and cost per session, task, or workspace                                                                                                                                          |\n| 🔄  | **Session recovery**       | Environments auto-reconnect. Suspended sessions resume where they left off                                                                                                                     |\n| 🔀  | **IPC pipes**              | Parent sessions spawn children with bidirectional pipes for structured communication                                                                                                           |\n| ⏰  | **Scheduled triggers**     | Cron expressions and interval shortcuts for recurring task creation                                                                                                                            |\n| ⌨️  | **Keyboard shortcuts**     | Global shortcuts for navigation and common actions                                                                                                                                             |\n\n## Quick Start\n\n### Docker (recommended)\n\nOne command — includes the server, web UI, knowledge graph (Neo4j), and a local agent environment:\n\n```bash\ndocker run -d --name grackle -p 3000:3000 -p 7434:7434 -p 7435:7435 -v grackle-data:/data ghcr.io/nick-pape/grackle:latest\n```\n\n(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.)\n\nOpen **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.\n\nTo mount your Claude Code credentials so agents can authenticate:\n\n```bash\ndocker run -d --name grackle -p 3000:3000 -p 7435:7435 -v grackle-data:/data \\\n  -v \"${HOME}/.claude:/home/node/.claude:ro\" \\\n  ghcr.io/nick-pape/grackle:latest\n```\n\n\u003e **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)`.\n\n\u003cdetails\u003e\n\u003csummary\u003eMount credentials for all runtimes\u003c/summary\u003e\n\n```bash\ndocker run -d --name grackle -p 3000:3000 -p 7435:7435 -v grackle-data:/data \\\n  -v \"${HOME}/.claude:/home/node/.claude:ro\" \\\n  -v \"${HOME}/.copilot:/home/node/.copilot\" \\\n  -v \"${HOME}/.codex:/home/node/.codex\" \\\n  -e GH_TOKEN=$(gh auth token) \\\n  ghcr.io/nick-pape/grackle:latest\n```\n\n- **Claude**: mounted read-only (redirected via `CLAUDE_CONFIG_DIR`)\n- **Copilot / Codex**: mounted writable (their CLIs write session state with no config dir override)\n- **GH_TOKEN**: enables the GitHub CLI and Codespace adapter inside the container\n- Use `${HOME}` (not `~`) — tilde expansion doesn't work in Docker on Windows\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDocker Compose\u003c/summary\u003e\n\nFor a more complete setup with Docker adapter integration, credential mounts, and networking:\n\n```bash\ncp deploy/docker-compose.yml deploy/.env.example .\ncp .env.example .env  # edit as needed\ndocker compose up -d\n```\n\nSee [`deploy/docker-compose.yml`](deploy/docker-compose.yml) for the full configuration.\n\n\u003c/details\u003e\n\n### npm\n\n```bash\n# 1. Install the CLI\nnpm install -g @grackle-ai/cli\n\n# 2. Start the server (gRPC + Web UI — all in one)\ngrackle serve\n\n# 3. Open the dashboard at http://localhost:3000\n\n# 4. Add a Docker environment and start working\ngrackle env add my-env --docker\n```\n\nOr skip the global install entirely — prefix every command with `npx`:\n\n```bash\nnpx @grackle-ai/cli serve\nnpx @grackle-ai/cli env add my-env --docker\n```\n\n\u003e **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:\n\u003e\n\u003e ```json\n\u003e { \"pnpm\": { \"onlyBuiltDependencies\": [\"better-sqlite3\"] } }\n\u003e ```\n\n\u003cdetails\u003e\n\u003csummary\u003eBuilding from source\u003c/summary\u003e\n\n```bash\nnpm install -g @microsoft/rush\nrush update \u0026\u0026 rush build\nnode packages/cli/dist/index.js serve\n```\n\n\u003c/details\u003e\n\n## Progressive complexity\n\nGrackle covers the whole spectrum — start simple, scale up.\n\n**One agent, one box** — Manage a single agent in a remote environment. No task tree, no orchestration. Just `grackle spawn`.\n\n**Task trees** — Decompose work into parent/child hierarchies. Chain siblings with dependencies. Review artifacts at each step.\n\n**Multi-agent** — Multiple agents working in parallel on a shared workspace, coordinating through the knowledge graph and IPC pipes.\n\n**Autonomous swarms** — Task decomposition, agent recruitment, and knowledge sharing — all through the same primitives.\n\n## Requirements\n\n- Docker (recommended — the Grackle app and its dependencies are bundled in the image)\n- Node.js \u003e= 22, \u003c 24 (for npm install — Node 24+ is not yet supported)\n\n\u003e 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.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnick-pape%2Fgrackle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnick-pape%2Fgrackle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnick-pape%2Fgrackle/lists"}