Skip to content

Commit 293580c

Browse files
Uzay-GUzay-G
committed
druids: multi-agent orchestration for coding agents
1 parent fd874ce commit 293580c

File tree

356 files changed

+31291
-19635
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

356 files changed

+31291
-19635
lines changed

‎.claude/skills/debug/SKILL.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
name: debug
3+
description: >
4+
Diagnose a running or completed Druids execution. Pulls agent traces,
5+
activity logs, and diffs, then produces a structured diagnostic covering
6+
communication health, errors, goal progress, agent performance, and
7+
behavioral bottlenecks.
8+
user-invocable: true
9+
---
10+
11+
# Debug an Execution
12+
13+
The user wants to understand what is happening (or what went wrong) inside a Druids execution. This skill produces a diagnostic report by pulling every available signal and analyzing it systematically.
14+
15+
## 1. Identify the execution
16+
17+
The user may pass a slug directly (`/debug gentle-nocturne`) or say something like "debug the current run". If no slug is given, call `list_executions` with `active_only=true` and pick the most recent one. If there are multiple active executions, ask which one.
18+
19+
## 2. Gather all available data
20+
21+
Make these calls in parallel where possible:
22+
23+
**a. Execution state** -- `get_execution` for the slug. Record: status, agent names, agent types, connections, topology edges, exposed services, PR URL, branch name.
24+
25+
**b. Full activity log** -- `get_execution_activity` with `n=200` and `compact=false`. This is the richest signal. It contains every tool call, message, error, connection event, and response across all agents. Request the full (non-compact) version so you can see tool arguments and outputs.
26+
27+
**c. Per-agent traces** -- For each agent in the execution, call `get_agent_trace`. This gives you the coalesced view: messages, thoughts, tool calls with status, and plans. Pull traces for all agents in parallel.
28+
29+
**d. Diff** -- `get_execution_diff`. If no diff exists yet, note that.
30+
31+
**e. Spec** -- from the execution data. You need this to evaluate whether agents are achieving the goal.
32+
33+
## 3. Analyze
34+
35+
Work through each dimension below. Do not skip dimensions even if they seem fine -- explicitly confirming health is part of the diagnostic.
36+
37+
### 3a. Communication health
38+
39+
Questions to answer:
40+
41+
- Are all agents connected? Check for `connected` and `disconnected` events. An agent that connected and then disconnected has a problem.
42+
- Is the topology correct for the program? Do agents that need to talk to each other have edges between them?
43+
- Are messages actually flowing? Look for `message` tool calls in the activity. Check that messages sent by one agent show up as received by the target.
44+
- How long between a message being sent and the receiver acting on it? Gaps longer than 30 seconds suggest the receiver is stuck or not listening.
45+
- Are any agents talking to themselves or sending messages that go nowhere?
46+
47+
### 3b. Errors
48+
49+
Questions to answer:
50+
51+
- Are there any `error` type events in the activity? What do they say?
52+
- Are there tool calls that returned errors? Look at `tool_result` events with error indicators.
53+
- Did any agent disconnect unexpectedly?
54+
- Are there repeated failures on the same tool call? This usually means the agent is stuck in a retry loop.
55+
- Did any agent hit a timeout?
56+
- Are there permission errors (git push failures, file access denied, port already in use)?
57+
58+
### 3c. Agent performance
59+
60+
For each agent, characterize:
61+
62+
- **Activity level**: How many tool calls has it made? Is it actively working or idle?
63+
- **Focus**: What is it spending its time on? (e.g., 80% file edits, 10% git, 10% messages)
64+
- **Progress**: Based on its trace, what has it accomplished relative to its role?
65+
- **Stuck indicators**: Is it repeating the same action? Has it gone silent? Is it producing long stretches of thinking without action?
66+
- **Tool usage patterns**: Which tools does it use most? Are there tools it should be using but isn't?
67+
68+
Then compare across agents:
69+
70+
- Which agent is furthest along?
71+
- Which agent is the weakest link (blocking others or making no progress)?
72+
- Is any agent doing redundant work that another agent already did?
73+
74+
### 3d. Goal progress
75+
76+
Compare the current state against the spec:
77+
78+
- What did the spec ask for?
79+
- What has actually been built? (Use the diff and exposed services.)
80+
- Has anyone attempted the demo from the spec?
81+
- What percentage of the requirements are met?
82+
- What is left to do?
83+
84+
### 3e. Behavioral bottlenecks
85+
86+
These are the pragmatic, structural problems that slow executions down:
87+
88+
- **File sharing**: Are agents trying to read files another agent is still writing? Look for file-not-found errors or stale reads.
89+
- **Info aggregation**: In programs with sub-agents, is the orchestrator actually collecting and using sub-agent output? Or is information getting lost?
90+
- **Messaging timeliness**: Are there long gaps where an agent should have sent a message but didn't? Calculate the longest gap between activity events for each agent.
91+
- **Hanging**: Is any agent completely silent for more than 2 minutes? This usually means it's stuck waiting for something or has crashed.
92+
- **Serialization**: Are agents doing work sequentially that could be parallel? (e.g., one agent waiting for another to finish before starting its own independent work)
93+
- **Scope creep**: Is any agent doing work outside its assigned role? (e.g., the reviewer starting to implement instead of reviewing)
94+
- **Thrashing**: Is any agent undoing and redoing work? Look for patterns like edit-revert-edit on the same files.
95+
96+
## 4. Present the diagnostic
97+
98+
Structure the output as follows. Be concrete and specific -- cite actual tool names, file paths, message contents, and timestamps from the trace. Do not hedge or generalize.
99+
100+
```
101+
## Diagnostic: {slug}
102+
103+
**Status**: {status} | **Agents**: {count} | **Duration**: {time since start}
104+
**Spec**: {one-line summary of what was asked for}
105+
**Branch**: {branch} | **PR**: {url or "none yet"} | **Diff**: +{added}/-{removed} lines
106+
107+
### Communication
108+
{2-4 sentences on topology health, message flow, latency. Flag any issues.}
109+
110+
### Errors
111+
{List each error with agent name and context. Or "No errors detected."}
112+
113+
### Agent Performance
114+
115+
#### {agent_name} ({agent_type})
116+
- Activity: {active/idle/stuck} -- {N} tool calls, last active {time}
117+
- Focus: {what it's spending time on}
118+
- Progress: {what it's accomplished}
119+
- Issues: {any problems, or "none"}
120+
121+
(repeat for each agent)
122+
123+
### Weakest link
124+
{Which agent is the bottleneck and why. Be direct.}
125+
126+
### Goal Progress
127+
- Spec asks for: {requirements list}
128+
- Completed: {what's done}
129+
- Remaining: {what's left}
130+
- Estimated completion: {close / far / stuck}
131+
132+
### Bottlenecks
133+
{List each bottleneck found, with evidence from the trace. Or "No structural bottlenecks detected."}
134+
135+
### Recommended actions
136+
{Concrete next steps. Examples:
137+
- "Send builder a message: the tests are failing because X, try Y"
138+
- "Stop agent Z, it's been hanging for 5 minutes"
139+
- "The reviewer hasn't received the builder's submission -- check topology"
140+
- "Everything looks healthy, just needs more time"}
141+
```
142+
143+
## 5. Offer to act
144+
145+
After presenting the diagnostic, ask the user if they want to take any of the recommended actions. You can:
146+
147+
- Send a message to an agent via `send_message`
148+
- Stop a stuck agent via `stop_agent`
149+
- Run a command on an agent's VM via `remote_exec` to inspect state
150+
- Check specific files or processes on the VM
151+
- SSH into the VM for the user via `get_agent_ssh`
152+
153+
Do not take action without the user's confirmation.
154+
155+
## Notes
156+
157+
- For running executions, the trace is live. If the user asks to "keep watching", re-pull activity after a minute and report changes.
158+
- If the execution has already completed or failed, the diagnostic is a post-mortem. Shift language accordingly: "what happened" instead of "what's happening".
159+
- The activity log is the primary signal. Agent traces are secondary -- they show the agent's perspective but miss inter-agent dynamics.
160+
- When citing evidence, include the agent name and a brief quote or description of the event. "builder called `Write` on `src/app.py` at 14:32" is better than "an agent edited a file".
161+
- If you see an agent in a retry loop (same tool call 3+ times with errors), that is the highest-priority finding. Flag it first.
162+
- Token usage from the execution record can indicate whether an agent is doing real work (high token usage) or stuck early (low token usage).

