English | 한국어

ADHDev

The control plane for your coding agents: every agent on every machine in one view, one shared task queue, and only work that passes your tests reaches main.

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 rebases finished work onto main, merging only if main hasn't moved — no merge-day hangover.

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

Try it in one command: npx @adhdev/daemon-standalone, then open http://localhost:3847.

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 → rebased onto main and merged only if main hasn't moved, worktree gone. Your phone only buzzed if something needed approving.

ADHDev is built that way. In the private monorepo where ADHDev is developed — this engine is published from it as a submodule — roughly one in six main commits is an Auto-merge via Refinery commit: work that an agent finished, the repo's own gates approved, and Refinery landed without a human running git merge. That history lives in the upstream monorepo, so this public mirror's own log won't show those merge commits.

---

Why ADHDev

🕸️ Repo Mesh — true multi-machine parallelism

(A single-machine mesh runs fully local; spreading it across machines needs the cloud edition.) 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:

📊 Quota-aware routing — spend the subscriptions you already pay for

Every machine reads how much of each CLI subscription's 5-hour and weekly window is left. When a task is claimed, a plan that is nearly out is skipped (the task waits or falls through to that machine's next CLI), and among the rest, quota that would expire unused at the next reset is spent first. The Machines page shows the whole fleet on one grid, and the mesh's Tasks tab forecasts which slot takes the next task at each difficulty before anything runs.

