dotbot

Structured, auditable AI-assisted development for teams.

Overview

What is dotbot?

Most AI coding tools give you a result but no record of how you got there - no trail of decisions for teammates to follow, no way to continue work across sessions, and no framework for managing large projects.

dotbot wraps AI-assisted coding in a managed, transparent workflow where every step is tracked:

Multi-workflow platform

Workflow-driven pipelines - Define multi-step pipelines in workflow.yaml manifests with tasks, dependencies, form configuration, MCP servers, and environment requirements. A project can have multiple workflows installed simultaneously, each run, re-run, and stopped independently.
Typed task system - Tasks can be prompt (AI-executed), script (PowerShell, no LLM), mcp (tool call), task_gen (generates sub-tasks dynamically), or prompt_template (AI with a workflow-specific prompt). Script, MCP, and task_gen tasks bypass the AI entirely - they auto-promote past analysis, skip worktree isolation, and skip verification hooks. This enables deterministic pipeline stages within AI-orchestrated workflows.
Enterprise registries - Teams publish workflows, stacks, tools, and skills in git-hosted or local registries. dotbot registry add links a registry (private or public); dotbot init -Workflow registry:name installs from it. Registries are validated against a registry.yaml manifest with version compatibility checks and auth-failure hints for GitHub, Azure DevOps, and GitLab.
Workflows and stacks - Workflows (e.g. kickstart-via-jira) define operational pipelines - what dotbot does. Stacks (e.g. dotnet, dotnet-blazor) add tech-specific skills, hooks, and MCP tools - what tech the project uses. Stacks compose additively with extends chains. Settings deep-merge across default -> workflows -> stacks.

Execution engine

Two-phase execution - Analysis resolves ambiguity, identifies files, and builds a context package. Implementation consumes that package and writes code. Tasks flow: todo -> analysing -> analysed -> in-progress -> done.
Per-task git worktree isolation - Each task runs in its own worktree on an isolated branch, squash-merged back to main on completion.
Per-task model selection - Tasks can specify a model (e.g. Sonnet for simple tasks, Opus for complex ones) that overrides the process-level default. Use cheaper models where they suffice to reduce token spend.
Multi-slot concurrent execution - The workflow engine runs multiple tasks from the same workflow in parallel with slot-aware locking, shortening wall-clock time for large task queues.
Multi-provider - Switch between Claude, Codex, and Gemini from the Settings tab. Each provider has its own CLI wrapper, stream parser, and model configuration.
Configurable permission modes - Choose how each provider handles permission checks during autonomous execution. Claude supports bypass and auto mode (AI-classified safety); Codex supports bypass and full-auto; Gemini supports YOLO and auto-edit. The dashboard detects installed providers, their versions, and authentication status.

Dashboard and observability

Web dashboard - Seven-tab UI (Overview, Product, Roadmap, Processes, Decisions, Workflow, Settings) with workflow cards showing progress pills, per-workflow run/stop controls, and pipeline-phase filtering.
Manifest-driven kickstart - The kickstart dialog is driven by workflow.yaml form modes with visibility flags for prompt, file upload, interview, and auto-workflow options.
JSONL audit trail - Session logs capture token counts, costs, turn boundaries, wall-clock gaps, agent completion reasons, and error details. Every AI session, question, answer, and code change is version-controlled.
Project health diagnostics - dotbot doctor scans for stale locks, orphaned worktrees, settings integrity, dependency issues, and task queue health.

Collaboration and control

Operator steering - Guide the AI mid-session through a heartbeat/whisper system. /status and /verify slash commands work during autonomous execution.
Kickstart interview - Guided requirements-gathering flow that produces product documents, then generates a task roadmap automatically.
Human-in-the-loop Q&A - When a task needs human input, dotbot routes questions to stakeholders via Teams, Email, or Jira.
Designed for teams - The entire .bot/ directory lives in your repo. Task queues, session histories, plans, and feedback are visible to everyone through git.

Foundation

Zero-dependency tooling - MCP server and web UI are pure PowerShell. No npm, pip, or Docker required. Cross-platform on Windows, macOS, and Linux.
Security - PathSanitizer strips absolute paths from AI output, privacy scan covers the full repo, and pre-commit hooks run gitleaks on staged files.

