Metadata-Version: 2.4
Name: agent-team
Version: 0.6.1
Summary: A configurable team of AI agents (any model, any machine) that plans, builds, reviews, markets and ships a software project through GitHub.
Author: Lakeba
License-Expression: MIT
Project-URL: Homepage, https://github.com/lakeba/agent-team
Project-URL: Documentation, https://lakeba.github.io/agent-team/
Project-URL: Changelog, https://github.com/lakeba/agent-team/blob/main/CHANGELOG.md
Keywords: ai,agents,llm,claude,ollama,github,devops
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=1.0
Provides-Extra: screenshots
Requires-Dist: pillow>=10; extra == "screenshots"
Provides-Extra: dev
Requires-Dist: pillow>=10; extra == "dev"
Dynamic: license-file

<p align="center"><a href="https://lakeba.com"><img src="https://raw.githubusercontent.com/lakeba/agent-team/main/docs/assets/brand/lakeba-mark.svg" alt="Lakeba" width="72"></a></p>

<h1 align="center">agent-team</h1>

<p align="center"><b>by <a href="https://lakeba.com">Lakeba</a></b> · Conceive · Create · Commercialise<br>
<a href="https://lakeba.github.io/agent-team/">Website</a> · <a href="https://pypi.org/project/agent-team/">PyPI</a> · <a href="CHANGELOG.md">Changelog</a></p>

A configurable team of AI agents that works on a software project the way a small team would:
it plans a roadmap, builds features, reviews them, writes marketing material, and ships through
GitHub with pull requests, CI, sign-offs and releases.

Team members can run on any model and any machine: Claude through the Anthropic API, local
models through Ollama, any OpenAI-compatible server, or another machine running
`agent-team serve`. A team is described in a `.team.toml` file in each project, so adding a
member, a machine or a project is a configuration change.

It grew out of todo-py, a small command-line app this team planned, built, marketed and released
(v1.0.0 and v1.0.1); its team is in [examples/todo-py.team.toml](examples/todo-py.team.toml).

## How the team works

| Workflow | Command | What happens |
|---|---|---|
| Discuss | `agent-team discuss "next features"` | Members talk in turn until they all agree on how to reach the product's vision (`VISION.md`); the lead updates `ROADMAP.md`. |
| Build | `agent-team build "task" --branch x --pr` | The lead writes `PLAN.md`, builders implement it (in parallel with `--parallel`), tests run each round, the lead reviews until approved, then a PR opens. Optional QA, security and docs members write tests first, review the result and update the docs. |
| Autopilot | `agent-team autopilot --milestone M2` | Works through the roadmap a PR at a time: the lead picks the next task, the team builds it, each devops shift reviews, fixes and merges, until the lead says the milestone is done (or it gets stuck, or hits a spend limit). |
| Fix | `agent-team fix 12` | When the lead requests changes on a PR, a builder applies the review on that PR's branch, the lead confirms the blocking points are addressed, and it pushes; the next shift reviews the new commit. |
| Market | `agent-team market` | The marketing member writes a brief, a website and a pitch deck; a fact-checker checks claims and the lead reviews with screenshots. |
| Set up | `agent-team setup --license "MIT, copyright 2026 Lakeba"` | The devops member drafts README, CONTRIBUTING, CHANGELOG, CI and templates. |
| Ship | `agent-team ship` | One devops shift on GitHub: triage, owner sign-offs, lead review, merge, release (or, with `release = "ask"`, a release proposal you approve with `ship --release X.Y.Z`), feedback digest. `agent-team schedule --every 6h` runs shifts unattended, never two at once. |
| Dashboard | `agent-team ui` | Overview, Team, Runs, Costs, live Activity charts (spend, runs, merges, problems, latest events), Settings (easy switches and team templates, always previewed as a diff) and Projects (every project on this Mac). A page on this machine: the team and whether each member is reachable, every run with each member's verdicts, estimated costs per member, day and run, and the GitHub state. Edit members, connections, guarantees and prices there, add a machine with a guided wizard, and review the diff before saving. Start runs there and follow their output live. |

