Skip to main content
dotbot is a pure PowerShell framework with three cooperating systems: an MCP server that exposes tools to the AI agent, a web UI that gives the team visibility and control, and a runtime that manages AI process lifecycle, git worktree isolation, and two-phase execution. All three systems live inside the .bot/ directory that dotbot init creates in your project. Framework files can be re-applied at any time with dotbot init -Force without losing your workspace data.

​
Three core systems

​
MCP server

A pure PowerShell stdio MCP server implementing protocol version 2024-11-05. Tools are auto-discovered from tools/{tool-name}/ subdirectories — no registration is needed. The server exposes 33 tools across task management, session management, plans, decisions, steering, and dev lifecycle. Because tools are file-based, you can add custom tools by dropping a metadata.yaml and script.ps1 into a new subfolder.

​
Web UI

A pure PowerShell HTTP server with a vanilla JS frontend. Seven tabs: Overview, Product, Roadmap, Processes, Decisions, Workflow, Settings. The default port is 8686; the server auto-selects the next available port if 8686 is busy. Launch the UI with .bot/go.ps1 from your project root.

​
Runtime

Manages AI CLI invocations as tracked processes. Process types include analysis, execution, kickstart, planning, commit, and task-creation. The runtime handles git worktree isolation and normalises invocations across Claude, Codex, and Gemini through a unified provider abstraction layer.

​
.bot/ directory layout

The full .bot/ directory tree after dotbot init: 
.bot/
├── systems/            # Core systems
│   ├── mcp/            # MCP server (stdio, auto-discovers tools)
│   │   ├── tools/      # One folder per tool (metadata.yaml + script.ps1)
│   │   └── modules/    # NotificationClient, PathSanitizer, SessionTracking
│   ├── ui/             # Pure PowerShell HTTP server + vanilla JS frontend
│   └── runtime/        # Autonomous loop, worktree manager, provider CLIs
│       └── ProviderCLI/  # Stream parsers for Claude, Codex, Gemini
├── workflows/          # Installed workflows (each with workflow.yaml + scripts)
│   └── <name>/         # workflow.yaml, scripts/, prompts/, context/
├── defaults/           # Default settings + provider configurations
├── prompts/            # AI prompts
│   ├── agents/         # Specialized personas (implementer, planner, reviewer, tester)
│   ├── skills/         # Reusable capabilities (unit tests, status, verify)
│   └── workflows/      # Numbered step-by-step processes
├── workspace/          # Version-controlled runtime state
│   ├── tasks/          # Task queue (todo/analysing/analysed/in-progress/done/…)
│   ├── sessions/       # Session history + run logs
│   ├── product/        # Product docs (mission, tech stack, entity model)
│   ├── plans/          # Execution plans
│   ├── feedback/       # Structured problem logs (pending/applied/archived)
│   └── reports/        # Generated reports
├── hooks/              # Project-specific scripts (dev, verify, steering)
├── init.ps1            # IDE integration setup
└── go.ps1              # Launch UI server

​
Source vs. deployed

The workflows/ directory in the dotbot repository is the canonical source for all framework files. When you run dotbot init, framework files are copied from workflows/default/ (and any named stacks) into .bot/.
  • You can freely edit files under .bot/ to customise your project. Run dotbot init -Force to receive framework upgrades — this overwrites framework files while preserving all workspace data.
  • Stacks like dotnet-blazor extend other stacks via extends chains. Settings deep-merge in this order: default → workflows → stacks. Stack-level settings win over workflow-level settings, which win over defaults.

​
Runtime state: .bot/.control/ vs .bot/workspace/

dotbot separates ephemeral machine-local state from durable version-controlled state into two distinct directories.

​
.bot/.control/ — gitignored, machine-local

This directory is always gitignored. It contains:
ItemDescription
settings.jsonUser-local settings overrides. Wins over settings.default.json.
processes/Process registry entries tracking active AI CLI invocations.
logs/Log files (retention controlled by logging.retention_days).
Session locksTransient lock files preventing concurrent workflow execution.
Do not commit anything from .bot/.control/.

​
.bot/workspace/ — version-controlled

This directory is committed to git. Every team member sees the same task queue, session history, product documents, and plans through standard git history.
DirectoryContents
tasks/Task files organised by status sub-folder (todo/, analysing/, analysed/, in-progress/, done/, needs-input/, skipped/, split/).
sessions/Session log files and JSONL audit trails (token counts, costs, turn boundaries, errors).
product/Product documents: mission statement, tech stack definition, entity model.
plans/Implementation plan markdown files, linked to tasks by ID.
feedback/Structured problem logs in three states: pending/, applied/, archived/.
reports/Generated reports (cost summaries, progress reports).
Committing workspace/ to git means every task, question, answer, decision, and code change is auditable by your entire team through standard git tooling.

​
Git worktree isolation

Each prompt and prompt_template task runs in its own git branch (task/{short-id}-{slug}) and a separate worktree directory (../worktrees/{repo}/task-{short-id}-{slug}/). On completion, the task branch is squash-merged back to the main branch and the worktree is cleaned up. This approach keeps the main working tree clean during concurrent execution and makes per-task rollback trivial. script, mcp, and task_gen tasks skip worktree isolation and run directly in the project root. This is safe because those task types do not invoke the AI and make deterministic, auditable changes that do not require branch isolation.