Prerequisites

Required:

PowerShell 7+ - Download
Git - Download
AI CLI (at least one) - Claude CLI, Codex CLI, or Gemini CLI

Recommended MCP servers:

Playwright MCP - Browser automation for UI testing and verification.
Context7 MCP - Library documentation lookup to reduce hallucination.

Windows ZIP download? Run this first:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Quick Start

1. Install dotbot globally (one-time)

One-liner (recommended):

irm https://raw.githubusercontent.com/andresharpe/dotbot/main/install-remote.ps1 | iex

<details> <summary><strong>Alternative install methods</strong></summary>

PowerShell Gallery:

Install-Module dotbot -Scope CurrentUser

Scoop (Windows):

scoop bucket add dotbot https://github.com/andresharpe/scoop-dotbot
scoop install dotbot

Homebrew (macOS/Linux):

brew tap andresharpe/dotbot
brew install dotbot

Git clone:

cd ~
git clone https://github.com/andresharpe/dotbot dotbot-install
cd dotbot-install
pwsh install.ps1

</details>

Restart your terminal so the dotbot command is available.

2. Add dotbot to your project

cd your-project
dotbot init

This creates a .bot/ directory with the MCP server, web UI, autonomous runtime, agents, skills, and workflows.

Workflows and Stacks

dotbot init -Workflow kickstart-via-jira               # Install a workflow
dotbot init -Stack dotnet-blazor,dotnet-ef             # Install stacks
dotbot init -Workflow kickstart-via-jira -Stack dotnet  # Both
dotbot list                                            # List available workflows and stacks

Workflow - Defines a multi-step pipeline with tasks, dependencies, scripts, and form configuration via workflow.yaml. A project can have multiple workflows installed. Each can be run and re-run independently (dotbot run <name>).
Stack (composable) - Adds tech-specific skills, hooks, verify scripts, and MCP tools. Stacks can declare extends to auto-include a parent (e.g. dotnet-blazor extends dotnet).

Apply order: default -> workflows -> stacks (dependency-resolved). Settings are deep-merged; files are overlaid.

Enterprise Registries

Teams can publish workflows, stacks, tools, and skills in a git repo with a registry.yaml manifest:

dotbot registry add myorg https://github.com/myorg/dotbot-extensions.git
dotbot registry add myorg C:\repos\myorg-dotbot-extensions  # Local path
dotbot registry update                                       # Update all registries
dotbot registry update myorg                                 # Update one registry
dotbot init -Workflow myorg:custom-workflow                  # Use from registry

3. Configure MCP Server

Add to your AI tool's MCP settings (Claude, Warp, etc.):

{
  "mcpServers": {
    "dotbot": {
      "command": "pwsh",
      "args": ["-NoProfile", "-File", ".bot/systems/mcp/dotbot-mcp.ps1"]
    }
  }
}

4. Start the UI

.bot\go.ps1

Opens the web dashboard (default port 8686, auto-selects next available if busy).

Screenshots

Overview Product Workflow Settings

Commands

dotbot help                    # Show all commands
dotbot init                    # Add dotbot to current project
dotbot init -Force             # Reinitialize (preserves workspace data)
dotbot init -Workflow <name>   # Install with a workflow
dotbot init -Stack <name>      # Install with a tech stack
dotbot list                    # List available workflows and stacks
dotbot run <workflow>          # Run/rerun a workflow
dotbot workflow add <name>     # Add a workflow to existing project
dotbot workflow remove <name>  # Remove an installed workflow
dotbot workflow list           # List installed workflows
dotbot registry add <n> <src>  # Add an enterprise extension registry
dotbot registry update [name]  # Update registry (all or named)
dotbot registry list           # List registries and available content
dotbot doctor                  # Run project health checks
dotbot status                  # Check installation status
dotbot update                  # Update global installation

Architecture

.bot/
├── systems/            # Core systems
│   ├── mcp/            # MCP server (stdio, auto-discovers tools)
│   │   ├── tools/      # One folder per tool (metadata.yaml + script.ps1)
│   │   └── modules/    # NotificationClient, Path

Dotbot

Install / Use

README