TheBotCompany Quick Start: A New AI Team Paradigm with Zero Manual Intervention

30 Minutes to Get Started｜Three Roles Cooperate Autonomously｜Multi-Provider Fallback｜End-to-End Automation from Requirements to PR

---

Project Overview

TheBotCompany is an AI development team platform that lets you “truly let go.” The idea is straightforward: it’s no longer just you chatting with an AI to write code. Instead, you assemble a team made up of multiple AI Agents—one plans, one writes code, one verifies. They discuss, assign tasks, and manage progress on their own. Your only job is to step in when they hit situations that genuinely require human judgment.

There are three fixed management roles in the team: Athena handles strategic planning, defining milestone goals and cycle-based budget allocation; Ares leads execution, breaking milestones into specific tasks for the worker Agents; Apollo owns acceptance, reviewing Ares’s output to high standards—anything that fails is sent back. You don’t need to watch the loop. The Dashboard shows in real time what each Agent is doing, how much it’s costing, and what problems it encounters.

---

Target Audience Profile

This article is for developers who:

• Have some development experience, want to hand repetitive coding work to an AI Agent team, and focus instead on decisions and architecture
• Are interested in Multi-Agent collaboration and self-organizing teams, and want practical case studies
• Already use a single Agent to assist development, but want to expand to multiple Agents working in parallel on multiple directions

If what you want is a tool you can set up once and “fully lie back,” you’ll need to lower expectations first—TheBotCompany can drastically reduce manual intervention, but it still isn’t completely zero.

---

Core Dependencies and Environment

---

Full Project Directory Tree

After installing and starting, the following structure will be generated under ~/.thebotcompany/:

~/.thebotcompany/
├── keys.json              # Encrypted storage for API Keys
├── db.sqlite              # Issue tracker database
├── config.yaml            # Global configuration
└── logs/                  # Runtime logs

Your project directory/
├── workers/               # Worker Agent skill definitions
│   ├── leo.md             # Frontmatter: reports_to, role, model
│   └── maya.md
├── workspace/             # Workspaces for each Agent
│   ├── athena/note.md
│   ├── ares/note.md
│   └── leo/note.md
└── .tbc/                  # Project-level configuration (generated when the project is created)

---

Step-by-Step Installation

Step 1: Install TheBotCompany

npm install -g thebotcompany

Verify installation:

tbc --version

Step 2: Start the service

tbc start

On the first run, it will prompt you in sequence to set:

1. Dashboard access password — Protects write operations (pause, resume, modify configuration)
2. Port — Default is 3100; just press Enter to accept the default

? Set a password for dashboard write access: ********
? Port to run the dashboard (default 3100):

After starting successfully, the Dashboard is accessible at http://localhost:3100. By default it’s read-only; you can operate it only after logging in.

Step 3: Configure API Key

