WebTeam Agents

A reusable team of AI agents for web development: planner, backend developer, frontend developer, security reviewer, and code reviewer. Install one CLI, configure your own model access, and use the same editable agents across your projects.

Early release: the orchestration, credential handling, and file boundaries have offline automated tests. Model quality varies; review generated changes before applying them. This is a local development tool, not an unattended production deployment service.

Install and set up

Requires Python 3.10 or newer. Use either:

uv tool install webteam-agents

or install into an activated Python virtual environment:

python -m pip install webteam-agents

Then:

webteam setup

Setup asks for:

1. Provider — Gemini, OpenAI, Anthropic, Groq, Mistral, DeepSeek, OpenRouter, xAI, Ollama, a custom OpenAI-compatible endpoint, or another LiteLLM provider.
2. Model ID — the exact model available to your API account or local runtime.
3. Endpoint, when needed for custom/local providers.
4. API key, with hidden terminal input. Ollama does not require a key.
5. Whether to save the key in your OS credential store.

The installer itself never asks for or sends credentials. webteam setup is the onboarding step after installation, and an interactive first run offers it if no connection is configured. No model call is made during setup.

Keys are never written to project JSON, source code, or run metadata. If an OS credential store is unavailable, use your provider's environment variable or enter the key per run; there is no plaintext file fallback. A key entered during setup without choosing to save it is discarded. Each teammate supplies their own access and pays their own provider usage charges.

Optionally verify access and tool calling with one small request (which may incur provider charges):

webteam doctor --check-model

webteam doctor without the flag checks local configuration only. A provider listing a model does not guarantee your account can use it. The selected model must support function/tool calling; not every vendor, model, API plan, or enterprise authentication scheme is supported. See LiteLLM providers for adapter details. Enterprise IAM-only setups may require an authenticated compatible gateway.

Use with any project

Initialize project-specific settings:

webteam init --project /absolute/path/to/project

Edit the generated webteam.json to provide commands that verify that project. For example:

{
  "checks": [
    ["npm", "ci", "--ignore-scripts"],
    ["npm", "test", "--", "--run"],
    ["npm", "run", "build"]
  ],
  "exclude": ["private/*", "customer-data/*"],
  "max_cycles": 3,
  "max_calls": 100
}

These are examples, not universal Node commands. Adapt them to your actual package scripts. Dependency directories are not copied into the working snapshot, so include preparation commands when required. Some projects need install scripts; enable them only for trusted projects. A Python project's check might be ["uv", "run", "python", "-m", "unittest", "discover"].

Run a task:

webteam run --project /absolute/path/to/project \
  --allow-checks "Add a profile page and API for changing a display name"

The team works in a separate project copy. Your source project is changed only by the explicit apply command:

webteam status /absolute/path/to/run-directory
# Review changes.diff and state.json in that directory first.
webteam apply /absolute/path/to/run-directory

No Git commit, push, or deployment happens automatically.

Workflow

Request + isolated project snapshot
                |
             Planner
                |
      Security threat assessment
                |
      Backend (when assigned)
                |
      Frontend (when assigned)
                |
       Configured test/build checks
                |
      Independent security assessment
                |
       Independent code review
                |
      All checks pass; no blockers?
           /                \
         Yes                 No
          |                   |
 Completed working copy   Route repair to owner
          |               (bounded iterations)
 User reviews diff            |
          |              Repeated failure / budget exhausted
 Explicit apply               |
 with conflict checks     Blocked, reports preserved

Agent	Inputs	Outputs and permissions
Planner	Task, project conventions, source, configured checks	Acceptance criteria, contracts, backend/frontend assignments; read-only
Backend	Assignment, contracts, review findings	Server implementation and regression tests; isolated-copy write access
Frontend	Assignment, contracts, backend report	UI implementation and tests; isolated-copy write access
Security	Plan or implementation, source, check results	Findings with owners and verification steps; read-only
Reviewer	Requirements, changed paths, source, check results	Correctness findings or acceptance; read-only

Each role gets a separate conversation. The controller passes explicit reports and enforces tool access; model text cannot grant permissions or override completion checks. Backend and frontend run sequentially to avoid concurrent edits. Their scope is instruction-based within the isolated project; planning and review write restrictions are enforced in code.

Customize your shared agents

