https://github.com/glav/teambot
An attempt to build an AI based 'team' that can be given a series of tasks to execute to conclusion as per an engineering team, and can work together to ensure it is done. Autonomous, requiring only daily objectives
https://github.com/glav/teambot
Last synced: about 1 month ago
JSON representation
An attempt to build an AI based 'team' that can be given a series of tasks to execute to conclusion as per an engineering team, and can work together to ensure it is done. Autonomous, requiring only daily objectives
- Host: GitHub
- URL: https://github.com/glav/teambot
- Owner: glav
- Created: 2026-01-22T01:54:56.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-10T02:29:59.000Z (3 months ago)
- Last Synced: 2026-03-10T09:25:32.860Z (3 months ago)
- Language: Python
- Size: 4.74 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# TeamBot
**Autonomous AI Agent Teams for Software Development**
TeamBot is a CLI tool that uses the [GitHub Copilot SDK](https://github.com/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.
[](https://www.python.org/downloads/)
[]()
[]()
## Installation
### Prerequisites
- **Python 3.10 or later** - [Download Python](https://www.python.org/downloads/)
- **uv** - [Install uv](https://astral.sh/uv)
- **GitHub Copilot CLI** - [Install Copilot CLI](https://githubnext.com/projects/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](docs/guides/terminal-compatibility.md).
### Installation Methods
| Method | Command | Best For |
|--------|---------|----------|
| **uvx (git)** | `uvx --from git+https://github.com/glav/teambot teambot` | Quick evaluation |
| **Devcontainer** | See [installation guide](docs/guides/installation.md) | VS Code / Codespaces |
| **Docker** | `docker run ghcr.io/glav/teambot` | No Python environment |
| **From source** | See below | Development |
### Install from Source
```bash
git clone https://github.com/glav/teambot.git
cd teambot
uv sync
uv run teambot --version
```
### Verify Installation
```bash
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
```bash
# 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:
```bash
# 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//`
- 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](docs/guides/worktree-isolation.md) for detailed usage.
## Environment Configuration
TeamBot automatically loads environment variables from `.env` files with hierarchical discovery:
```bash
# 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](docs/guides/development.md).
## Documentation
| Guide | Description |
|-------|-------------|
| [Getting Started](docs/guides/getting-started.md) | Installation, setup, first run, troubleshooting |
| [File-Based Orchestration](docs/guides/file-based-orchestration.md) | Running objectives autonomously |
| [Interactive Mode](docs/guides/interactive-mode.md) | REPL, pipelines, multi-agent mode |
| [Worktree Isolation](docs/guides/worktree-isolation.md) | Parallel feature development with Git worktrees |
| [CLI Reference](docs/guides/cli-reference.md) | All commands and options |
| [Agent Personas](docs/guides/agent-personas.md) | The 6 specialized AI agents |
| [Workflow Stages](docs/guides/workflow-stages.md) | 14-stage development process |
| [Configuration](docs/guides/configuration.md) | teambot.json, stages.yaml, models |
| [Objective Format](docs/guides/objective-format.md) | Writing objective files |
| [Shared Workspace](docs/guides/shared-workspace.md) | .teambot/ directory structure |
| [Development](docs/guides/development.md) | Contributing and development setup |
| [Architecture](docs/guides/architecture.md) | Internal components and design |
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Contributing
See [Development Guide](docs/guides/development.md) for setup and contribution guidelines.
---
Made with 🤖 by TeamBot