Metadata-Version: 2.4
Name: webteam-agents
Version: 0.2.0
Summary: Reusable multi-provider AI agents for web development across local projects
License-Expression: MIT
Keywords: agents,web-development,cli,llm,code-review
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: litellm<2,>=1.102.1
Requires-Dist: keyring<26,>=25.7
Dynamic: license-file

# 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:

```sh
uv tool install webteam-agents
```

or install into an activated Python virtual environment:

```sh
python -m pip install webteam-agents
```

Then:

```sh
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):

```sh
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](https://docs.litellm.ai/docs/providers) for adapter details. Enterprise IAM-only setups may require an authenticated compatible gateway.

## Use with any project

Initialize project-specific settings:

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

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

```json
{
  "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:

```sh
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:

```sh
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

```text
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

```sh
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:

```sh
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.