webteam agents --export /absolute/path/to/my-agents
export WEBTEAM_AGENTS_DIR=/absolute/path/to/my-agents

Edit planner.md, backend.md, frontend.md, security.md, and reviewer.md. That one folder supplies the roles for all projects. Select a different folder for a single run with --agents-dir.

Keep project conventions in that project's AGENTS.md or GEMINI.md. Keep verification commands and project exclusions in webteam.json. Keep provider credentials personal.

Configuration

Personal connection metadata lives in ~/.config/webteam/connection.json, respecting XDG_CONFIG_HOME. Override the directory with WEBTEAM_CONFIG_DIR. Re-run webteam setup to change providers. Custom endpoints must use HTTPS; localhost HTTP is allowed for local runtimes. Saved credentials are bound to the provider and endpoint.

Environment variables take precedence over saved credentials:

Provider	API key environment variable
Gemini	GEMINI_API_KEY
OpenAI	OPENAI_API_KEY
Anthropic	ANTHROPIC_API_KEY
Groq	GROQ_API_KEY
Mistral	MISTRAL_API_KEY
DeepSeek	DEEPSEEK_API_KEY
OpenRouter	OPENROUTER_API_KEY
xAI	XAI_API_KEY
Custom compatible endpoint	WEBTEAM_API_KEY
Other provider	Name chosen during setup

Use your shell or secret manager to provide keys; do not put literal keys in shared commands. --model, WEBTEAM_MODEL, or a project's model field can override the model within the personally configured provider. models can select a different model for each role within that same provider. An empty model uses the personal choice. A project cannot change the provider endpoint or select another provider's credential.

Supported project keys: model, models, checks, exclude, max_cycles, max_turns, max_calls, timeout_minutes, check_timeout_seconds.

Run data defaults to ~/.local/state/webteam. Override with --state-dir or WEBTEAM_STATE_DIR; storage must be outside the target project. Each run contains:

• state.json: task, stage reports, findings, checks, usage, final status.
• changes.diff: proposed changes against the original snapshot.
• workspace/: isolated editable copy.
• original/: initial snapshot.
• backup/: originals replaced by an explicit apply.

Execution boundaries and failure handling

--allow-checks authorizes the configured test/build commands on your host. Commands can execute arbitrary project or generated code. A copied directory is not an OS sandbox. Use trusted projects or run the whole CLI in a container/VM for untrusted code. No arbitrary shell tool is exposed to the models.

Common secret filenames, dependency/build directories, and symlinks are excluded. Filename filtering is not a secret detector; add project-specific exclusions. Content read by agents and check output is sent to your configured provider, unless using a local endpoint. Source and check output remain in local run artifacts; keep them private and delete them when no longer needed.

Agents cannot edit project policy files. Text tools are limited to 256 KB per file. Snapshots are limited to 10,000 files / 100 MB; exclude large assets as needed. Binary editing and explicit deletion are not exposed to models.

Default limits: 3 repair cycles, 20 turns per role, 100 provider attempts, a 30-minute budget checked before model calls, and 120 seconds per check. In-flight calls may finish after the run budget; this is not strict wall-clock cancellation. Retries are bounded with backoff. Token totals are informational, not a guaranteed spending cap.

Missing or unauthorized checks, unresolved blockers, repeated identical failures, and exhausted budgets cannot produce a completed run. Interruptions retain completed reports and working files; automatic mid-run resume is not implemented. Start a new run after resolving the blocker. Exit code 0 means success; 2 means invalid, blocked, interrupted, or failed.

Apply verifies that the workspace is unchanged since review and rejects conflicts with your source. Do not edit the source concurrently during apply. Backups and rollback handle caught copy errors; an abrupt machine failure is not a filesystem transaction.

Development and validation

From a source checkout:

uv run python -m unittest discover -s tests -v

Offline checks exercise permissions, conflict handling, failure loops, provider routing, credential storage behavior, and the model probe using mocked responses. They do not prove live vendor compatibility or model quality. Use doctor --check-model and a disposable project with known tests to evaluate your selected model.

Use one run per target project at a time. Independent projects can run in separate processes and share provider account quotas. Distributed scheduling, global rate limiting, unattended release, enforced monetary caps, and crash-resume require additional infrastructure.

License: MIT. Provider use remains subject to each provider's terms.