agent-team

by Lakeba · Conceive · Create · Commercialise
Website · PyPI · Changelog

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.

How the team works

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 models on this machine or others, or both; a team on Ollama alone needs no API key. Optional: Ollama 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 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:

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

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:

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:

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:

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

Other commands

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: providers, agents, workflows and how they fit.
• Configuration: every .team.toml setting.
• Extending: add a team member, a role, a provider or a workflow.
• Remote agents: let another machine join the team.
• Examples: the todo-py team, and a larger team across four machines with security, QA and docs members, parallel builders and spend limits.
• Changelog and roadmap.

Licence

MIT, see LICENSE.

Status

Released on PyPI and GitHub; see the CHANGELOG for what each version changed, ROADMAP.md for what's next and CONTRIBUTING.md to help.