Getting Started

This guide takes you from zero to chatting with your first AI agent through ADHDev. It should take about five minutes.

ADHDev runs in two modes. Pick one before you start — the install command is the same, but the dashboard URL and account flow differ.

	Standalone	Cloud
Account	None	GitHub or Google
Dashboard	http://localhost:3000	https://adhf.dev
Best for	Single machine, local use, privacy	Multi-machine, remote access, sharing

If you're unsure, start with Standalone. You can switch later without uninstalling.

---

Step 1 — Install the CLI

Run the install script. It detects your platform, installs Node.js if needed, and puts the adhdev CLI on your PATH.

macOS / Linux:

curl -fsSL https://adhf.dev/install | sh

Windows (PowerShell):

irm https://adhf.dev/install.ps1 | iex

macOS / Linux (Homebrew):

brew tap vilmire/adhdev
brew install adhdev

Homebrew bundles its own Node.js runtime, so this keeps adhdev isolated from your global npm setup. (The install script above already uses Homebrew automatically when it's available on macOS.)

Via npm (any platform):

npm install -g adhdev

WARNING

On Windows, global npm install on Node.js 24+ is currently unsupported. The PowerShell installer bootstraps a portable Node.js 22 runtime for you.

What should happen:

adhdev --version

prints a version number. If you get command not found, open a new terminal window — the installer registers the PATH permanently (User scope), so it survives reboots. If it still fails after a reboot, see Windows PATH troubleshooting.

Then run the first-run wizard:

adhdev setup

For Standalone, choose the local-only option — no browser sign-in is required. For Cloud, the wizard opens a browser tab for device authorization against adhf.dev. Sign in with GitHub or Google.

TIP

Cloud sign-in requires a verified email from the OAuth provider. If your GitHub/Google account has no verified email, the sign-in will be rejected rather than guessing which account to link.

What should happen: The wizard prints Setup complete and tells you which command starts the daemon.

---

Step 2 — Open the dashboard

Standalone

adhdev standalone

The standalone command starts both the daemon (localhost:3847) and the dashboard (localhost:3000).

Open http://localhost:3000 in your browser.

What should happen: A dashboard loads showing an empty machine list with your local machine "online". No login screen.

If you want LAN access from another device on your network:

adhdev standalone --host 0.0.0.0 --token <some-secret>

Cloud

adhdev daemon

The daemon connects to api.adhf.dev, registers this machine, and prints its machine ID.

Open https://adhf.dev in your browser. Sign in if prompted.

What should happen: The dashboard's machine list shows your machine as online within a few seconds, with a green indicator. You'll see "P2P connected" once the WebRTC channel comes up.

If the machine doesn't appear:

adhdev doctor

This checks the daemon process, the WebSocket connection, and the local provider registry. Most issues will be flagged with a specific fix.

---

Step 3 — Pick a provider

A provider is ADHDev's adapter for one AI agent. Two categories matter for first-time use:

• CLI providers — terminal-based agents like Claude Code, Codex CLI, Antigravity CLI, Hermes CLI. The daemon runs them under a PTY and pipes the terminal to the dashboard.
• IDE providers — running editors like Cursor, VS Code, Antigravity, Windsurf. The daemon attaches via Chrome DevTools Protocol (CDP) and reads / writes the agent panel inside the IDE.

To see what ADHDev detects on your machine:

adhdev detect

What should happen: A list with installed: yes/no for each known provider. Anything marked yes is ready to launch.

Recommended starting points

For the smoothest first run, pick whichever of these you already have installed:

1. Claude Code (CLI) — adhdev launch claude
2. Codex CLI — adhdev launch codex
3. Cursor (IDE) — adhdev launch cursor

adhdev launch opens the agent under the daemon. For IDEs it relaunches the editor with CDP enabled.

WARNING

adhdev launch <ide> will close and reopen the IDE so it can start with CDP enabled. Save your work first.

What should happen: The dashboard sprouts a new card for the agent (or a new tab inside the machine's view) and shows its terminal output or IDE state in real time.

---

Step 4 — Send your first prompt

In the dashboard, click the card for the agent you just launched. You'll get one of two views:

• CLI view — a live terminal with an input box at the bottom. Type a prompt and press Enter (or click Send) exactly as you would in the local terminal.
• IDE view — a chat panel mirroring the agent panel inside your editor. Type a prompt and click Send.

Try something simple:

List the files in the current directory and tell me what kind of project this is.

What should happen:

• The provider streams the agent's response into the dashboard in real time.
• For CLI agents, you see the same tokens you'd see in the local terminal.
• For IDE agents, the chat bubble updates as the model generates.
• Any tool / approval prompt the agent raises is mirrored to the dashboard with the same approve/deny buttons.

If you see the prompt arrive but no response, check:

adhdev status         # daemon healthy?
adhdev provider list  # provider loaded?
adhdev doctor         # any auth or network issue?

If the agent itself asks for an API key or login (Anthropic, OpenAI, Google, etc.), handle that in the agent's own UI or ~/.config. ADHDev does not store or proxy those credentials — each tool keeps its own auth.

---

You're set

You now have a daemon running, the dashboard connected, and at least one agent talking back over ADHDev's transport.

Where to go next

• Dashboard guide — panels, machine switcher, session sharing
• CLI agents — managing PTY sessions, scrollback, restart
• Remote view — control an IDE from a different device (Cloud only)
• Multi-machine — linking laptop + desktop + work box (Cloud only)
• Compatibility & caveats — what's verified vs. what's experimental
• Troubleshooting — common failures and fixes

Going deeper

• Provider Guide — write a custom provider
• Provider SDK — manifest, TUI primitives, debugging
• Architecture — daemon, dashboard, P2P, server (canonical source for infra and timing values)

Uninstall

adhdev uninstall     # stops the daemon, removes ~/.adhdev/
npm uninstall -g adhdev   # also removes the CLI itself

To switch accounts without losing local state, use adhdev logout instead.