Prerequisites
Before You Start
Step 1
Download chAIrman
Log into mrchairman.ai/account, navigate to your account page, and click the Download button. Save chairman somewhere permanent — you'll reference its path in Claude Desktop's config.
Paste this into your terminal. It downloads and places the chairman binary in ~/.chairman/ automatically.
curl -fsSL https://mrchairman.ai/install.sh | bash
chairman binary — you'll need it in the next step.
Step 2
Add to Claude Desktop
In Claude Desktop, go to Settings → Developer → MCP Servers (or press ⌘, on macOS).
Click Edit Config to open claude_desktop_config.json in your editor.
Paste the JSON below. Replace /path/to/chairman with the actual path from Step 1.
{
"mcpServers": {
"chairman": {
"command": "/path/to/chairman" ← replace this
}
}
}
/Users/yourname/.chairman/chairman. Use an absolute path, not ~.
Step 3
Configure Permissions
chAIrman spawns agents using --permission-mode bypassPermissions so they can work autonomously without manual approval for every file edit. This step is optional — bypassPermissions already skips permission checks, but adding a settings file provides an extra safety layer with explicit deny rules.
Create a .claude/settings.json file inside your project directory:
{
"permissions": {
"allow": [
"Bash",
"Read",
"Write",
"Edit",
"Glob",
"Grep",
"WebFetch",
"TodoWrite"
],
"deny": [
"Bash(rm -rf *)", ← blocked for safety
"Bash(rm -r /*)" ← blocked for safety
]
}
}
rm -rf and rm -r / are blocked. Agents have broad access to read/write/edit files and run Bash commands — only deploy on projects you control.
Step 4
Add CLAUDE.md to Your Project
Every project needs a CLAUDE.md file in its root directory. This is the shared context injected into every agent's prompt — it tells agents what they're building, the tech stack, conventions, and what to avoid.
Go to mrchairman.ai/account and download the starter template, or use the minimal version below.
Save it as CLAUDE.md in the top-level directory of your project — the same folder where you'll run create_project.
Fill in your tech stack, important file paths, coding conventions, and any tasks agents should never do. The more specific, the better your agents perform.
# My Project ## What This Is [Describe your project in 2-3 sentences] ## Tech Stack - Language: [e.g. TypeScript] - Framework: [e.g. Next.js] - Database: [e.g. PostgreSQL with Prisma] - Styling: [e.g. Tailwind CSS] ## Project Structure - src/app/ — Next.js app router pages - src/components/ — Reusable UI components - src/lib/ — Utilities and helpers ## Conventions - Use TypeScript strict mode - Prefer named exports over default exports - Write tests alongside implementation ## DO NOT - Modify .env files directly - Delete migrations - Push to main branch without PR
Step 5
Start Building
Start a new conversation. You should see chAIrman tools available in the tool panel — look for tools like create_project, hire_agent, and assign_task.
Describe your project naturally. Claude will use chAIrman tools to register the project, hire appropriate agents, and assign tasks — all automatically.
Open localhost:3456 in your browser. You'll see agents appear on the kanban board, click any agent card to see live terminal output, and watch your budget in real time.
Quick Start
Paste This Into Claude Desktop
Copy the prompt below and paste it into a new Claude Desktop conversation. Claude will walk you through the full setup interactively.
Walk me through:
1) Verifying the MCP server is connected and the tools are working
2) Creating my first project at [paste your project path]
3) Hiring my first agents and assigning them tasks
4) Opening the dashboard at localhost:3456
My project is: [describe what you're building in 1-2 sentences]
Troubleshooting
Common Issues
Check that the path in claude_desktop_config.json is an absolute path (not starting with ~). Run /your/path/to/chairman in your terminal — if it starts without error, the path is correct. Then fully quit and restart Claude Desktop (not just close the window). The chAIrman tools should appear in the tool panel on the next conversation.
First confirm Claude Code is installed: run claude --version in your terminal. If not found, make sure you have an active Claude subscription (Pro or Max) with Claude Code access enabled. Also verify the .claude/settings.json permissions file exists in your project directory. Check get_status for the agent ID to see the error message.
The dashboard starts automatically when the MCP server starts. If Claude Desktop has the MCP server running (you can see chAIrman tools), but localhost:3456 shows nothing, check if another process is using port 3456. You can change the port by setting the environment variable CHAIRMAN_PORT=3457 in the MCP server entry in your config.
Cost tracking depends on Claude Code's stream-json output including a total_cost_usd field in the result message. This is populated by Claude Code automatically — if you see $0, it may mean the task completed very quickly or Claude Code's version you have installed doesn't emit this field. Costs are still accurate in your Anthropic billing dashboard.
Make sure CLAUDE.md is in the project root directory — the same path you passed to create_project. The file is truncated at 10,000 characters per file, so keep it concise. Use clear section headers and avoid redundant context. You can also use post_message to broadcast reminders to active agents mid-task.
License keys follow the format CHRM-XXXX-XXXX-XXXX-XXXX. Copy-paste directly from your account page — avoid any extra spaces. If activation still fails, contact [email protected] with your account email and the key you're trying to activate.
Another process is occupying port 3456, preventing chAIrman from starting its dashboard. Free the port with:lsof -ti :3456 | xargs kill -9
Then fully quit and restart Claude Desktop. The MCP server will re-bind to port 3456 on startup.
Claude Desktop shows the MCP server as disconnected with no clear reason. Run the binary directly in your terminal to see the exact error:cd /path/to/chairman && node build/index.js
Replace /path/to/chairman with the actual directory containing your chairman binary. The error message printed to the terminal will show what's failing (missing dependency, bad config, etc.).
Each chAIrman account is limited to 1 active device. If you're switching computers, log in again at mrchairman.ai/account — this re-registers the current machine as your active device and deactivates the previous one automatically.
Downloads require an active Pro or Unlimited subscription. Visit mrchairman.ai/account and verify your subscription status. If the download button is missing or grayed out, your subscription may have lapsed — check the billing section on that page to renew.
Two things to check: (1) Claude subscription — agents are powered by Claude Code, so an active Claude Pro or Max subscription with Claude Code access is required. Run claude --version in your terminal to confirm it's installed. (2) Tier agent limit — the Pro plan allows up to 2 concurrent agents. If you need more, upgrade to Unlimited at mrchairman.ai/#pricing. Use batch_status to see how many agents are currently active.
First confirm the MCP server is running — you should see chAIrman tools in the Claude Desktop tool panel. Then try opening localhost:3456 directly in your browser. If it still doesn't load, a port conflict may be blocking it: run lsof -i :3456 to see what's using the port. You can also set CHAIRMAN_PORT=3457 as an environment variable in your MCP config to use a different port.