Guardrails are enforced in code, not left to the models. A PR merges only when CI is green, the
lead approved the exact head commit, and every member who owns a changed path signed off that
same commit (the lead's approval is its own sign-off). On a re-review, reviewers block only on
points still open or problems the new commit introduces, so a PR that fixes what was asked passes. Releases need green CI on `main` and a CHANGELOG entry. Text from outside the team
always reaches the models marked as untrusted. Spend limits in `.team.toml` stop any run before it
costs more than you allow, and large projects get a focused context instead of every file.

Builders change files with small search/replace edits instead of rewriting them, and an edit
that doesn't match is refused and sent back. Reviewers read files, search, see the diff and run
the tests themselves. When a reviewer blocks for a reason that will matter again, the lesson is
kept and every member sees it in later work.

With `[sandbox] mode = "container"`, the code the team writes is tested in a throwaway container
with no network and none of your keys. Every push is checked for secrets first (key and token formats, private keys, `.env` files, and
the values in your keys file). Paths you list in `require_approval` wait for your approval of the
exact commit. Weaker models hand work to a stronger member after rejected rounds (`escalate_to`),
and `[notify]` posts to Slack or any webhook when PRs open or merge, approvals or releases wait
for you, or autopilot stops.

## Install

Requirements: macOS or Linux, Python 3.11+ (on Ubuntu/Debian also `python3-venv`) and git. Members
can run on Claude (an Anthropic API key), on [Ollama](https://ollama.com/) models on this machine or
others, or both; a team on Ollama alone needs no API key. Optional: [Ollama](https://ollama.com/)
for local models, on this machine or another. The workflows that work on GitHub (`build --pr`,
`ship`, `setup` and the plugin's PR steps) also need the [GitHub CLI](https://cli.github.com/)
signed in (`gh auth login`).

One command installs the CLI into its own environment under `~/.agent-team`, puts `agent-team` on
your `PATH` (`~/.local/bin`), and installs the Claude Code plugin if Claude Code is present:

```bash
curl -fsSL https://raw.githubusercontent.com/lakeba/agent-team/main/scripts/install.sh | bash
```

Run it again to update, then run `/reload-plugins` in any open Claude Code session (or start a new
one): an open session keeps the commands it started with. Options go after `bash -s --`, for example `| bash -s -- --ref v0.1.0`
for a specific version, `--no-plugin` to skip the plugin, or `--uninstall` to remove everything
it installed. `--uninstall` keeps your saved keys and project list in `~/.config/agent-team`; add
`--purge` to delete them too (it asks first). If you prefer pipx:
`pipx install git+https://github.com/lakeba/agent-team.git` (that installs the CLI only). Keep one
copy: two installs mean two versions, and the one first on your `PATH` wins.

Tab completes commands, options, choices and your members' names: the installer sets it up for
bash; for zsh, run `agent-team completion install` once (it asks before adding one line to
`~/.zshrc`).

## Quick start

```bash
cd ~/code/my-project
agent-team ready      # checklist: git, GitHub, keys, Ollama, with the fix for anything missing
agent-team init       # asks where the models run (Claude, Ollama or both), which members, how many
                      # builders and any spend limits, then writes .team.toml
agent-team keys set ANTHROPIC_API_KEY    # only if members use Claude: asks for the key (hidden)
agent-team doctor     # the checklist again, then checks every member can be reached
```

`init` finds Ollama on this machine, at `OLLAMA_HOST`, or on the machine a VM or container runs
on, and offers what it finds. To set up without questions (scripts, CI), give the choices as flags;
`--yes` takes the defaults for the rest:

```bash
agent-team init --yes --models ollama --ollama-url http://192.168.1.20:11434   # no Claude, no key
agent-team init --yes --models claude --members security,qa --builders 2 --per-day 20
```

`--models` is `mixed` (Claude leads, reviews, ships and markets; the builders run on Ollama; the
default), `ollama` or `claude`. `--members` adds the optional members (`security`, `qa`, `docs`,
`all`). With a `.team.toml` already there, `agent-team init --ollama-url URL` only changes the
team's Ollama address. The dashboard's **Settings → Team composition** offers the same choices for
an existing team, shown as a diff before anything is saved.

Keys live in `~/.config/agent-team/env`, readable only by you, so they work the same from any shell,
the dashboard, background runs and schedules (Ubuntu's `~/.bashrc`, for one, is skipped by
non-interactive shells). A variable already exported in your environment wins.

Then edit `.team.toml` (or open `agent-team ui` and use **Edit team**): set the project's
guarantees, adjust the team, give members skills (Markdown files or Claude Code skill folders added
to their prompts), set spend limits under `[limits]`, and run a workflow:

```bash
agent-team discuss "next features"                       # agree a roadmap
agent-team build "add an export command" --branch team/export --pr
agent-team ship                                          # one devops shift on GitHub
```

### The product vision

Tell the team what the product should be in `VISION.md`: who it's for, what problem it solves,
what makes it worth using. `init` asks for it (or `init --vision "..."`), and every workflow
reads it, so plans, builds, reviews and marketing all work towards it. To start the roadmap
from a vision you've written elsewhere:

```bash
agent-team discuss --vision ~/notes/tipsplit-pitch.md    # saved as VISION.md if there's none yet
```

### Other commands

| Command | What it does |
|---|---|
| `agent-team status [--json] [--health]` | The team, spend per member and today, recent and background runs, the schedule. |
| `agent-team ui` | The dashboard: see and edit the team, start runs, follow costs. |
| `agent-team jobs [start <workflow> \| stop <id> \| log <id>]` | Runs in the background, as the dashboard and the Claude panel start them. |
| `agent-team schedule --every 6h` | Run devops shifts on a schedule (launchd on macOS, cron elsewhere); `--remove` to stop. |
| `agent-team serve ...` | Serve a model on this machine as a team member for a team elsewhere. |
| `agent-team discover` | Find agent-team nodes on the local network. |
| `agent-team ready [--json]` | What this machine and project still need (git, GitHub, keys, Ollama, models), each with its fix. |
| `agent-team keys [set NAME \| remove NAME]` | API keys and tokens in agent-team's own keys file; values are never shown. |
| `agent-team issues [sync --milestone M2 --yes]` | The team's to-do list: `team:build` issues, created from the roadmap by the lead (shown first, created with `--yes`). Autopilot builds them and its PRs close them. |
| `agent-team approve [PR]` | Approve a PR's current commit when it changes paths in `require_approval`; with no number, list what's waiting. |
| `agent-team notify` | Send a test message to the `[notify]` webhook. |
| `agent-team eval [--only feature,bug]` | Runs fixed scenarios with your real models in a throwaway project (no GitHub): pass/fail, rounds and cost. Asks before spending. |
| `agent-team estimate build` | Predicts a run's cost from this project's past runs. |
| `agent-team projects` | Every project you use agent-team in: spend, runs, what waits for you. |
| `agent-team scoreboard` | Each builder's approval and first-round rate, average rounds and cost; each reviewer's pushback; cost per merged PR. |
| `agent-team memory [add TEXT \| forget N]` | The lessons the team learned from its reviews, which every member sees in later work. |
| `agent-team agents`, `agent-team doctor` | List the team; check every member can be reached. |

`build` takes `--parallel` (split the plan across every builder), `--skip qa,security,docs`,
`--rounds`, `--builder` and `--lead`. Every command takes `-C <project>`; `--help` lists the rest.

### Use it from Claude Code

The installer adds the plugin. To add it by hand, at the prompt of a Claude Code session:

```
/plugin install agent-team --marketplace lakeba/agent-team
```

Then, in any project: `/team-init`, `/team-doctor`, `/team-plan`, `/team-build <task>`,
`/team-ship`, `/team-fix <PR>`, `/team-schedule <6h>`, `/team-market` and `/team-ui`. Claude runs the workflow where you can watch it, checks the
result, and reports back. In projects with a `.team.toml`, the plugin also opens an agent-team side
panel (or run `/team-panel`): the team, each member's health, recent runs and spend, with buttons to
refresh, check health, start a devops shift and start the dashboard, plus background runs you can
stop. `/team-run build <task>` (or `fix <PR>`, `discuss <topic>`, `ship`, `market`, `doctor`) starts a run in
the background and the panel follows it. The commands need the `agent-team` CLI on your `PATH`.

## Documentation

- [Architecture](docs/architecture.md): providers, agents, workflows and how they fit.
- [Configuration](docs/configuration.md): every `.team.toml` setting.
- [Extending](docs/extending.md): add a team member, a role, a provider or a workflow.
- [Remote agents](docs/remote-agents.md): let another machine join the team.
- [Examples](examples/): the todo-py team, and a larger team across four machines with security,
  QA and docs members, parallel builders and spend limits.
- [Changelog](CHANGELOG.md) and [roadmap](ROADMAP.md).

## Licence

MIT, see [LICENSE](LICENSE).

## Status

Released on [PyPI](https://pypi.org/project/agent-team/) and [GitHub](https://github.com/lakeba/agent-team/releases);
see the [CHANGELOG](CHANGELOG.md) for what each version changed, [ROADMAP.md](ROADMAP.md) for what's
next and [CONTRIBUTING.md](CONTRIBUTING.md) to help.
