Drasill

An agent mesh control plane and dashboard server for coordinating local Claude Code sessions. Agents register, discover each other, and exchange messages through Drasill — using heimdall stdin injection for message delivery.

Why "Drasill"?

In Norse mythology, Yggdrasill is the world tree — an immense ash that connects the nine realms, carrying messages between gods, humans, and the dead through its branches and roots. The squirrel Ratatoskr runs up and down its trunk delivering messages (and insults) between realms.

Drasill is your local world tree. It connects Claude Code agents running in separate terminals, letting them discover each other, exchange tasks, and coordinate work — all through a single trunk. Each agent is a Ratatoskr, checking in at the tree for new messages whenever it finishes its current task.

The name drops the "Ygg-" prefix (meaning "terrible" or "dreadful") because there's nothing terrible about well-coordinated agents.

What It Does

Agent Mesh

The mesh turns Drasill into a control plane for local Claude Code sessions:

┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  Claude Code  │    │  Claude Code  │    │  Claude Code  │
│    (alpha)    │    │     (beta)    │    │    (gamma)    │
└──────┬────────┘    └──────┬────────┘    └──────┬────────┘
       │                    │                    │
       │  register          │  send msg          │  inbox
       │  send msg          │  check inbox       │  consume
       │  check inbox       │                    │  send msg
       │                    │                    │
       └────────────────────┼────────────────────┘
                            │
                    ┌───────┴────────┐
                    │    Drasill     │
                    │    :8400       │
                    │                │
                    │    /mesh/*     │
                    │    SQLite      │
                    │    SSE + async │
                    └────────────────┘

• Register — POST /mesh/agents joins the mesh with a name and optional session ID
• Discover — GET /mesh/agents lists all active agents
• Message — POST /mesh/agents/{name}/inbox sends a message (with optional heimdall wake)
• Consume — GET /mesh/agents/{name}/inbox returns the oldest unread message
• Pruning — Stale agents auto-transition: active → idle → dead → removed

All /mesh/* endpoints are localhost-only (middleware rejects non-loopback requests), so exposure via Cloudflare Tunnel or similar is safe.

Web UI

A live-updating control panel showing agent status, recent messages, and a send-message form. SSE events trigger HTMX partial reloads, Alpine.js handles client-side interactivity. Web terminal gives browser access to agent pty sessions.

Agent Integration

No plugins or hooks needed. Drasill injects mesh awareness into each agent's system prompt at launch and delivers messages via heimdall stdin injection when agents go idle. Agents communicate with peers using curl to the mesh API.

Prerequisites

# Verify prerequisites
uv --version && hm --version && claude --version && git --version && curl --version

Quick Start

# Install dependencies
uv sync

# Start the server
uv run uvicorn drasill.app:create_app --factory --reload --port 8400

# Open the dashboard
open http://localhost:8400

Deploy with systemd

./deploy/install.sh

Join the mesh from Claude Code

Agents are mesh-aware at launch — no setup needed. Send a message from any terminal:

curl -s -X POST "http://localhost:8400/mesh/agents/alpha/inbox" \
  -H 'Content-Type: application/json' \
  -d '{"from_agent": "human", "body": "Run the tests and report results"}'

Configuration

config.toml at the project root (or set DRASILL_CONFIG env var):

[server]
host = "0.0.0.0"
port = 8400

[db]
path = "~/.local/share/drasill/dash.db"

# Per-dashboard overrides
[dashboards.agent_mesh]
enabled = true
schedule = "5s"

Development

uv sync                              # install deps
uv run pytest                        # run tests (95% coverage gate)
uv run ruff check py_src py_tests    # lint
uv run ruff format py_src py_tests   # format
uv run nox -s all_checks             # lint + format + typecheck + test

150 tests, 96% coverage, zero lint warnings.

Stack

Project Structure

py_src/drasill/
├── app.py                 # FastAPI app factory + lifespan
├── config.py              # TOML → Pydantic config loader
├── db.py                  # SQLite schema + init
├── claude.py              # Async claude CLI wrapper
├── doctor.py              # Dependency health checks
├── supervisor_client.py   # Async heimdall socket client
├── mesh/
│   ├── router.py          # /mesh/* API endpoints
│   ├── models.py          # Pydantic request/response models
│   ├── events.py          # SSE event bus (asyncio.Queue fanout)
│   ├── middleware.py       # Localhost-only security middleware
│   ├── uploads.py         # File attachment storage
│   └── pruning.py         # Agent lifecycle management
├── terminal/
│   └── router.py          # WebSocket heimdall proxy + session creation
├── templates/             # Jinja2 + HTMX templates
└── static/                # PWA assets + CSS

License

Apache 2.0