Skip to main content
dotbot wraps AI coding in a managed, auditable workflow engine. This guide takes you from a fresh install to running your first AI-assisted pipeline — no npm, pip, or Docker required.
1

Install dotbot

Use a package manager. Each installs a self-contained copy and puts dotbot on your PATH:
Or install from a source checkout. Clone the repository and run the bootstrap script:
bootstrap.ps1 drops a small PATH shim into ~/.local/bin (Linux/macOS) or %LOCALAPPDATA%\Microsoft\WindowsApps (Windows). The shim contains no framework code; it routes to a dotbot checkout or to a project-local runtime. After installing, restart your terminal so the dotbot command is on your PATH.
On Windows, if PowerShell blocks the script due to your execution policy, run this first:
2

Set the active runtime

Package-managed installs resolve the framework from their own location, so you can skip this step. Source-checkout shims need DOTBOT_HOME to point at the checkout:
Persist it in your shell profile, or with setx DOTBOT_HOME <path> on Windows. Confirm the active install:
3

Add dotbot to your project

Navigate to your project directory and initialize dotbot:
This creates a .bot/ directory with two children: a tracked workspace/ tree (task queue, plans, decisions, sessions, product docs) and a .gitignore for machine-local paths. Framework code is not copied; the runtime resolves it from your active install. Workflow and stack selection is recorded in .bot/.control/settings.json.To initialize with a specific workflow or stack, pass flags:
To vendor a per-project copy of the runtime so the project runs without a machine-level DOTBOT_HOME, use dotbot init --copy-runtime, or dotbot install runtime for a project that is already initialized. This copies the runtime into .bot/runtime.
4

Start the web dashboard

Launch the runtime and built-in web dashboard:
The dashboard opens at http://localhost:8686 by default. If that port is busy, dotbot scans for the next available port. Pass --open to open the dashboard in your default browser.The dashboard gives you seven tabs: Overview, Product, Roadmap, Processes, Decisions, Workflow, and Settings.
5

Run a workflow

Start the default workflow for a new project:
To see all available workflows and stacks installed in your project, run:
Run dotbot doctor at any time to scan for stale locks, orphaned worktrees, settings issues, and task queue health problems.

​
Next steps

Core concepts

Understand workflows, stacks, task types, and how settings compose.

Configure providers

Switch between Claude, Codex, and Antigravity. Set models per task.

MCP server

Explore the 31 built-in MCP tools for task and session management.

Command reference

Full reference for every dotbot CLI command and flag.