TeamAI — The team harness for AI agents

# TeamAI — The team harness for AI agents

> [English](README.md) | [简体中文](README.zh-CN.md)

[![CI](https://github.com/Tencent/teamai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Tencent/teamai-cli/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/teamai-cli.svg)](https://www.npmjs.com/package/teamai-cli)
[![npm downloads](https://img.shields.io/npm/dm/teamai-cli.svg)](https://www.npmjs.com/package/teamai-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Make every AI coding agent work by the same harness. Git-native management of skills, rules, and docs across 20+ AI tools — for you or your whole team.

**Supports:** Claude Code, Codex, Cursor, CodeBuddy IDE, as well as Gemini CLI, Windsurf, Trae, Aider, Amp, OpenClaw, and 20+ other AI coding tools (skills sync).

> 📖 **Full usage guide:** [docs/usage-guide.md](docs/usage-guide.md) — covers everything from team creation to day-to-day use.

> 📚 **Provider notes:** [docs/providers.md](docs/providers.md) — GitHub / TGit differences and auth setup.

Questions or suggestions are welcome — please open a PR or an Issue and help build this project together.

## Install

```bash
npm install -g teamai-cli
```

<details>
<summary>Tencent internal users: install <code>@tencent/teamai-cli</code> via tnpm</summary>

```bash
npm install -g @tencent/teamai-cli --registry=http://r.tnpm.oa.com
```

The two packages share identical source code; `@tencent/teamai-cli` is just the internal mirror of the public `teamai-cli`.
</details>

## Quick Start

### Team members

```bash
# User-scope init (default, resources installed under ~/)
teamai init --repo yourteam/yourproject

# Project-scope init (resources installed under the project directory)
cd /path/to/my-project
teamai init --repo yourteam/yourproject --scope project

# Non-interactive mode (for CI/CD or AI-agent automation)
teamai init --repo yourteam/yourproject --scope user --role hai_dev --force
```

### Admins

First create the shared-experience repo on your git host (GitHub by default; TGit also supported) and grant write access to every team member.

- **GitHub:** create with `gh repo create yourorg/yourproject --private` or via the UI. Then use Settings → Collaborators to add members, and set `master`/`main` as the default branch.
- **TGit (Tencent Gongfeng):** create on [git.woa.com](https://git.woa.com/) and grant master permissions in bulk via user groups.

The CLI picks a provider automatically from the repo URL:

- `yourorg/yourrepo` or `https://github.com/yourorg/yourrepo` → GitHub
- `https://git.woa.com/yourteam/yourrepo` → TGit

## Commands

| Command | Description |
|---------|-------------|
| `teamai init [--scope <user\|project>] [--role <id>] [--force]` | Initialize (auto-installs gf CLI, OAuth login, links repo, registers member, configures reviewers, injects hooks) |
| `teamai push [--all] [--role <id>]` | Push local new resources to a dedicated branch and open a Merge Request; new skills prompt interactively for a target namespace (override with `--role`) |
| `teamai pull [--silent]` | Pull team resources and inject them into local AI tools (both scopes pulled sequentially) |
| `teamai status` | Show the diff between local and the team repo |
| `teamai list [type] [--source repo\|local\|all] [--agent <id>]` | List resources (skills\|rules\|docs\|env\|wiki). With `--source local` or `all`, scans skills directories of installed AI agents and tags each skill's origin (`[team]` / `[builtin]` / `[source:<name>]` / `[local-only]`) |
| `teamai skill [list\|show <name>]` | List all skills by default; `show <name>` prints the skill's origin, contributors, installed-agent list, and description summary |
| `teamai members` | List registered team members |
| `teamai remove <type> <name>` | Remove a resource from both the team repo and local, then open an MR (skills\|rules\|wiki) |
| `teamai roles` | Manage team roles (`init`/`list`/`set`/`add`/`remove`/`update`) |
| `teamai source` | Manage cross-team skill subscription sources (`add`/`remove`/`list`/`browse`) |
| `teamai contribute --file <path> [--scope <user\|project>]` | Push an AI-generated experience document to the team repo |
| `teamai recall <query>` | Search the team knowledge base, automatically merging user + project scope results |
| `teamai digest` | Generate a team AI usage weekly digest (skill leaderboard, new/updated skills, session summaries) |
| `teamai hooks` | Manage AI-tool hooks (list / inject / remove) |
| `teamai uninstall [--force]` | Uninstall teamai: remove hooks, rules, skills, env, docs, and `~/.teamai/` |
| `teamai doctor` | Diagnose configuration problems |

Global options:
- `--dry-run` — preview mode, no real changes
- `--verbose, -v` — verbose output

## How It Works

```
Member A                             Member B
  create skill / write rules           same
    │                                     │
    ▼                                     ▼
  teamai 

... (truncated)