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).

Try it first

agent-team try

A minute, in a throwaway folder: a two-member team (Atlas leads, Forge builds) adds a feature to a small sample CLI, runs its tests and reviews the result. It uses Claude when a key is set, else a local Ollama model, else a recorded run that calls no model at all, so it works on a fresh machine (--with claude|ollama|replay to choose, --keep to keep the folder).

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

Behaviour checks with REA

Tests check what their authors thought of. A behaviour check uses the program the way a user would, before and after the team's change, and shows the lead what changed: "after stop, status still shows the timer running", with the screens as evidence. It works for command-line programs, web apps (a browser follows plain-words steps like click button "Start", each with its own deadline, and the report names a step that failed), Electron desktop apps (their windows, the IPC channels and external effects they attempt) and libraries (the public API of a .NET assembly or a JavaScript package).

agent-team rea setup          # installs REA (https://rea.tools) if needed and sets it up
agent-team behaviour suggest  # the lead writes the first journeys from VISION.md

From then on, build has the QA member (or the lead) add the journeys each task needs and runs them every round; the dashboard's Behaviour tab shows before and after side by side. Releases follow the evidence (removing a public member needs a major version), the security member also reviews what the build ships, and an optional scout looks at other products from the outside before the team plans (a site can have steps first, such as accepting a cookie dialog). REA is one of the tool servers the team can use over MCP: any [mcp.*] server's allowed tools can be given to members (mcp = ["rea"]). See configuration.

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.

Everything in ECC, for the team

ECC is a large, MIT-licensed library for coding agents. agent-team uses a pinned ECC release (fetched once, only what it needs) and maps each part onto the team:

agent-team ecc skills "rest api"        # search ECC (agents, skills, commands, rules)
agent-team templates apply              # one piece per role, plus rules, for your language
agent-team ecc library on               # members read any ECC skill when a task needs it

Templates. agent-team templates lists ten (python, react, typescript, dotnet, go, rust, kotlin, java, swift, general); apply gives the lead ECC's reviewer for the language, the builders its patterns skill, QA its testing skill, the security, docs and marketing members ECC's agents for those jobs, and everyone the language's rules. Everything is copied into team/skills/ecc/ and team/rules/ecc/ with ECC's licence (NOTICE.md) and named in .team.toml, so you review and commit it like any other file. Skills and rules go with every call, so each command shows how many characters it adds first; the library costs nothing until a member asks for a skill.

Guards. Members can't weaken an existing linter or formatter config to make a check pass (unless the task names the file), and a change to a sensitive file (CI, migrations, authentication, payment, secrets, deployment) waits until the member writes a WHY path: ... line with the facts it rests on. A held-back change keeps the build open. [project].protect_config and gate_sensitive turn them off.

Use it from any coding agent (MCP)

agent-team mcp serves the team over the Model Context Protocol, so Claude Code, Codex, Cursor and other agents can see the team and start its runs ("have the team build the export command as a PR"):

agent-team mcp install --client claude     # or codex, cursor; asks first
agent-team mcp config                      # the snippets, to add by hand

The tools: team_status, team_ready, team_start_run (build, fix, discuss, ship, autopilot, market, doctor, in the background), team_run_output, team_runs, team_stop_run and team_behaviour. Runs keep the same spend limits and guardrails. Approving pull requests and releases isn't offered: that stays with you.

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.