adhdev

🦦 ADHDev — Agent Dashboard Hub. Monitor & control AI coding agents from a single dashboard. Self-hosted, open-source.

Generate Convert Improve

Install / Use

npx skills add vilmire/adhdev

Installs into whichever agent you are using.

About this skill

📦

Other

Other agent config

Quality Score

75/100

Skill content

View source on GitHub

English | 한국어

ADHDev

Ten coding agents on one repo, none of them stepping on each other — driven from your browser or phone.

AI coding agents have become long-running background workers. ADHDev is the control plane for them: launch, watch, approve, and steer agent sessions from a web or mobile dashboard — Claude Code, Codex, Kimi, Cursor CLI, Antigravity CLI side by side, across every machine you own — and hand off convergence to an unattended pipeline that merges finished work into main.

Parallel agents without the collisions. Every task runs in its own git worktree; the Refinery gates, verifies, and fast-forwards finished work home — no merge-day hangover.

Website: adhf.dev · Docs: docs.adhf.dev

The loop: describe a task in chat → the coordinator files it, tags it, queues it → an idle machine claims it into a fresh worktree → your repo's own gates decide → ff-merge to main, worktree gone. Your phone only buzzed if something needed approving.

This repo is built that way: about a third of recent commits on its main are Auto-merge via Refinery commits. Don't take our word for it — clone it and run git log --oneline -60 | grep -c "via Refinery".

Why ADHDev

🌐 Web-first control

Your agents run locally; you drive them from anywhere. The dashboard is a real control surface — inspect active sessions, read chat and terminal state, approve or interrupt work, reopen the right history, and send the next instruction from a browser or your phone. No terminal babysitting. Approval notifications carry the command text itself, because approving rm -rf build/ and approving git push --force deserve different reaction times (push-to-phone ships with the cloud edition).

🕸️ Repo Mesh — true multi-machine parallelism

Enqueue tasks with dependencies and let a coordinator dispatch them to whichever node has spare capacity — your laptop, a desktop, a build box. This is genuine multi-machine orchestration over a P2P mesh, not SSH into one host. Each task runs in its own worktree so agents never step on each other. The mesh and Refinery engine ships in this repo; cross-machine dispatch runs on the cloud edition.

A mesh is bound to one git repository and owns the moving parts you'd otherwise coordinate by hand:

| | | | --- | --- | | Task queue | Pull-based. pending → assigned → completed/failed, with depends_on ordering and retries. Idle nodes claim work themselves — no push scheduler to get out of sync. | | Missions | A goal that groups many tasks, so a restarted coordinator picks up where the last one left off instead of re-queuing everything. | | Worktree nodes | An isolated branch checkout per parallel task, bootstrapped automatically (install, native rebuilds, gitignored build outputs) before any work is dispatched to it. | | Append-only ledger | Every dispatch, completion, failure, stall, and checkpoint as a JSONL event — the audit trail that makes "what actually happened" answerable after the fact. | | Operating notes | Lessons recorded at runtime (a provider quirk, a recovery procedure) are injected into every future coordinator prompt, so knowledge outlives the session that learned it. | | Live-state prompt | The coordinator's system prompt isn't static text — at launch it's a render of live mesh state (node health, active mission, recent failures, accumulated notes), and at runtime events are injected into its session instead of it polling. | | Difficulty routing | Map easy work to cheap models and hard work to expensive ones with deep thinking, per node capability — the token bill scales with difficulty, not with task count. |

⚡ Async by design — you talk to one place

You talk to one place. The coordinator orchestrates every worker and machine asynchronously — it waits on events, you don't. No session babysitting. Instead of sitting in front of each agent window watching for it to finish, you hand work to a single coordinator that drives all the workers in parallel and reacts only when a completion, approval, or status event actually arrives — no polling, no blocking waits. One conversation for you; a non-blocking event loop underneath.

🚢 Refinery — unattended landing on `main`

Parallelism only pays off if the work actually merges. The Refinery converges finished tasks with per-repo validation gates, patch-equivalence checks, submodule-aware fast-forward merges, and automatic worktree cleanup — unattended. Agents finish; the Refinery lands them. The mesh board above surfaces the whole pipeline live: the ledger's DIRECT FAST FORWARD entries are landed tasks, and REFINE JOBS tracks convergence in flight.

