This page lists only the settings AITM needs to run correctly. Everything else has a sensible default and can wait.
Setup Essentials
Rule of thumb: if a row below is not done, tasks will either not start, will fail on the first AI step, or will not merge. Everything not on this page is optional.
1. Before you open the dashboard
| What | Where | Why |
|---|---|---|
| Node.js 24+, npm, Git on the machine (or Docker) | your OS | AITM is a Node.js server; pipeline steps shell out to git. |
claude CLI installed and logged in (claude auth login) | terminal | The default AI provider spawns the Claude CLI. Without it every AI step fails immediately. |
npm install then npm run setup:e2e (once) | repo root | Installs dependencies and the Playwright Chromium used by the E2E step. |
config.json created from config.example.json | repo root | The server refuses to start without it. Minimum fields: port (3333), host, one tabs[] entry with one project, and sandboxRoot. |
Start with aitm start (or npm run dev in development) | terminal | Starting any other way bypasses the instance guard and the restart supervisor. |
Docker instead of a local install: use the full-pipeline compose file and .env from release/docker/. The same checklist applies once the container is up — the only difference is that the Claude API key or OAuth login is done from Settings → AI Providers instead of the terminal. The Docker install now offers a direct button to install the claude CLI (the same button also exists in Settings → AI Providers as a fallback).
2. Add your project (Settings → Projects & Memory)
| What | Where | Why |
|---|---|---|
| Tab — name, shortcut, icon, colour | Projects & Memory → tab header | A tab groups related projects. Every task belongs to a tab. |
| Project — Name, Description, Host, Web Port | Projects & Memory → project row | Web Port is what the E2E step opens in the browser. Wrong port = E2E cannot reach the app. |
Project path must be a Git repository with a dev branch | your disk | Tasks branch from dev and merge back to dev. No repo → the Branch step fails. |
CLAUDE.md in the project root | project repo | The first thing every agent reads. Without it the AI works blind. |
3. Connect an AI provider (Settings → AI Providers)
Claude enabled + either CLI login or an API key. Leave the key empty when the machine already has claude auth login; fill it in for Docker/headless servers. Click Test to confirm.
4. Pick the default models (Settings → AI & Models)
AI Provider (global default) and Default Model, Chat Model, Brainstorm Model. Chat and Brainstorm run far more often than the pipeline — a cheaper model there saves the most money.
5. Pipeline behaviour (Settings → Pipeline)
Max concurrently running tasks (global) — recommended 2 on a 16 GB machine. Keep Continue Context and Handoff Context on — later steps see what earlier steps did.
6. Git and merging (Settings → Git & Storage)
Push remote (default origin) must exist in every project repo. Server restart after self-merge — manual (default) waits for you to click Restart in the header menu.
7. Licence (Settings → License)
Without an active licence the pipeline queue does not admit tasks. Each project registered in a tab consumes one slot. Running the same key on two machines triggers the "License blocked (session-mismatch)" banner — see Glossary & FAQ.
8. Resources (Settings → Watchdog & Resources and System)
Keep Disk Janitor and Disk Watchdog enabled so a full disk never stops the pipeline. Keep e2eInstances (config.json) at 1 unless you have ≥ 8 cores / 16 GB.
9. Language (Settings → Languages & Translation)
UI language changes the dashboard only. Primary/secondary language for AI output lets you write prompts in another language while the AI reads and writes code in English.
Quick verification
- Header shows Connected (green dot) and no orange licence banner.
- Settings → AI Providers → Test on the Claude card returns OK.
- Your project card on the Develop view shows the right branch (
dev) and path. - Create a tiny task and watch it go
pending → running → finished → archived. If it does, everything on this page is right.
Tips
- If a task never leaves
pending, check the licence banner and the Max concurrently running tasks row below before looking anywhere else. - Without
claude auth loginor an API key, every AI step fails immediately — verify that first. - Not sure where a setting lives? The "Where" column in the tables above points to the exact Settings tab.