TeamBot

Autonomous AI Agent Teams for Software Development

TeamBot is a CLI tool that uses the GitHub Copilot SDK to enable collaborative, multi-agent AI workflows. Instead of single-threaded AI interactions, TeamBot orchestrates a team of specialized AI agents that work together autonomously to achieve development objectives.

Installation

Prerequisites

• Python 3.10 or later - Download Python
• uv - Install uv
• GitHub Copilot CLI - Install Copilot CLI and authenticate with copilot login

Terminal Requirements

TeamBot's split-pane UI works with all modern terminal emulators. For the best experience:

• VSCode integrated terminal - Recommended (Kitty protocol support enabled by default)
• Kitty, Alacritty, WezTerm - Full support for enhanced keyboard protocol
• Standard terminals - xterm, GNOME Terminal, Konsole, Terminal.app all work correctly

For troubleshooting input issues, see Terminal Compatibility Guide.

Installation Methods

Method	Command	Best For
uvx (git)	uvx --from git+https://github.com/glav/teambot teambot	Quick evaluation
Devcontainer	See installation guide	VS Code / Codespaces
Docker	docker run ghcr.io/glav/teambot	No Python environment
From source	See below	Development

Install from Source

git clone https://github.com/glav/teambot.git
cd teambot
uv sync
uv run teambot --version

Verify Installation

teambot --version
teambot --help

Key Features

• 🤖 6 Specialized Agent Personas - PM, BA, Writer, 2 Builders, Reviewer
• 📋 14-Stage Prescriptive Workflow - From setup through acceptance testing to completion
• 🔄 Autonomous Operation - Define objectives in markdown, let the team execute
• ⚡ Parallel Builders - builder-1 and builder-2 execute concurrently
• 💬 Interactive REPL - Ad-hoc tasks with pipelines and multi-agent mode
• ⚙️ Configurable - Custom stages, models, and workflows

Interactive mode

Autonomous mode

Quick Start

# Initialize TeamBot in your project
teambot init

# Run with an objective file
teambot run objectives/my-feature.md

# Or start interactive mode
teambot run

Worktree Isolation

TeamBot supports isolated execution using Git worktrees, enabling parallel feature development:

# Run objective in isolated worktree
teambot run objectives/my-feature.md --worktree

# With explicit branch name
teambot run objectives/my-feature.md --worktree --branch feat/custom-name

Requirements: Git 2.5+

Behavior:

• Creates worktree at .teambot-worktrees/<branch-name>/
• State files scoped to worktree (no cross-contamination)
• Visual indicators show current branch in REPL and stage headers
• Worktree persists after completion for user review

See Worktree Isolation Guide for detailed usage.

Environment Configuration

TeamBot automatically loads environment variables from .env files with hierarchical discovery:

# Default: loads .env from current directory + parent directories
teambot run objectives/my-task.md

# Load from specific file only (disables auto-discovery)
teambot --env-file /path/to/.env run objectives/my-task.md

# Disable .env loading (useful for CI)
teambot --no-env run objectives/my-task.md

Precedence: When multiple .env files exist, values are merged with the current directory taking precedence over parent directories.

What teambot init Creates

The init command sets up your project with:

• teambot.json - Configuration file for agents and workflows
• .teambot/ - Directory for workflow state and history
• stages.yaml - Workflow stage definitions (if not exists)
• AGENTS.md - Agent documentation (if not exists)
• .github/agents/ - Agent persona definitions (if not exists)
• .agent/ - SDD commands, instructions, and standards (if not exists)
• docs/sdd-objective-template.md - Objective template (if not exists)

Existing files are never overwritten. Use teambot init --force to reset all scaffold files.

For development from source, see Development Guide.

Documentation

Guide	Description
Getting Started	Installation, setup, first run, troubleshooting
File-Based Orchestration	Running objectives autonomously
Interactive Mode	REPL, pipelines, multi-agent mode
Worktree Isolation	Parallel feature development with Git worktrees
CLI Reference	All commands and options
Agent Personas	The 6 specialized AI agents
Workflow Stages	14-stage development process
Configuration	teambot.json, stages.yaml, models
Objective Format	Writing objective files
Shared Workspace	.teambot/ directory structure
Development	Contributing and development setup
Architecture	Internal components and design

License

MIT License - see LICENSE file for details.

Contributing

See Development Guide for setup and contribution guidelines.

---

Made with 🤖 by TeamBot