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. The install command is the same either way — what differs is the dashboard URL and account flow.

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

Cloud is the default path below — it's what the install script sets up for you automatically. If you'd rather stay fully local with no account, look for the Standalone box under Step 1 and Step 2; it's a fully supported alternative, not a fallback.

---

Step 1 — Install the CLI

Run the install script. It detects your platform, installs Node.js if needed, puts the adhdev CLI on your PATH, and — for Cloud — walks you through sign-in right away.

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.

Cloud

The install script above already runs the setup wizard for you (adhdev setup) right after installing — it opens a browser tab for device authorization against adhf.dev, signs you in with GitHub or Google, registers this machine, and starts the daemon. If that finished, skip ahead to Step 3 below.

You only need to run the wizard yourself if it didn't run automatically (ADHDEV_NO_SETUP=1, a non-interactive shell, or you're finishing up after a command not found fix):

adhdev setup

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, registers the machine, and offers to start the daemon (default: yes).

Standalone

Standalone doesn't use the setup wizard at all — there's no account to create. Skip straight to Step 2 below and run adhdev standalone directly.

---

Step 2 — Open the dashboard

Cloud

If setup already started the daemon for you, it's running — open https://adhf.dev in your browser and sign in if prompted, then skip to What should happen below.

Otherwise, start it yourself:

adhdev daemon

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

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.

Standalone

adhdev standalone

This starts a single local server — daemon and dashboard together — on http://localhost:3847 and opens it in your browser automatically.

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>

---

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-cli
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
• 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)
• Agent-driven Repo Mesh setup — hand a page to your agent and let it wire up the mesh
• 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

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.