dotbot-v3

Structured, auditable AI-assisted development for teams.

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. This is often called "vibe coding": fast output, zero accountability.

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

• Plan first, then execute -- Product specs become task roadmaps. Each task gets pre-flight analysis before implementation begins. Decisions, trade-offs, and rationale are documented as the work happens.
• Full session audit trail -- Every AI session, question, answer, and code change is recorded in version-controlled JSON files. Your team can review exactly what happened, when, and why.
• Operator steering -- Guide the AI mid-session through a heartbeat/whisper system. Send corrections or pivot instructions without interrupting its flow.
• Zero-dependency tooling -- The built-in MCP server and web UI are pure PowerShell. No npm, pip, or Docker required -- install and go.
• Designed for teams -- The entire .bot/ directory lives in your repo. Task queues, session histories, plans, and feedback are visible to everyone through git.
• Fully extensible -- Hooks, verification scripts, agents, skills, and workflows can all be customised per-project. The MCP server and UI can be mutated inside any project to fit your tech stack and dev workflow. Tech-specific profiles (e.g. dotnet) overlay additional tooling on top of the base system.

Prerequisites

Required:

• PowerShell 7+ -- Download
• Git -- Download
• Claude CLI -- Required for autonomous mode

Strongly recommended MCP servers:

• Playwright MCP -- Browser automation for UI testing and verification. Dotbot's autonomous agents use this to validate completed work.
• Context7 MCP -- Library documentation lookup. Agents use this to resolve API questions without hallucinating.

Windows ZIP download? If you downloaded this repo as a ZIP instead of cloning, you may need to run this first:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Quick Start

1. Install dotbot globally (one-time)

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

After installation, 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:

• MCP server for task management
• Web UI for monitoring (port 8686)
• Autonomous loop for Claude CLI
• Agents, skills, and workflows

3. Configure MCP Server

Add to your Claude/Warp MCP settings:

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

4. Start the UI

.bot\go.ps1

Opens the web dashboard at http://localhost:8686

Screenshots

Overview	Product	Workflow	Settings

Commands

dotbot help          # Show all commands
dotbot status        # Check installation status
dotbot init          # Add dotbot to current project
dotbot init -Force   # Reinitialize (overwrites existing)

Update Installation

cd ~/dotbot-install
git pull
pwsh install.ps1

Architecture

.bot/
├── systems/          # Core systems
│   ├── mcp/          # MCP server (task/session tools)
│   ├── ui/           # Web UI server
│   └── runtime/      # Autonomous loop
├── prompts/          # AI prompts
│   ├── agents/       # Specialized AI personas
│   ├── skills/       # Reusable capabilities
│   └── workflows/    # Step-by-step processes
├── state/            # Runtime state
│   ├── tasks/        # Task queue (todo/in-progress/done)
│   ├── sessions/     # Session tracking
│   └── product/      # Product documentation
├── hooks/            # Project-specific scripts
├── init.ps1          # Claude Code integration setup
└── go.ps1            # Launch UI server

MCP Tools

The dotbot MCP server provides:

Task Management: task_create, task_get_next, task_mark_done, task_list, task_get_stats

Session Management: session_initialize, session_get_state, session_get_stats

Development: dev_start, dev_stop

See .bot/README.md for full documentation.

Troubleshooting

dotbot command not found after install — Restart your terminal. The installer adds ~/dotbot/bin to your PATH, but the current session needs a restart to pick it up.

Script execution blocked on Windows — Run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser in PowerShell and try again.

PowerShell version error — dotbot requires PowerShell 7+. Check your version with $PSVersionTable.PSVersion and upgrade if needed.

License

MIT