{"id":51710146,"url":"https://github.com/iriseye931-ai/blockhouse","last_synced_at":"2026-07-16T20:03:43.025Z","repository":{"id":346893407,"uuid":"1191584576","full_name":"iriseye931-ai/blockhouse","owner":"iriseye931-ai","description":"A launch-control room for your local AI agents — block minifig crew, NASA-style GO/NO-GO board, real-time events from Claude Code hooks and agent logs. No cloud, no simulation.","archived":false,"fork":false,"pushed_at":"2026-07-02T21:23:00.000Z","size":27818,"stargazers_count":15,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-07-02T22:28:02.411Z","etag":null,"topics":["ai-agents","claude-code","dashboard","fastapi","local-llm","mission-control","mlx","multi-agent","pixel-art","react"],"latest_commit_sha":null,"homepage":"","language":"Python","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/iriseye931-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-03-25T11:45:11.000Z","updated_at":"2026-07-02T21:23:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iriseye931-ai/blockhouse","commit_stats":null,"previous_names":["iriseye931-ai/mission-control-dashboard","iriseye931-ai/blockhouse"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/iriseye931-ai/blockhouse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iriseye931-ai%2Fblockhouse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iriseye931-ai%2Fblockhouse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iriseye931-ai%2Fblockhouse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iriseye931-ai%2Fblockhouse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iriseye931-ai","download_url":"https://codeload.github.com/iriseye931-ai/blockhouse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iriseye931-ai%2Fblockhouse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35557060,"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-07-16T02:00:06.687Z","response_time":83,"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":["ai-agents","claude-code","dashboard","fastapi","local-llm","mission-control","mlx","multi-agent","pixel-art","react"],"created_at":"2026-07-16T20:03:42.384Z","updated_at":"2026-07-16T20:03:43.018Z","avatar_url":"https://github.com/iriseye931-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blockhouse\n\n**A launch-control room for your local AI agents — with a tiny crew that actually does the work.**\n\nYour agents render as animated block minifigs at their consoles: typing when they work, thinking when they reason, talking when they message each other, and throwing confetti when a task lands. Every pixel is driven by real events — Claude Code hooks, agent logs, and actual inter-agent messages. No simulation, no cloud, no API keys.\n\n\u003e A *blockhouse* is the hardened building at a rocket range where launch control sits. This one is made of blocks. The full mesh it watches lives at [The Range](https://github.com/iriseye931-ai/the-range).\n\n![React 19](https://img.shields.io/badge/React_19-Vite-blue) ![FastAPI](https://img.shields.io/badge/FastAPI-WebSockets-green) ![MLX](https://img.shields.io/badge/MLX-Qwen3.6_35B-green) ![License](https://img.shields.io/badge/license-MIT-purple)\n\n![Blockhouse](assets/dashboard-crew.png)\n\n---\n\n## Demo\n\n![Blockhouse demo](assets/dashboard-demo.gif)\n\n- [Short MP4 clip](assets/dashboard-demo.mp4) — CAPCOM message ▸ speech bubble ▸ task-complete confetti, all live data\n\nMore: [crew celebrating a finished task](assets/crew-celebration.png) · [CAPCOM exchange over AMP](assets/capcom-reply.png) · [release history](CHANGELOG.md)\n\n---\n\n## What you get\n\n- **The crew stage** — each agent is a block minifig at a console with a live status LED. Idle, thinking (thought dots), working (typing, code scrolling on their monitor), talking (speech bubble + data beam), waiting (amber `!`), celebrating (arms up + confetti when a task finishes).\n- **The Big Board** — NASA-style front screen: shift clock, orbit trace, live event ticker, and a **GO / NO-GO board** where your local services report as flight controllers (VIKING, MEMORY, COMMS, …). Click a cell for live service detail.\n- **CAPCOM console** — type on the stage and it sends a real AMP message to your runner agent; the reply comes back as a speech bubble. `/task \u003ctitle\u003e` queues real work on the runner's kanban board.\n- **Ops log** — a scrolling live feed of every tool call, thought, and handoff, with per-agent filter chips. Click a minifig: it waves, and the log filters to that agent.\n- **Telemetry footer** — CPU, RAM, MLX memory, disk, mesh availability, and a 24h timeline scrubber for replaying mesh state.\n- **Zero fake data** — everything on screen comes from hooks, logs, sockets, and health checks. If a service is down, the board says NO GO.\n\n---\n\n## How the pipeline works\n\n```\nClaude Code ──hooks──▶ POST /api/crew/hook ─┐\nagent log  ──tail───▶ backend feed ─────────┼─▶ crew state ──WebSocket──▶ stage (~2s latency)\nAMP inbox  ──watch──▶ speech events ────────┘\n```\n\n- **Lead agent (Claude Code):** the official [Hooks API](https://docs.anthropic.com/en/docs/claude-code/hooks) POSTs `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Notification`, and `Stop` events to the backend. Async hooks — they never block a tool call.\n- **Runner agent (Hermes):** the backend tails its agent log for sessions, tool calls, and token counts, and shells to its CLI for kanban task creation.\n- **Speech:** a watcher on the AMP message directories turns real agent-to-agent messages into speech bubbles.\n\nClaude Code hook config (goes in `~/.claude/settings.json`, one entry per event):\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [{\n      \"matcher\": \"*\",\n      \"hooks\": [{\n        \"type\": \"command\",\n        \"command\": \"curl -s -m 2 -X POST -H 'Content-Type: application/json' --data-binary @- http://127.0.0.1:8000/api/crew/hook \u003e/dev/null 2\u003e\u00261 || true\",\n        \"async\": true, \"timeout\": 3\n      }]\n    }]\n  }\n}\n```\n\n---\n\n## Quick start\n\n```bash\ngit clone https://github.com/iriseye931-ai/blockhouse\ncd blockhouse\n\n# backend — run from the repo root (package imports)\npip install -r backend/requirements.txt\nuvicorn backend.main:app --host 0.0.0.0 --port 8000\n\n# frontend (second terminal)\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run dev\n```\n\n- Dashboard: http://localhost:3000\n- Backend API: http://localhost:8000\n- WebSocket: `ws://localhost:8000/ws`\n\nThe backend starts polling local services immediately; the crew stage lights up as soon as hook events arrive. `docker-compose up --build` also works, but the two-process path above is the one exercised daily.\n\n---\n\n## Honest scoping\n\nBlockhouse was built for one specific mesh — Claude Code as lead, [Hermes](https://hermes-agent.nousresearch.com) as runner, OpenViking for memory, MLX for local inference on Apple Silicon — and the service list, paths, and agent identities reflect that. Adapting it means editing `backend/config.py` (service URLs and paths, or override via `backend/.env`) and the `SKINS`/`ANCHORS`/`CALLSIGNS` tables in `frontend/src/components/CrewStage.tsx`. The bones — hook receiver, log tail, AMP watcher, WebSocket fan-out, canvas stage — are generic.\n\n| Role | Built with | Swappable for |\n|------|-----------|----------------|\n| Lead agent | Claude Code | any CLI agent that can POST hook events |\n| Runner agent | Hermes (MLX) | any agent with a log to tail + a task CLI |\n| Memory | OpenViking + Memory MCP | anything with a health endpoint |\n| Local LLM | MLX (Qwen3.6 35B / Qwen3.5 9B, 4-bit) | Ollama, llama.cpp |\n\n---\n\n## REST API\n\n```\nGET  /api/health         — health check\nGET  /api/status         — full dashboard state snapshot\nGET  /api/crew           — crew state + recent crew events\nPOST /api/crew/hook      — Claude Code hook receiver (lead-agent activity)\nPOST /api/crew/task      — queue a task on the runner's kanban\nGET  /api/agents         — mesh agents + presence\nGET  /api/routing        — routing summary\nGET  /api/system         — CPU, RAM, MLX RAM\nGET  /api/cron           — runner's scheduled jobs\nGET  /api/memories       — recent memory recalls\nGET  /api/history        — 24h state snapshots (timeline scrubber)\nPOST /api/amp/send       — send an AMP message to any agent\nPOST /api/agent-messages — operator handoff notes (agent inbox)\nWS   /ws                 — full state on every update + crew events\n```\n\n---\n\n## Stack\n\n| Layer | Tech |\n|-------|------|\n| Frontend | React 19, Vite, TypeScript, Tailwind, Zustand, Canvas 2D |\n| Backend | FastAPI, uvicorn, WebSockets, Pydantic |\n| Inference (reference mesh) | MLX — Qwen3.6 35B-A3B + Qwen3.5 9B, 4-bit, Apple Silicon |\n| Deploy | Docker Compose, or two processes |\n\nRouting in the reference mesh is `local-first, premium-by-exception`: the local runner handles routine volume; the lead agent is reserved for planning, ambiguous debugging, tricky refactors, and final review.\n\n---\n\n## Repo notes\n\n- Screenshots and the demo GIF are captured from the live dashboard — not mockups, not simulated data.\n- This public repo covers the dashboard, its backend, and the event pipeline. Experimental local agent wrappers are intentionally excluded.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firiseye931-ai%2Fblockhouse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Firiseye931-ai%2Fblockhouse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firiseye931-ai%2Fblockhouse/lists"}