adhd

A personal AI assistant that runs entirely on your machine — one process, no database, no cloud except the model API you point it at. From a single chat box it can read and write files, run shell commands, search and browse the web, remember things about you across sessions, schedule tasks, and automate anything you do repeatedly.

It talks to DeepSeek, Anthropic, Gemini, or any OpenAI-compatible API, and serves a ChatGPT-style UI at http://127.0.0.1:8787. Your API keys never leave that address.

▌ you  find nearby restaurants

✓ recall       user/location
✓ web_search   places · "restaurants Homagama, Sri Lanka"
✓ browser      read · https://…/the-one-it-picked
Here are a few near you: …

Quick start

Requires Bun installed.

npm install -g adhd-cli
adhd               # opens http://127.0.0.1:8787

Or run it once without installing: bunx adhd-cli.

Add an API key in Settings (or put it in .env — see Configuration) and start chatting. You only need a key for the provider you actually use.

From source

bun install
bun start          # builds the frontend, then opens http://127.0.0.1:8787

• bun run dev:web — rebuild the frontend on save while developing.
• bun run build — compile a standalone ./adhd binary.
• bun test — run the test suite.

What it can do

• Streams answers with a live, collapsible trace of every tool call.
• Falls back to the next model automatically if one is rate-limited mid-turn, without losing work or re-running tools.
• Reads and writes files, runs shell/PowerShell commands, and searches or browses the web — each capability can be switched off independently in Settings.
• Renders rich replies: images and galleries, video, tables, charts, metric cards, progress bars, Mermaid diagrams, and maps with directions.
• Shows your own local files inline, from folders you explicitly allow.
• Remembers durable facts about you across sessions.
• Schedules tasks that fire while adhd is open, with desktop notifications.
• Builds visual Flows — reusable workflows you wire up once, then run from chat, on a schedule, or with a button.
• Tracks its own progress on multi-step tasks with a visible, ticking checklist.
• Loads skills — extra instructions the model pulls in only when a task needs them.
• Delegates large subtasks to subagents, or grinds through a hard task across several passes.
• Shows a live meter of what's filling the model's context window, and a Compact now button to shrink it.
• Light, dark, and system themes.

Tools

