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.

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 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 an append-only record in the mesh's local SQLite store — 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. | | Task chaining | Chain tasks with depends_on: a dependent waits until its predecessors complete, then receives their completion summaries as an "Upstream results" appendix. A failed or cancelled predecessor holds (or, by mesh policy, cancels) the downstream chain and notifies the coordinator. mesh_enqueue_batch enqueues several already-confirmed tasks in one atomic call. |

🚢 Refinery — unattended landing on main

🧩 Submodule-aware convergence — works on real monorepos

• 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

🌐 See and steer every session

🔺 Multi-perspective review

🔐 P2P transport (trust, not a paywall)

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.

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):

| Agent | Provider | | --- | --- | | Claude Code | cli/claude-cli | | Codex CLI | cli/codex-cli | | Cursor Agent | cli/cursor-cli | | Google Antigravity CLI | cli/antigravity-cli | | Grok CLI | cli/grok-cli | | Kimi Code | cli/kimi | | Opencode | cli/opencode |

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

Star History

• 💬 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

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.

| | OSS (self-hosted) | Cloud (adhf.dev) | | --- | :--: | :--: | | Dashboard | localhost:3847 | adhf.dev, any browser or phone | | Account required | ❌ no auth | OAuth (GitHub / Google) | | Machines | 1 | 1 / 2 / 5 by plan | | Reach | localhost, or your LAN with --host | anywhere (P2P WebRTC + TURN for locked-down networks) | | Every provider (CLI / IDE / extension) | ✅ | ✅ | | Repo Mesh, Refinery, worktree nodes | ✅ single-machine mesh runs fully local | ✅ | | Mesh across machines | ❌ (no cross-machine relay) | ✅ | | Push notifications (approval / completion / error) | ❌ | ✅ | | Hosted REST API + API keys | ❌ (local API only) | ✅ | | Price | free, no quotas | Free / Pro / Ultra |

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.