🧩 Submodule-aware convergence — works on real monorepos

Parallel worktrees and unattended merges get fragile the moment git submodules enter the picture. ADHDev handles that case head-on — this very project is a submodule monorepo (a root repo plus the AGPL engine and provider catalog as submodules), and we dogfood the mesh and Refinery on it every day. The Refinery treats submodules as first-class during convergence:

Reachability gate — before a root branch lands on main, it verifies the referenced submodule commits are reachable from the submodule's origin/main; if not, the task is held as blocked until those commits are published.
Patch-equivalence detection — when a submodule commit is rebased or squashed and its SHA changes, the Refinery still determines whether the content already landed, so it won't double-merge or falsely flag a divergence.
Atomic pointer bumps — the submodule pointer bump converges together with the root change, so an unattended merge never leaves the root pointing at a broken or dangling submodule commit.

🔺 MAGI — cross-verified results

MAGI — Multi-Agent Ground-truth Insight, and yes, the Evangelion reference came first and the backronym took a while — runs a read-only investigation (a bug RCA, a design review, an audit) through several independent agents at once, then you read where they disagree.

The premise is that high agreement is not the same as being right: the same model, given the same prompt and the same context, produces the same hallucination. So MAGI fans the question out across different machines and different providers, and weighs consensus by how independent the sources actually were:

Answers come back sorted into agreed / contested / dissent / singleton / source-coupled — and agreement between replicas sharing a provider or machine is discounted as a likely shared hallucination rather than counted twice.
The headline output isn't a verdict, it's a needs_verification list — the friction is the product.
Independence is enforced, not hoped for: fewer than two genuinely independent targets is an error, not a silent downgrade. Replicas are read-only, so cross-checking can never write to your repo.

Real case from this project: a single confident RCA concluded "no code change needed." Independent cross-verification overturned it as a two-layer compound bug.

🔐 P2P transport (trust, not a paywall)

Chat, commands, screenshots, and remote input travel over an encrypted WebRTC data channel directly between your dashboard and your daemon. The server only handles signaling and lightweight metadata — your working data doesn't sit on someone else's box. It's a trust property of the design, not an upsell.

How it works

ADHDev doesn't replace your agents or spawn its own — it attaches to the ones already installed on your machine and gives them a control surface.

   browser / phone
         │  chat, commands, screenshots, remote input
         ▼
   ┌───────────────┐        PTY          ┌──────────────────────┐
   │    daemon     │────────────────────▶│ Claude Code, Codex,  │
   │ (your machine)│◀────────────────────│ Cursor CLI, …        │
   │               │        CDP          ├──────────────────────┤
   │  · providers  │────────────────────▶│ Cursor, VS Code,     │
   │  · sessions   │                     │ Antigravity, …       │
   │  · mesh + queue│       stdio (ACP)  ├──────────────────────┤
   │  · Refinery   │────────────────────▶│ Goose, Qwen, …       │
   └───────────────┘                     └──────────────────────┘
         │
         └── git worktrees ── one isolated checkout per parallel task

The daemon owns the integrations. Four provider categories: cli (PTY), ide (Chrome DevTools Protocol), extension (CDP webview), acp (Agent Client Protocol over stdio).
Long-lived runtimes are a separate process. adhdev-sessiond owns the PTYs, so your CLI sessions survive a daemon restart or upgrade.
Self-hosted talks straight to the daemon over HTTP + WebSocket on localhost:3847. In the cloud edition the same data rides a WebRTC data channel browser↔daemon, with the server only doing signaling.

What happens when you queue a task

mesh_enqueue_task  →  SQLite queue (pending)
                   →  an idle node claims it (assigned)
                   →  worker agent runs in its own git worktree
                   →  completed / failed  →  append-only ledger
                   →  Refinery: repo's own gates → patch equivalence → ff-only merge → cleanup

Four properties that shape everything else:

The coordinator routes, it doesn't implement. It orchestrates mesh tools instead of reading and editing code itself, so its context stays small and its ownership survives daemon restarts.
Nothing polls. A reconcile loop pushes completion, approval, and refine events into the coordinator's session. You wait on events; you don't ask for status in a loop.
Git is the proof, not the agent's word. "Done" is verified with real git state and commit checkpoints, not with a worker claiming success.
**Ambiguity stops the pipelin

Truncated for display — read the full file on GitHub.