🚢 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 rebase-and-merge (only if main hasn't moved), and automatic worktree cleanup — unattended. Agents finish; the Refinery lands them. The mesh board above surfaces the pipeline live: tasks moving through the queue, refine jobs while convergence is in flight, and every dispatch, completion, and stall in the activity feed.

🧩 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.

⚡ 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.

🌐 See and steer every session

Your agents run locally; you watch and drive them from any browser. 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 pushes carry the start of the command itself, because approving rm -rf build/ and approving git push --force deserve different reaction times: the push arrives → tap it → approve in one tap (push-to-phone ships with the cloud edition).

🔺 Multi-perspective review

For a read-only investigation that matters — a bug RCA, a design review, an audit — ask the coordinator for a second opinion: it sends the same question to 2–3 workers on different providers, waits for their reports, and lays out where they agree, where they disagree, and which claims only one of them made. High agreement is not the same as being right — the same model with the same context repeats the same mistake — so the disagreements are the part worth reading.

🔐 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 handles sign-in, signaling and lightweight metadata, plus one deliberate exception: on the cloud edition it receives the approval prompt (the command and button labels) to build the push notification, and the push shows up to 80 characters of it. Chat, terminal output and your code don't sit on someone else's box. It's a trust property of the design, not an upsell.

---

How it compares

• Claude Code Remote Control, Codex Remote: great for driving one vendor's session from your phone. ADHDev adds a queue several vendors and machines share, quota-aware routing between them, and test-gated merges. If you run one CLI on one machine, the built-in remote features may be all you need.
• Paseo, Happy: open-source remote control and mobile apps for coding agents. ADHDev's focus is the work after the prompt: idle machines pull tasks, each in its own worktree, and only work that passes your tests lands on main.
• Conductor, Superset, Vibe Kanban: parallel agents in worktrees, ending in a diff or a PR you review and merge. ADHDev runs one queue that your Mac, Windows and Linux machines pull from and merges for you when the gates pass.

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 │                     └──────────────────────┘
   │  · Refinery   │
   └───────────────┘
         │
         └── git worktrees ── one isolated checkout per parallel task

• The daemon owns the integrations. Three provider categories: cli (PTY), ide (Chrome DevTools Protocol), extension (CDP webview).
• 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 → rebase → merge (main unchanged) → cleanup

Four properties that shape everything else:

1. 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.
2. Nothing polls. Worker completion, approval, and refine reports are delivered straight into the coordinator's session as they happen — via a structured report_completion call, not a screen-scrape. You wait on events; you don't ask for status in a loop.
3. 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.
4. Ambiguity stops the pipeline. The Refinery never force-pushes; anything it can't decide is held for a human instead of merged.

Deeper: Repo Mesh developer guide · session-host

---

Install

Requirements: Node.js 20 or newer (22 LTS recommended; on Windows use 22.x — see the note below), git, and at least one coding agent already installed and authenticated — ADHDev drives the CLIs you already use.

Recommended — the adhdev CLI:

npm install -g adhdev
adhdev standalone

Open http://localhost:3847.

Self-host directly with the standalone package:

npm install -g @adhdev/daemon-standalone
adhdev-standalone

Everything runs on your machine as a local daemon with an embedded dashboard — no cloud account required for the standalone path. Both packages install an adhdev command, so install one or the other, not both.

Cloud edition (several machines, push notifications):

curl -fsSL https://adhf.dev/install | sh      # macOS / Linux
irm https://adhf.dev/install.ps1 | iex         # Windows (PowerShell)
adhdev setup                                   # sign in, then open https://adhf.dev

Useful flags:

adhdev standalone --host 0.0.0.0  # allow other devices on the same LAN
adhdev standalone --port 8080     # custom port
adhdev standalone --token mysecret # token auth for scripts / operator access
adhdev standalone --no-open       # don't auto-open the browser
adhdev standalone --dev           # enable the DevServer API (:19280) to debug and test providers
adhdev-standalone --public <dir>  # (standalone package) serve a custom web dashboard build

Standalone stays localhost-only by default. If you bind to 0.0.0.0 for LAN access, the dashboard warns when neither token auth nor a dashboard password is configured.

Windows note: Windows + Node.js 24+ is currently blocked for normal startup/install paths. Use Node.js 22.x, or the PowerShell installer: irm https://adhf.dev/install.ps1 | iex (docs).

Canonical self-hosted docs:

• Self-hosted setup
• Self-hosted configuration
• Self-hosted local API

First five minutes

1. Start the daemon — adhdev standalone, then open http://localhost:3847. The dashboard detects which agents are installed on this machine.
2. Launch a session. Pick a provider (say Claude Code), pick a working directory, and start it. You now have a real agent session you can drive from chat or watch as a raw terminal — toggle between the two.
3. Send work and walk away. Type a task. When the agent hits a permission prompt, it shows up as an approval in the dashboard's activity inbox instead of blocking a terminal you're not looking at. (Push-to-phone for those approvals is a cloud feature.)
4. Paste a screenshot into the chat when a description isn't enough — it goes into the agent's context directly.
5. Try the mesh on one machine. Open /mesh, create a mesh bound to your repo, and clone a worktree node. Queue a task to it and watch the ledger: dispatch → completion → Refinery → rebase and merge into main. This all works self-hosted; only crossing to a second machine needs the cloud edition.

Stuck? The self-hosted setup guide covers ports, LAN exposure, and provider detection problems.

---

Supported Agents

ADHDev talks to coding agents through three provider categories — ide (CDP), extension (CDP webview), and cli (PTY).

CLI agents (PTY-driven, launched and controlled from the dashboard):

IDEs (via Chrome DevTools Protocol): Cursor, Google Antigravity, VS Code, VSCodium, Kiro, Windsurf, Trae, PearAI.

IDE extensions (CDP webview): Claude Code (VS Code), Codex, Cline, Roo Code.

Built-in ≠ verified. ADHDev ships a broad inventory; presence in the catalog means the integration exists, not that every one has been validated end-to-end. Support levels vary. See the live policy:

• Supported Providers
• Supported IDEs
• Compatibility & Caveats

ADHDev does not manage API keys for your agents — each tool handles its own auth. ADHDev detects install status and surfaces errors.

Add your own agent

Providers are data, not code you have to fork. A provider is a versioned manifest (provider.v1.json) plus scripts describing how to detect the tool, launch it, parse its output into chat turns, and recognise its approval prompts. Drop one in ~/.adhdev/providers/ and the dashboard picks it up — your override wins over the built-in of the same name, so you can fix a broken parser locally without waiting for a release.

• Verification tiers are explicit: Verified / Partial / Unverified. "Built-in" only means the integration exists.
• Guides: Supported Providers · Custom providers guide

If you get an agent working that isn't in the catalog, that's the most useful contribution you can make — open it against vilmire/adhdev-providers. Core pull requests here require signing the CLA (the bot prompts you).

---

Star History

---

Community

• 💬 Discord
• 🐛 Issues
• 🤝 Contributing
• 📋 Changelog

---

What's in This Repo

This is the open-source, self-hosted edition (AGPL-3.0). Hosted cloud operations are not part of this repository. Self-hosted is built around three local layers:

1. daemon-standalone exposes a local HTTP/WebSocket server and serves the web UI.
2. daemon-core manages IDE, CLI, and extension integrations.
3. session-host-daemon (adhdev-sessiond) owns long-lived PTY runtimes so CLI sessions survive daemon restarts.

Standalone API surface

• GET /api/v1/status — sessions[] array is the source of truth
• POST /api/v1/command
• GET /api/v1/runtime/:sessionId/snapshot
• GET /api/v1/runtime/:sessionId/events
• GET /api/v1/mux/:workspace/state
• POST /api/v1/mux/:workspace/control
• ws://localhost:3847/ws

Reference: Self-hosted API docs

---

Develop from source

git clone https://github.com/vilmire/adhdev.git
cd adhdev
npm install
npm run build
npm run dev

Useful workspace scripts:

npm run dev:daemon
npm run dev:web

---

OSS vs Cloud

The engine is open source. What the cloud adds is a reach layer: accounts, more than one machine, internet-wide remote access, and push.

If you only drive one machine and stay on your own network, self-hosted gives you everything except push notifications and the cross-machine mesh — no quotas. The cloud exists for the moment you add a second machine or want to reach your agents from outside the house.

---

License

AGPL-3.0-or-later. See LICENSE.