> ## Documentation Index > Fetch the complete documentation index at: https://docs.dotbot.ch/llms.txt > Use this file to discover all available pages before exploring further. # dotbot architecture and directory layout > How dotbot's MCP server, web UI, and autonomous runtime fit together, plus a complete reference for the .bot/ directory tree and runtime state separation. 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. Framework files live in the dotbot install directory pointed to by `$env:DOTBOT_HOME` and are resolved at runtime by a layered content resolver - no framework code is copied into your project by default. Running `dotbot init` creates only the project's `.bot/workspace/` tree (tracked in git) and a `.bot/.gitignore`. *** ## Three core systems ### MCP server A pure PowerShell stdio MCP server implementing protocol version 2024-11-05. Tools are auto-discovered from `src/mcp/tools/{tool-name}/` subdirectories, and no registration is needed. The server exposes 31 tools across task management, session management, plans, decisions, steering, workflow control, and dev lifecycle. Because tools are file-based, you can add custom tools by dropping a `metadata.json` 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 `dotbot go` from your project root. ### Runtime Manages AI CLI invocations as tracked processes. The runtime handles git worktree isolation and coordinates two-phase execution (analysis then execution) for each task. AI provider invocations are normalised through a pluggable adapter layer in Dotbot.Harness, which ships adapters for Claude Code, Codex, Antigravity, Copilot, and OpenCode. An HTTP control plane (Dotbot.Runtime) exposes workflow run state over a local endpoint consumed by the dashboard, CLI commands, and the MCP server. *** ## `.bot/` directory layout `dotbot init` creates two items: a `workspace/` tree tracked in git, and a `.gitignore` that excludes machine-local state. ``` .bot/ ├── workspace/ # Version-controlled project state │ ├── tasks/ │ │ ├── workflow-runs/ # Tasks owned by a workflow run │ │ └── standalone/ # Tasks run outside a workflow │ ├── sessions/ │ │ ├── history/ # Completed session audit trails (tracked) │ │ └── runs/ # Active session logs (gitignored) │ ├── plans/ # Implementation plan files │ ├── product/ # Product docs (mission, tech stack, entity model) │ ├── decisions/ │ │ ├── accepted/ │ │ ├── deprecated/ │ │ ├── proposed/ │ │ └── superseded/ │ ├── pilot/ # Pilot experiment artifacts │ └── reports/ # Generated cost and progress reports └── .gitignore # Excludes .control/, .handoffs/, session run logs ``` Three optional directories appear under `.bot/` under specific conditions. | Directory | When it appears | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.control/` | Created and gitignored when the runtime starts or when a workflow/stack is selected during `dotbot init`. Holds `settings.json`, `runtime.json`, port files, and logs. | | `content/` | Populated when a workflow or stack ships project-tier overrides, or when content is installed from a registry. Overrides under `.bot/content///` take precedence over the matching framework content in `$env:DOTBOT_HOME`. | | `runtime/` | Populated only when `dotbot init --copy-runtime` is used. Contains a self-contained copy of the framework for projects that cannot rely on a shared `$env:DOTBOT_HOME`. | *** ## Content resolution Framework content (agents, skills, prompts, workflows, stacks, MCP tools, hooks) lives in the dotbot install directory at `$env:DOTBOT_HOME`. The layered content resolver checks `.bot/content///` first; if no project-level override exists, it falls back to `$env:DOTBOT_HOME/content///`. Your project only needs to include the files it wants to customise. Stacks follow the same pattern. A stack like `dotnet-blazor` declares `extends: dotnet` in its manifest; the resolver applies settings in dependency order and deep-merges them: framework defaults, then workflow settings, then stack settings. Settings declared closer to the project always win. *** ## Runtime modules The runtime is implemented as 19 PowerShell modules under `src/runtime/Modules/` in the dotbot install directory. | Module | Purpose | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Dotbot.Content | Layered content resolver. Looks up agents, skills, prompts, workflows, stacks, and hooks from `.bot/content/` before falling back to `$env:DOTBOT_HOME/content/`. | | Dotbot.Core | Foundation helpers: path resolution, workspace identity GUID, ANSI-escape sanitization, and absolute-path stripping for logs. No dependencies on other Dotbot.\* modules. | | Dotbot.Executor | Plugin executor discovery and dispatch. Reads `metadata.json` from each executor plugin folder to map task types to their handler. Adding a new task type requires only a new plugin folder. | | Dotbot.Handoff | Task-scoped handoff artifacts for human-in-the-loop pauses. Writes a compact handoff before a task enters `needs-input`; the next session attempt resumes from that artifact without creating a new task. | | Dotbot.Harness | Pluggable AI harness layer. Registers per-provider adapters (Claude Code, Codex, Antigravity, Copilot, OpenCode) that normalise process launch, stream parsing, and exit-code classification. Replaces the old Dotbot.Provider module. | | Dotbot.Hook | Transition hook discovery and dispatch. Hooks live on disk under the project or framework hook directories and are discovered at dispatch time. | | Dotbot.Logging | Structured JSONL logging with levels (Debug, Info, Warn, Error, Fatal) and automatic log rotation. Writes to `.bot/.control/logs/dotbot-{date}.jsonl`. | | Dotbot.Notification | Client for external notifications (Teams, Email, Jira) via the DotbotServer surface. Used by the `needs-input` transition and the notification poller. | | Dotbot.Process | Process lifecycle management: a business-level process registry for long-running runners and a platform-aware child process launcher used by `go` and the CLI launchers. | | Dotbot.Runtime | Per-project HTTP control plane. Owns the listener loop, authentication, routing, and workflow-run state. Composed of HttpServer, ControlPlaneClient, EndpointDiscovery, and Lifecycle. | | Dotbot.SessionTracking | Session ID tracking for AI provider session continuation when a task is paused for human input and later resumed. | | Dotbot.Settings | Four-tier settings loader and deep-merge utilities: framework default, project override, user-level, and `.control/settings.json`. Missing files are silently skipped. | | Dotbot.Task | Task lifecycle: prompt building, completion detection, crash recovery, post-script hooks, merge-failure escalation, and the interactive interview loop. | | Dotbot.TaskFile | Atomic, lock-protected, retry-aware mutations for task JSON files. Writes are crash-safe via temp-file rename; cross-state moves are atomic-then-cleanup. | | Dotbot.TaskIndex | On-demand task index that reads task files fresh from disk on each access, with no in-process caching. | | Dotbot.TaskInput | Shared in-process transitions for accepting human input on tasks, using the same atomic task-file primitives as the rest of the runtime. | | Dotbot.Theme | Console theme engine. Reads the selected theme from `.control/ui-settings.json` and provides themed output helpers used across CLI and runtime surfaces. | | Dotbot.Workflow | Workflow manifest utilities: parse `workflow.json`, create initial task sets, and merge MCP server configurations. Used by init, workflow-add, and workflow-run. | | Dotbot.Worktree | Git worktree lifecycle management. Creates per-task branches and worktrees at analysis start, squash-merges them to the main branch on completion, and cleans up the worktree directory. | *** ## HTTP runtime Dotbot.Runtime runs as an in-process HTTP server when `dotbot go` or `dotbot serve` starts. It publishes its address to `.bot/.control/runtime.json` so the UI server, MCP server, and CLI commands like `dotbot runtime-status` can discover it without hard-coded ports. * **HttpServer** - listener loop, request routing, and token authentication. * **ControlPlaneClient** - outbound registration with an optional mothership dashboard in fleet mode. * **EndpointDiscovery** - resolves the runtime URL from environment variables, settings, or the connection file. * **Lifecycle** - start, stale-PID detection, and graceful shutdown. *** ## 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: | Item | Description | | --------------- | -------------------------------------------------------------------------------------------------- | | `settings.json` | Machine-local settings: active workflow and stack selections. Wins over `settings.default.json`. | | `runtime.json` | Runtime PID, URL, and start timestamp. Written when the runtime starts; removed on clean shutdown. | | `ui-port` | Port file written by the UI server after its listener binds. | | `logs/` | Structured JSONL log files (retention controlled by `logging.retention_days`). | | `processes/` | Process registry entries tracking active AI CLI invocations. | 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. | Directory | Contents | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `tasks/workflow-runs/` | Tasks owned by a named workflow run, organised by status sub-folder (`todo/`, `analysing/`, `analysed/`, `in-progress/`, `done/`, `needs-input/`, `skipped/`, `split/`). | | `tasks/standalone/` | Tasks run outside a workflow via `dotbot tasks run`. Same status sub-folder layout. | | `sessions/history/` | Completed session audit trails with token counts, costs, turn boundaries, and errors. | | `product/` | Product documents: mission statement, tech stack definition, entity model. | | `plans/` | Implementation plan markdown files, linked to tasks by ID. | | `decisions/` | Architecture decision records in four states: `proposed/`, `accepted/`, `deprecated/`, `superseded/`. | | `pilot/` | Pilot experiment artifacts. | | `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.