# Open Agent Team

Open Agent Team Logo

NPM Version NPM Downloads

This project lets you build a declarative **agent team** with a 3-layer hierarchy: `Admin -> Leader -> Worker` You declare roles, models, shared skills, and workspace/git strategies in `team.json`. Admin governs project work, Leaders review and integrate Worker branches, and Workers deliver self-tested short-lived Git branches. A Worker never merges directly: it submits a persisted review request; only an Admin-approved, serialized MergeController updates `main`/`master`. See the [Git collaboration workflow](docs/zh-CN/git-collaboration.md) for branch naming, review, release approval, artifact manifests, and runtime-file isolation. ## Quick Start ### 1. Install **Via One-liner Script (Recommended):** **macOS & Linux:** ```bash curl -fsSL https://oat.ibert.me/install.sh | bash ``` **Windows:** ```powershell powershell -c "irm https://oat.ibert.me/install.ps1 | iex" ``` **Via NPM:** ```bash npm i open-agent-team -g ``` ### 2. Create `team.json` Create a `team.json` in your project root (see [team.example.json](./team.example.json) for a full example): ```bash oat init ``` ### 3. Start your team ```bash oat start team.json ``` ### 4. Open OAT Desktop Use the Desktop application for project management, task operations, observability, configuration, usage, achievements, plugins, channels, Git delivery, and Docker runtime management. ## Key concepts ### Declarative configuration (`team.json`) - `team.json` defines: - global default model (`model`, optional) - global provider integration (`providers`, optional) - project metadata (`project`; `project.base_branch` must be `main` or `master`, default `main`) - model alias mapping (`models`) - `Admin` agent config (`admin`) - team configs (`teams[]`: `Leader` + `Worker`) - If `admin.prompt` / `leader.prompt` / `worker.prompt` ends with `.md`, the loader treats it as a file path and loads the file content as prompt text. - Model inheritance chain: `worker.model -> leader.model -> admin.model -> model` (you can override at any level). See the detailed field reference: `oat docs config --lang en`. ### Isolated workspaces (git worktree) By default, each agent runs in an isolated workspace created via `git worktree`, under: - `workspace.root_dir` (default: `/workspaces`) For large repos, sparse-checkout can be enabled; worker sparse-checkout paths come from `teams[].leader.repos`. ### Skills management (`npx skills`) Skills are managed via [`npx skills`](https://github.com/vercel-labs/skills) and declared in `team.json` as `SkillEntry` objects: - Each entry specifies a `source` (GitHub repo, URL, or local path) and optional `names` filter - On startup, OAT runs `npx skills add` for each entry and installs skills into `/skills/` - A `.pi/skills` symlink is created for pi-coding-agent compatibility ### Git-reviewed collaboration When initializing agents, the Orchestrator injects system constraints: - `CHANGELOG.md` is human-readable delivery evidence, not the collaboration bus. - A Worker calls `submit-review` after implementation and self-tests; the request records branch, commit, changed files, tests, and an artifact path. - A Leader explicitly reviews with `review-worker-branch`, merges approved branches into an integration branch, and creates a release proposal. - Admin approves or rejects the proposal with `approve-release`; only the serialized MergeController can update `main`/`master`. - Logs, drafts, Agent metadata, and other runtime files are stored in `/git-collaboration/`, not in Git worktrees. ## Quick start ### 1) Configure skills (optional) Declare skill sources in `team.json` using the `SkillEntry` format: ```json "skills": [{ "source": "vercel-labs/agent-skills", "names": ["frontend-design"] }] ``` ### 2) Create `team.json` Refer to: - `docs/en/guide.md` (minimal example + run steps) - `docs/en/config.md` (field-by-field reference) ### 3) Start Orchestrator ```bash oat start team.json [goal] ``` Choose output/docs language: ```bash oat start team.json [goal] --lang zh-CN ``` **OAT Desktop** provides real-time observability, project configuration editing, global settings, multi-project management, task operations, and Project Achievements for browsing daily work records and `CHANGELOG.md` history. ### 4) Useful commands ```bash oat list oat stop oat docs architecture --lang en oat docs config --lang en oat docs guide --lang en ``` ## How collaboration works (high level) 1. Orchestrator installs skills via `npx skills add`, starts `Admin`, each `Leader`, and pre-spawns a `Worker` pool (size = `teams[].worker.total`). 2. A `Leader` calls the tool `dispatch-worker-tasks` with a list of `tasks`. 3. Orchestrator dispatches tasks to the pre-spawned `Worker` pool: - connects to the target worker - sends the task prompt 4. Each Worker creates a task-specific branch from a pinned `main`/`master` SHA, self-tests, commits only Git-reported changes, and calls `submit-review`. 5. Leader reviews each request before merging it into a task integration branch. Rejected reviews create a new task attempt; no code is merged before review. 6. Leader submits a release proposal with artifact paths. Admin approves/rejects it; MergeController serializes the atomic main/master ref update. 7. Task worktrees and manifests are retained under `state_dir/git-collaboration/`, keeping repository worktrees free of runtime garbage. ## Current implementation notes (aligned with code) - Runtime mode: `local_process` is implemented (Orchestrator starts multiple agent processes on different ports). - Workspaces: `worktree` provider is implemented; other providers are placeholders. - Worker pool size intent (`teams[].worker.total`) is enforced by pre-spawning workers at team startup; workers are not cleaned up after a leader completes (only on orchestrator shutdown). ## Push Channel Notification & OpenClaw Plugins OAT supports sending task progress, agent crashes, and final achievements to external chat channels (e.g. Slack, Discord, WeChat), fully compatible with the OpenClaw plugin ecosystem. ### 1) Configuration File (`~/.oat/oat.json`) All global settings are natively stored in standard JSON at `~/.oat/oat.json`. A typical structure for channels is: ```json { "channels": { "openclaw-slack": { "accounts": { "team-slack": { "webhookUrl": "https://hooks.slack.com/services/..." } } } } } ``` To route task manager push notifications to a channel, declare the target in `team.json` under `admin.push_channel`: ```json "admin": { "name": "AdminAgent", "push_channel": { "channel": "openclaw-slack", "account": "team-slack" } } ``` ### 2) CLI Commands Manage compatibility plugins and accounts directly from the terminal: - `oat channels` - View all loaded plugins, configured accounts, and active WeChat sessions. - `oat channel login ` - Guideline/interactive ASCII QR scanner setup for stateful channels (e.g., WeChat): ```bash oat channel login weixin my-wechat ``` - `oat plugins install ` - Download and hot-install an OpenClaw-compatible plugin from NPM: ```bash oat plugins install @tencent-weixin/openclaw-weixin ``` - `oat plugins uninstall ` - Remove a plugin physically from disk, wiping its cached sessions and credentials. ### 3) Visual Plugin Center (Desktop) OAT Desktop includes a native **Plugin Center** to: - View status cards of installed plugins and active accounts. - Enter NPM package names to download and hot-install plugins dynamically in one click. - Configure new accounts dynamically via visual form fields compiled directly from the plugin's configuration schema (`configSchema`). - Guide users on scanning WeChat interactive QR codes in their CLI terminals. ## Other languages - `README.en.md` - `README.zh-CN.md` - `README.fr.md` - `README.ja.md` ## Acknowledgments ## Star History Star History Chart ## LICENSE MIT © Herbert He