Tool	What it does	Asks first
read_file / write_file	Read or write a text file	—
list_dir / grep / glob	List, regex-search, or glob for files	—
bash / powershell	Run a shell command	yes
run_script	Write and run a Bun/TypeScript snippet	yes
web_search	Search the web — pages, images, videos, places, shopping, news	—
browser	Drive headless Chrome: read a page as clean markdown, snapshot its elements, screenshot, fill/click/type/press, eval JS	on changes
search_files	Find your own local images/videos/docs to show	—
remember / recall	Save or load a durable memory	—
todo_write	Show and update a live task checklist	—
schedule	Add, list, or remove scheduled tasks	—
use_skill	Load a skill's full instructions	—
spawn_agent	Delegate a self-contained subtask to a subagent (subagents can't spawn further)	—
loop_task	Iterate a hard task across multiple passes	yes
run_flow	Run a saved Flow by name	—
render_ui	Draw a rich block — image, gallery, table, chart, map, sources	—
ask_user	Ask a multiple-choice question	interactive

Tools from any MCP server you add appear here too, named <server>_<tool> — see Extending.

Flow tool nodes get the same file/shell/web tools, minus spawn_agent/loop_task/run_flow (a Flow can't call another Flow). Flow prompt nodes get no tools at all.

Flows

A Flow is a workflow you draw on a canvas, open from the Flows button — each node is a plain function, not an agent. It runs server-side and is saved to ~/.adhd/flows.json.

Node	What it does
Start / End	Where the run begins and stops.
Prompt	One model call, no tools — deterministic by design.
If	Asks the model a yes/no question and follows the matching branch.
Switch	Sorts the input into one of your named cases (plus an automatic else).
Tool	Runs exactly one tool, with fields generated from that tool's own arguments.
Merge	Waits for every incoming branch, then joins their outputs for the next node.

Each node passes its output to the next; {{prev}} in a field is replaced by it, and {{key}} reads back any earlier node you gave that output key. Branches that fan out run in parallel; a Merge node fans them back in. A run can be paused, resumed, or stopped mid-flight, and a 30-step cap stops any accidental cycle.

Three ways to run one: the Run button, asking in chat, or scheduling it (Settings → Schedule, prompt flow:<id>). A few example Flows are seeded once on first launch — delete them and they stay deleted.

Permissions

Settings → Permissions controls when adhd stops to ask before doing something:

• Ask every time — every side effect gets a confirmation card, no exceptions.
• Normal (default) — asks before anything that changes your machine, minus what you've already approved.
• Approve everything — never asks. For a sandbox you don't mind losing.

Flow tool nodes are the one exception: you built the graph and pressed Run, so they execute without asking. A confirmation nobody answers within 5 minutes is declined automatically, so a scheduled run doesn't hang waiting for a click that will never come.

Configuration

Environment

Create a .env in the project root:

DEEPSEEK_API_KEY=sk-...   # required — the model
SERPER_API_KEY=...        # optional — enables web_search
MAPTILER_KEY=...          # optional — map tiles (falls back to OpenStreetMap)
ADHD_PORT=8787             # optional — server port

DEEPSEEK_API_KEY and SERPER_API_KEY can also be set from Settings, stored in ~/.adhd/secrets.json and never sent back to the browser.

config.json

Merged from ~/.adhd/config.json, then ./.adhd/config.json (project wins). Everything is optional:

{
  "model": "deepseek-v4-flash",       // "<provider>:<id>"; a bare id means DeepSeek
  "fallbackModel": [],                 // string or string[], tried in order if rate-limited
  "systemPrompt": "...",               // replaces the default system prompt
  "localRoots": ["/path/..."],         // folders the file tools may touch (default: home)
  "allowedCommands": ["bash:git"],     // "always allow" list, built from the approval prompt
  "permissionMode": "normal",          // "ask" | "normal" | "auto"
  "capabilities": { "shell": false },  // switch a whole feature group off
  "disabledTools": ["run_script"],     // turn off individual tools
  "mcpServers": {                      // stdio MCP servers, loaded at startup
    "notes": { "command": "npx", "args": ["-y", "@some/notes-mcp"], "trust": "ask" }
  }
}

What's stored where (~/.adhd/)

Path	What
secrets.json	API keys
config.json	the settings above
memory/	durable memories
schedule.json	scheduled tasks
flows.json	saved Flows
tools/<name>.ts	your custom tools
skills/<name>/SKILL.md	your skills

Extending

• Tools: drop a file at ~/.adhd/tools/<name>.ts that default-exports an AI SDK tool(). The filename becomes the tool name.
• Skills: add ~/.adhd/skills/<name>/SKILL.md with name and description frontmatter; the model loads the body on demand.
• MCP servers: add one in Settings → MCP servers, or write it into config.json yourself. adhd connects over stdio at startup and exposes its tools as <server>_<tool>. Mark a read-only server "trust": "read" so its tools don't need approval each time — anything else asks, the same as bash. Remote HTTP/SSE servers aren't supported, stdio only.

Architecture

One Bun process serves the UI over SSE and runs the agent in-process — no separate backend, no database.

• web/ — the frontend (chat UI + the Flows canvas), bundled by Vite into public/.
• src/web.ts — the HTTP/SSE server: chat, settings, and flow routes.
• src/setup.ts — assembles config, models, tools, and the system prompt into one agent.
• src/agent.ts — the turn loop: streams text and tool calls, retries, falls back between models.
• src/tools.ts, src/browser.ts — the built-in file/shell/web tools and the headless-Chrome browser tool.
• src/flows.ts — the Flow graph runner.
• src/mcp.ts — connects to MCP servers and exposes their tools, approval-gated.
• src/memory.ts, src/skills.ts, src/scheduler.ts, src/subagent.ts, src/loop.ts — memory, skills, scheduling, subagents, and multi-pass tasks.
• src/sanitize.ts — strips injection vectors before content reaches the model or the UI.

The server only accepts loopback Host headers (no DNS rebinding), requires state-changing requests to be same-origin (CSRF), and serves local files only from folders you've allowed, under a locked-down CSP.

License

MIT © 2026 Adhishtanaka Kulasooriya