Open the Dashboard (http://localhost:3100), click Settings at the top-right, and add your API Key in the Keys panel. You can also have it auto-detect on first run via environment variables:

# Add these to .bashrc or .zshrc:
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

Step 4: Create a project via Dashboard

1. Open http://localhost:3100
2. Click New Project and fill in:
   • Repository URL — Your GitHub Repo URL (requires that gh has access)
   • Provider — Choose which LLM Provider to use
   • Model Tier — Models used for each tier (high/mid/low)
3. Click Create and hand control to Athena to start working

---

Deep Dive: Three-Roles Collaboration Architecture

This is the most core design of TheBotCompany. Once you understand it, you’ll know how the whole system runs.

Three Fixed Management Roles

The Complete Cycle Loop

PLANNING phase (Athena)
  → Athena + her worker Agents run
  → Research, evaluation, brainstorming
  → Define milestones → go into IMPLEMENTATION

IMPLEMENTATION phase (Ares)
  → Ares + his worker Agents run (up to N Cycles)
  → Ares declares completion → go into VERIFICATION
  → Exceeds cycle budget → send back to PLANNING for re-evaluation

VERIFICATION phase (Apollo)
  → Apollo + his worker Agents run
  → Apollo acceptance passes → go into the next PLANNING
  → Apollo sends back → return to IMPLEMENTATION for fixes

How Worker Agents Work

Managers (Ares / Athena / Apollo) “hire” worker Agents by creating .md files in the {project_dir}/workers/ directory. Each file has a fixed YAML frontmatter:

---
reports_to: ares          # Who they report to
role: Frontend Engineer   # Responsibilities
model: mid                # Which model tier to use
---

# Frontend Engineer

You are a frontend engineer responsible for implementing UI components and interaction logic.

When a Manager assigns tasks to a worker, it assigns one task per cycle—you’re not allowed to stack five tasks at once. After a worker finishes, the Manager reads note.md in the workspace to understand context, then decides the next step.

Communication Between Agents

Agents don’t talk directly to each other; they coordinate through the built-in Issue Tracker:

• Ares needs Athena’s input → create an Issue in the Issue Tracker and assign it to Athena
• A Worker encounters a problem → create an Issue, which the Manager will see and handle
• Manual intervention needed → create a GitHub Issue with a title starting with HUMAN:, and you log in to GitHub to respond

---

End-to-End Development Flow Demonstration

Step 1: Create a Project via Dashboard

Open the Dashboard and click New Project:

Repository: https://github.com/your-username/your-repo
Provider: Anthropic
Model: claude-sonnet-4

After the project is created, you’ll see a project card on the Dashboard. Its status is PLANNING, and Athena starts working.

Step 2: Observe Athena’s Planning Process

In the Dashboard’s Agent Reports panel, you can see Athena’s outputs. She does things like:

• Read the project README and existing code to understand the current situation
• Search for relevant technical approaches and best practices
• Evaluate feasibility of the requirements
• Define the first milestone and its budget (how many Cycles)

Once the milestone is defined, the system automatically switches to the IMPLEMENTATION phase and Ares goes online.

Step 3: Ares Executes the Implementation

The Dashboard status switches to IMPLEMENTATION, and Ares starts working:

1. Hire workers — Ares creates files like workers/leo.md and workers/maya.md
2. Assign tasks — Each Cycle assigns one concrete task to one worker only
3. Review PRs — After a worker opens PRs, Ares performs Code Review
4. Cycle control — If a cycle doesn’t finish, send it back to retry in the next cycle

You can message Ares directly in the Dashboard’s Chat panel to adjust direction or add context.

Step 4: Apollo Verification

When Ares declares the milestone is complete, the system switches to VERIFICATION, and Apollo goes online:

→ Apollo reads the code changes
→ Run verification tests (via GitHub Actions)
→ Check whether it meets milestone requirements
→ Pass → proceed to the next PLANNING
→ Fail → send back to IMPLEMENTATION, explaining what’s wrong

Apollo’s bar is higher than Ares’s, so it’s common to see “Ares thinks it’s fine, but Apollo sends it back.” That’s normal by design, not a bug.

Step 5: Manual Intervention (If Needed)

When an Agent encounters something that truly requires human judgment, it creates a GitHub Issue starting with HUMAN::

HUMAN: Should the login page use OAuth or username/password?
Please reply to this Issue on GitHub. The Agent will continue based on your response.

After you reply, Ares continues execution. If you don’t want intervention, you can directly pause the project in the Dashboard.

---

Dashboard Feature Breakdown

TheBotCompany’s Dashboard is the control center of the entire system—everything is visible at a glance.

Project Overview

The Dashboard homepage displays cards for all projects. Each card shows:

• Current stage (PLANNING / IMPLEMENTATION / VERIFICATION)
• Current Cycle / Epoch count
• Milestone progress bar
• Summary of the last Agent Report

Agent Reports

Each project’s Agent output history. Supports Markdown rendering and automatic summarization. If a cycle’s output is exceptionally long, the Dashboard will automatically compress it and show only the key conclusions.

Issue Tracker

All coordination between Agents happens here:

• Filter by project
• Filter by status (Open / In Progress / Resolved)
• Filter by Agent
• Dedicated Human Issues panel listing all escalation requests that require you to handle

Chat

The Dashboard includes a built-in direct chat entry. You can choose any project, message the corresponding Manager, and add context or adjust direction. Supports streaming responses and image uploads.

Cost Tracking

Cost breakdowns for each project and each Agent:

• Last Cycle cost
• 24-hour average cost
• Cumulative total cost

With Budget Controls, you can set a rolling 24-hour budget cap; once exceeded, Agents automatically enter sleep mode.

Controls

Quick control buttons on the Dashboard:

• Pause / Resume — Pause and resume a project (requires login)
• Skip Sleep — Skip the preset sleep interval and start the next Cycle immediately
• Kill Run / Cycle / Epoch — Force terminate the current run
• Bootstrap — Restart from a specified milestone

---

Multi-Provider and Key Pool Management

Supported Provider List

TheBotCompany natively supports 15+ LLM Providers:

How Key Pool Works

In the Settings → Keys panel, you can add multiple keys for the same Provider and set their priority order. During runtime:

1. The system first uses the highest-priority key
2. If that key hits a rate limit (429) or runs out of quota → automatically switch to the next key
3. After the cooldown ends, the key becomes available again and returns to the rotation

This is especially useful for long-running projects—you don’t have to worry about a single key exhausting and stalling the entire Agent team.

Model Tier Configuration

Each project can customize which models are used for each tier:

# Project-level .tbc/config.yaml
model_tiers:
  high: claude-opus-4       # Complex architectures, deep reasoning
  mid: claude-sonnet-4      # Default, balanced capability and cost
  low: claude-haiku-3       # Simple repetitive tasks, formatting

You can also modify it directly in the Settings → Model Tier Overrides panel via the UI, without editing config files.

---

Common Troubleshooting

Q1: After running tbc start, the Dashboard won’t open; it shows Connection Refused

Cause: The port is already in use, or the service didn’t start correctly.

Troubleshooting steps:

# 1. Check whether tbc is running
tbc status

# 2. If it’s not running, start it manually and inspect the error output
tbc dev

# 3. If the port is occupied, specify another port
TBC_PORT=3200 tbc start

---

Q2: The Agent team stays in PLANNING and never enters IMPLEMENTATION

Cause: Athena is doing deep research or waiting for the worker Agents’ results, and hasn’t defined any milestones yet.

Solution:

Open the Dashboard → Agent Reports to check Athena’s latest output. If she’s waiting for a worker’s research result, you can use /tbc logs to check server logs and confirm whether it’s stuck. If it’s truly stuck, send Athena a message in the Dashboard’s Chat panel: “Based on the existing information, define the first milestone; no need to wait for more research.”

---

Q3: No GitHub PR is created; the Agent reports an authorization error in the Issue Tracker

Cause: The gh CLI isn’t authenticated correctly, or the token lacks sufficient permissions.

Troubleshooting steps:

# 1. Check gh login status
gh auth status

# 2. If not logged in, re-authenticate (requires repo permissions)
gh auth login --scopes repo

# 3. Confirm the remote URL in the project directory is correct
cd /path/to/your-project
git remote -v

---

Q4: Apollo keeps sending back Ares’s implementation, causing a Cycle dead loop

Cause: The direction Ares fixes toward each time doesn’t match Apollo’s expectations, or the milestone definition itself isn’t clear enough.

Solution:

In the Dashboard’s Chat panel, send to Ares: “Apollo’s reason for sending it back is [paste the specific feedback from Apollo’s Report]. Before fixing, please make sure you fully understand Apollo’s standards. Confirm the direction with Apollo before you start.”

If Apollo’s standards are too strict, you can have Athena adjust the acceptance criteria for the milestone during the PLANNING phase.

---

Q5: Costs are far higher than expected; you want to pause all Agents immediately

Solution:

# Option 1: Dashboard operation
# Log in to Dashboard → each project card → Controls → Pause

# Option 2: CLI pause
tbc stop

# Option 3: Set a budget cap (takes effect on the next start)
# In Dashboard Settings → Budget Controls, set a 24h budget cap

---

Q6: You added multiple API keys, but Agents keep using the same key and hit the limit

Cause: The Key Pool priority order might be wrong, or the key’s cooldown after rate limiting hasn’t finished.

Solution:

In Dashboard Settings → Keys panel, check the status of each key:

• Active — being used normally
• Cooldown — rate-limited and currently cooling down
• Exhausted — quota used up

If a key stays in Cooldown for a long time, manually move it to the bottom of the Key list so the system switches to the next key.

---

Further Reading and Advanced Directions

1. Customizing Worker Agent Skills

Create new .md files under workers/ to extend the team’s capabilities:

---
reports_to: ares
role: DevOps Engineer
model: mid
---

# DevOps Engineer

You are a DevOps engineer proficient in CI/CD pipelines, containerization, and infrastructure as code.

Managers will automatically discover newly added worker Agents. They can be scheduled as soon as the next Cycle starts.

2. Integrating a Custom Provider

If you need to connect to a company internal LLM service (OpenAI or Anthropic compatible format), go to Settings → Keys → Add Custom Provider:

{
  "name": "my-internal-llm",
  "baseUrl": "https://llm.internal.company.com/v1",
  "apiKey": "sk-internal-...",
  "model": "gpt-4"
}

3. Deep Integration with GitHub Actions

The Agent design in TheBotCompany encourages running time-consuming tests and builds via GitHub Actions. In a worker Agent’s skill file, specify:

Never run tests longer than 5 minutes directly in the terminal. Trigger all test suites through GitHub Actions.

This way, when the Agent is killed due to a Cycle timeout, the submitted code and CI results won’t be lost.

4. Multi-Project Management and Overview

If you’re running multiple projects at the same time (open-source maintenance, Side Project, commercial project), TheBotCompany’s unified Dashboard lets you see the status, spend, and issue distribution of all projects on a single page. Use the top-level Project Filters to switch quickly, and the Human Issues panel centralizes all escalation requests so you don’t miss any decisions you need to make.

5. Fine-Grained Control of Budget and Cost

By default, the rolling 24-hour budget cap is global. If you want different budgets for different projects, you can run multiple TheBotCompany instances (each with a different TBC_HOME directory). Each instance independently manages a set of projects and budgets, without interfering with each other.