Tutorial: Your First Real Task
Getting Started got you installed and chatting in five minutes. This tutorial is the next step: a hands-on walk through what ADHDev is actually for — running a real coding agent, staying in control of what it does, and (optionally) coordinating work across machines through Repo Mesh and letting the Refinery land it on main.
You'll do everything by hand so you can see each piece work. By the end you'll understand the four things ADHDev gives you — Refinery, any agent, your machines, remote control — not as bullet points, but from having driven them.
What you need
- The
adhdevCLI installed (see Getting Started if not). - At least one CLI agent installed and authenticated on your machine — Claude Code, Codex CLI, Gemini CLI, or another. ADHDev doesn't manage the agent's own login; the agent keeps its own auth.
- A git repository you're comfortable letting an agent make a small change in.
This whole tutorial works in Standalone mode (no account). The Repo Mesh section at the end is Cloud only — it's marked clearly, and everything before it is self-contained.
Step 1 — Start standalone and open the dashboard
adhdev standaloneThis starts the embedded daemon (localhost:3847) and the local dashboard (localhost:3000) together. Open http://localhost:3000.
What you'll see: the dashboard with your local machine listed as online. No login screen — standalone is entirely local.
📸 [screenshot: standalone dashboard, one machine online, empty session list]
Why it matters: this is the control plane. Everything an agent does from here on — chat, tool calls, approvals — flows peer-to-peer between this browser and your daemon. The dashboard is your single view over every session, and in a moment it'll have one to show.
Sanity check
If the dashboard is empty or the machine shows offline, run adhdev doctor in another terminal. It checks the daemon process, the local connection, and the provider registry, and points at the specific fix.
Step 2 — See what ADHDev can drive
Before launching, look at what's detected on this machine:
adhdev detectWhat you'll see: a list of known providers with installed: yes/no. Anything yes is ready to launch.
Why it matters: a provider is ADHDev's adapter for one agent, and there are four kinds — you'll pick from the first one here:
| Category | Transport | Examples |
|---|---|---|
| cli | PTY (terminal) | Claude Code, Codex CLI, Gemini CLI, Hermes CLI |
| ide | Chrome DevTools Protocol | Cursor, VS Code, Windsurf, Kiro, PearAI, Trae |
| extension | CDP webview | Antigravity |
| acp | stdio (Agent Client Protocol) | ACP-compatible agents |
For this tutorial we use a cli provider — it's the quickest to a working session and needs no editor relaunch.
Step 3 — Launch a CLI agent session
Pick a CLI agent that showed installed: yes. For example:
adhdev launch claude # Claude Code
# or: adhdev launch codex / adhdev launch geminiThe daemon starts the agent under a PTY and streams the terminal to the dashboard.
What you'll see: a new session card appears in the dashboard. Click it to open a live terminal view with an input box at the bottom.
📸 [screenshot: session card + open terminal view with input box]
Why it matters: the agent is running on your machine, in your working directory, with its own auth — ADHDev just gives you a window onto it. Nothing about the agent's behavior changed; you've added a control plane on top.
Working directory
The session runs in the directory you launched from. Point it at the git repo you want the agent to work in — either cd there before adhdev launch, or open the repo from the launch flow in the dashboard.
Step 4 — Chat, and stay in control of approvals
In the session's input box, ask the agent to do something small and real. For example:
Look at this repo and add a one-line description to the top of the README explaining what it does.
Type it and press Enter, exactly as you would in the local terminal.
What you'll see:
- The agent's response streams into the dashboard in real time — the same tokens you'd see in the local terminal.
- When the agent wants to run a tool or edit a file, an ACTION REQUIRED banner appears with Approve and Reject buttons.
📸 [screenshot: ACTION REQUIRED approval banner with Approve / Reject]
Click Approve to let the edit through (or Reject to decline it). The decision travels over the peer-to-peer channel to the daemon, and the agent continues.
Why it matters: this is human-in-the-loop control. The agent never silently runs a command you didn't see — every tool call and file edit surfaces as an approval you own. That same banner is what lets you walk away from the keyboard and still stay in charge, which is exactly what the next step builds on.
Attach an image
The chat input accepts image attachments (up to 5 images, 10 MB each) — handy for pasting a screenshot of a bug or a design you want the agent to match.
Step 5 — Approve from your phone (Cloud)
Cloud Only
This step needs the Cloud version. Standalone is single-machine and local-only, so there's no remote surface to approve from. If you're on standalone, skip to Next steps — you've already seen the core loop.
The approval banner from Step 4 isn't tied to the machine the agent runs on. In cloud mode, sign in on your phone's browser at adhf.dev and the same Approve / Reject banner appears there — responsive layout, same peer-to-peer approval flow.
📸 [screenshot: mobile approval banner]
What you'll see: an agent pauses on a tool call at your desk; the approval shows up on your phone; you tap Approve; the agent continues.
Why it matters: you can kick off long-running work and step away. The agent stops and waits for you at every decision point, wherever you are. (Phones receive and answer approvals; dispatching new tasks stays a desktop/CLI action.)
Step 6 — Coordinate across machines with Repo Mesh (Cloud)
Cloud Only
Repo Mesh coordinates multiple same-account daemons and is available in the Cloud version only. It's the layer above a single dashboard — where one coordinator hands work to agents on many machines (or many isolated worktrees) and converges the results. See the full Repo Mesh guide for the concepts; here we just wire one up.
So far you've driven one agent in one session. Repo Mesh is what turns that into one person coordinating many agents. Here's the smallest end-to-end version.
1. Create a mesh for your repo. From inside the repo (so the git remote is auto-detected):
adhdev mesh create my-project --add-current--add-current also registers your current workspace as the mesh's first node. The command prints a mesh ID (e.g. mesh_abc123).
What you'll see: a confirmation with the mesh ID, the detected repo identity, and the branch, followed by "Next steps" hints.
2. Add another node. On a second machine (or as an isolated worktree), add it to the same mesh. A worktree keeps parallel agents from trampling each other's working tree:
adhdev mesh add-node mesh_abc123 --worktree --provider-priority claude-cli,codex-cli--provider-priority tells the node which agent to launch when a task doesn't name one — a node with no priority set will refuse to auto-launch rather than guess.
3. Confirm the shape of the mesh.
adhdev mesh show mesh_abc123 # nodes, policy, per-node launch readiness
adhdev mesh status mesh_abc123 # live per-node git health (branch, dirty, ahead/behind)📸 [screenshot: adhdev mesh status output, nodes with branch + clean/dirty]
Why it matters: you now have more than one workspace enrolled under one coordinator. From the cloud dashboard's Repo Mesh page (/mesh), you enqueue tasks against a mission, and idle nodes pull the work autonomously — Claude Code on one node, Codex on another. You don't push a task at a specific machine and babysit it; fast idle nodes drain the queue, and the coordinator watches for completion events instead of polling. Each task moves pending → assigned → completed (or failed).
Step 7 — Let the Refinery land the work (Cloud)
Cloud Only
The Refinery runs as part of Repo Mesh convergence.
Spawning parallel agents is the easy part. Merging what they produce is the hard part — and this is the part ADHDev exists to do.
When a task finishes on an isolated worktree branch, the Refinery converges that branch back into its base without a force-push, ever. It runs a sequence of gates: it loads the repo's convergence config, bootstraps the worktree, runs your repo's own validation (typecheck / tests / lint), applies a no-op guard and a patch-equivalence check, publishes any submodule commits, does a fast-forward-only merge into the base, and cleans up the worktree.
Every touched branch lands in exactly one final state, so nothing is silently left on a stray branch:
| Final state | Meaning |
|---|---|
merged_to_main | Converged and merged cleanly. |
pushed_feature_branch_needs_merge | Pushed, waiting on a merge you'll do. |
blocked_review | Held for a human — e.g. submodule commits not yet reachable from the submodule's origin. |
cleanup_candidate | Work is landed; the worktree can be removed. |
not_mergeable | Can't fast-forward. The Refinery refuses and asks for you rather than resolving a conflict blindly. |
📸 [screenshot: Refinery convergence log ending in merged_to_main]
Why it matters: this is the difference between "ten agents ran" and "ten branches landed safely." The Refinery is git-native and conservative on purpose — it validates against your gates and only ever fast-forwards. Anything it can't land cleanly (a real conflict, an unreachable submodule commit) comes back to you as not_mergeable or blocked_review, not a silent merge. You get parallelism without the merge-day hangover.
What you just did
You ran a real agent through ADHDev and stayed in control the whole way:
- Remote control + HITL — you drove a live session from the dashboard and approved every tool call (from your phone, in cloud mode).
- Any agent — you launched a CLI agent through a provider adapter; the same flow works for Codex, Gemini, IDEs over CDP, and ACP agents.
- Your machines — the agent ran on your own hardware, with its own auth, under your dashboard.
- Refinery — (cloud) you enrolled nodes in a mesh and saw how finished work converges to
mainthrough validation gates, with a clear final state for every branch.
Next steps
- Repo Mesh — the full model: missions, queue, ledger, and the Refinery in depth.
- Multi-Machine — linking laptop, desktop, and work box under one account.
- MCP Server — expose ADHDev sessions (and mesh coordination) as tools to another agent.
- CLI Agents — managing PTY sessions, scrollback, and restarts.
- Dashboard — panels, the machine switcher, and session sharing.
- Mobile — the responsive dashboard and approval flow on a phone.
- Compatibility & Caveats — what's verified vs. experimental.