‎.claude/skills/druids-driver/SKILL.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
name: druids-driver
3+
description: >
4+
Reference for driving Druids: launching agent executions, monitoring
5+
progress, writing specs, and reviewing results. Loaded automatically
6+
so Claude Code always knows how to use Druids.
7+
user-invocable: false
8+
---
9+
10+
# Druids
11+
12+
Druids runs coding agents on remote VMs. You send a program and a spec, agents implement on isolated sandboxes, and the results come back as pull requests. Your role as the driver is to translate user intent into specs, launch executions, monitor progress, and review output.
13+
14+
Use Druids when the user asks to build a feature, fix a bug, or do work that benefits from delegation to background agents. Do not use it for quick edits, questions about the codebase, or tasks that require real-time back-and-forth with the user.
15+
16+
## Concepts
17+
18+
A **devbox** is a VM snapshot with the user's repo cloned and dependencies installed. Executions fork from it so each agent starts with a working environment. Created via `druids devbox create` and `druids devbox snapshot`.
19+
20+
A **program** is a Python file that defines `async def program(ctx, ...)`. It creates agents, registers tool handlers, and manages lifecycle. Programs live in `.druids/` in the repo. The driver reads the file and sends its source to `create_execution`.
21+
22+
An **execution** is a running instance of a program. Gets a slug like `gentle-nocturne`. Contains one or more agents working on VMs. When agents finish, they push a branch and open a PR.
23+
24+
An **agent** runs on a VM inside an execution. Created by programs via `ctx.agent(name, ...)`. Each has a bridge process connecting it back to the server.
25+
26+
## Workflow
27+
28+
1. User asks to build something.
29+
2. Explore the codebase. Understand conventions, test patterns, relevant files.
30+
3. Write a spec describing what to change. The spec is the primary input to the agent. Include file paths, function signatures, and concrete demo commands. If the `write-spec` skill is available, use it.
31+
4. Choose a program. `basher.py` in direct mode handles most implementation tasks (implementor + reviewer). `main.py` runs Claude and Codex in parallel for comparison. `review.py` demo-reviews an existing PR.
32+
5. Read the program source and call `create_execution` with `program_source` set to the file contents. Pass the spec and other parameters in `args`.
33+
6. Monitor with `get_execution`. Check status, agents, connections, PR URL.
34+
7. If an agent is stuck, check `get_execution_activity` and send guidance via `send_message` with `sender="driver"`.
35+
8. When agents finish, review the diff with `get_execution_diff` and report to the user with a link to the PR.
36+
37+
## Programs in `.druids/`
38+
39+
- `basher.py`: Implementation with review. Direct mode: pass `task_name` and `task_spec` to spawn an implementor+reviewer pair. The implementor builds on a feature branch, the reviewer demos the change and creates a PR if it works (up to 3 review rounds). Full mode: a finder agent scans for tasks and spawns pairs automatically.
40+
- `main.py`: Parallel comparison. Spawns a Claude agent and a Codex agent on the same spec. Both implement independently, both submit when done.
41+
- `build.py`: Spec-driven build with auditing. A builder implements, a critic reviews each commit for simplicity, and an auditor verifies the demo evidence is real.
42+
- `review.py`: Demo-review of a PR. A demo agent checks out the PR, runs the system, and tests every changed behavior from the outside. A monitor watches for lazy behavior. Takes `pr_number`, `pr_title`, `pr_body`, `repo_full_name`.
43+
44+
## MCP tools
45+
46+
These tools are exposed by the Druids server. They are your interface for creating and managing executions.
47+
48+
### Creating work
49+
50+
`create_execution`: start an execution. Required: `program_source` (Python source string). Optional: `devbox_name`, `repo_full_name` (finds devbox by repo when name not set), `git_branch`, `args` (dict of string key-value pairs). Returns `execution_slug` and `execution_id`.
51+
52+
### Monitoring
53+
54+
`list_executions`: list executions. Pass `active_only=false` to include stopped ones.
55+
56+
`get_execution`: get execution by slug. Returns status, agents, connections, branch name, PR URL, exposed services, client events.
57+
58+
`get_execution_activity`: recent trace events for an execution. Optional: `n` (default 50), `compact` (default true). Shows agent names, event count, recent activity.
59+
60+
`get_execution_diff`: git diff from an execution's VM. Optional: `agent` (default picks the first agent with a machine).
61+
62+
`get_agent_events`: event stream for a specific agent. Required: `slug`, `agent_name`. Optional: `after_sequence` (resume from sequence number), `limit` (default 100).
63+
64+
### Interacting with agents
65+
66+
`send_message`: message a running agent. Required: `execution_slug`, `receiver` (agent name), `message`. Set `sender` to `"driver"`.
67+
68+
`remote_exec`: run a shell command on a VM. Target by `repo` (devbox) or `execution_slug` + `agent_name` (agent VM). Required: `command`. Returns `stdout`, `stderr`, `exit_code`.
69+
70+
`stop_agent`: stop an agent. Required: `agent_name`, `execution_slug`.
71+
72+
`get_agent_ssh`: SSH credentials for an agent's VM. Required: `agent_name`, `execution_slug`. Returns host, port, username, private_key, password.
73+
74+
### Stopping work
75+
76+
`update_execution`: change execution status. Set `status` to `"stopped"`, `"completed"`, or `"failed"`.
77+
78+
## CLI commands
79+
80+
The `druids` CLI runs on the driver's local machine:
81+
82+
- `druids exec <program> [--devbox NAME] [--branch BRANCH] [key=value ...]`: run a program. Bare names resolve against `.druids/` (e.g. `druids exec build`).
83+
- `druids execution ls [--all]`: list executions.
84+
- `druids execution status SLUG`: check execution status.
85+
- `druids execution stop SLUG`: stop an execution.
86+
- `druids execution send SLUG MESSAGE [--agent NAME]`: send a message to a running agent.
87+
- `druids execution ssh SLUG [--agent NAME]`: open a shell on a VM.
88+
- `druids execution connect SLUG [--agent NAME]`: resume an agent's coding session.
89+
- `druids devbox create [--name NAME] [--repo OWNER/REPO]`: provision a devbox.
90+
- `druids devbox snapshot [--name NAME] [--repo OWNER/REPO]`: snapshot and save.
91+
- `druids devbox ls`: list all devboxes.
92+
- `druids devbox secret set/ls/rm`: manage devbox secrets.
93+
- `druids auth set-key KEY`: set auth key.
94+
- `druids init`: initialize repo (programs, .mcp.json, llms.txt).
95+
96+
## Reference
97+
98+
- Execution status values: `created`, `running`, `completed`, `stopped`, `failed`.
99+
- `remote_exec` can target a devbox directly (pass `repo`) without a running execution. Use for setup, debugging, or ad-hoc commands.
100+
- Agents call tools on the VM via `druids tool <tool_name> key=value`. Tools are defined by `@agent.on("tool_name")` in the program.
101+
- Built-in agent tools: `expose` (expose a port as public HTTPS URL), `message` (send message to another agent), `list_agents` (list agents in the execution).
102+
- Programs can use `share_machine_with=other_agent` to run two agents on the same VM.

0 commit comments

Comments
 (0)