Scenario: Admin — day-to-day management
The user already ran teamai init. Do NOT re-init or re-register. Before changing
anything, say what you are about to change. Pick the task below that matches.
Day-to-day management is mostly publishing and updating team resources — skills, rules, MCP servers, and env — plus inviting members and checking the dashboard.
Publish or update a skill / rule / doc
The user (or you) creates or edits a skill, rule, or doc locally, then publishes it
to the team. The same teamai push handles both new resources and updates to
existing ones:
teamai push # review the diff, then confirm
teamai push --all # push everything without per-item confirmation
teamai push --skill <path> # push one specific skill
teamai push --branch <name> # use an explicit branch for a new pushAn existing open PR is updated on its recorded branch. TeamAI refuses to reset a team-repo clone with unrelated modified, staged, untracked, or conflicted files; commit or stash those changes before retrying.
Members receive it automatically the next time they open a session (or when they
run teamai pull).
Publish or update team MCP servers
teamai mcp list # team MCP servers + per-tool install status
teamai mcp inject # push team MCP servers into every AI tool's config
teamai mcp remove --dry-run # preview removal without changing tool configs or managed records
teamai mcp remove # remove teamai-managed MCP serversmcp inject and mcp remove return exit code 1 if a tool config cannot be read or parsed, including in a dry run. Other tools may still change. Fix the config named in the warning and rerun the command; the unreadable config and its ownership records are kept for that retry.
MCP definitions travel with the team repo like skills/rules — edit, then the members pick them up on sync.
A server with a ${VAR} the tool cannot expand itself gets the resolved value
written into its project config (.mcp.json, .cursor/mcp.json, ...). With
sharing.gitExclude on, Claude's (not in a team in self mode, whose worktrees
each read their own branch's servers) and CodeBuddy's and WorkBuddy's servers go to their local
scopes in ~/.claude.json and .codebuddy.json instead, outside the project,
and the next pull (on an HTTP-backed team, the local agent's next sync) moves
teamai's servers out of .mcp.json. Before
that write, teamai lists the file in the clone's .git/info/exclude, inside a
# [teamai:mcp-exclude:start] block; the committed .gitignore is never touched.
A file under a symlinked directory is listed and checked where the write lands
(.cursor/ linking to config/: /config/mcp.json); a config that is itself a
symlink stays one, and its target is listed in, and checked by, its own repository.
When it cannot (git already tracks the file, a rule in the member's git ignore
files re-includes it, .git/info is not writable, the exclude file is held by
another teamai command, or git errors), it leaves the file as it was, warns, and
teamai mcp list shows withheld: <tool> — <reason>. <fix>. Apply the fix it
names (a tracked file: git rm --cached <file> and rotate the token; a
re-including rule such as !/.mcp.json: remove it), then run teamai pull. A pull or teamai mcp remove takes a line out
once its file no longer holds a resolved value; teamai uninstall does so in
every worktree. A file written under a toolPaths.<tool>.mcpProject the team
later changes or removes stays listed until it is deleted or holds no server;
for one an older teamai wrote, the first pull finds the path in the team repo's
history of teamai.yaml, or among the built-in paths teamai has since changed
(not one the same tool maps today), and lists it while it holds any server; one
git tracks is recorded instead and listed once the member runs git rm --cached
on it. teamai doctor checks those paths until that pull. A file written for a
tool the team moved elsewhere (recorded, or found in that history), that another
tool still maps, stays listed while it holds a server that tool did not write,
one of the member's own included. The built-in location of a tool the team drops
from toolPaths or moves elsewhere stays listed while it holds any server; one
another tool maps today (CodeBuddy's .mcp.json, which Claude maps) while it
holds a server that tool did not write. A file two tools map, with no pull on
this version having recorded it, needs a managed-mcp.json record from each of
them. While a worktree has no managed-mcp.json at all (lost, or before its
first pull), an untracked config holding a server no record claims is listed,
and that server noted: it keeps the line until it leaves the file. So is the
file of a tool managed-mcp.json has no record for, when a pull writes that
tool's first record (its record lost, or teamai's first delivery to it). While that
note cannot be written (another teamai command holds the record), the line stays
until a later pull writes it. A Copilot project config's bare top-level servers
still count once another tool writes mcpServers into the file. On an HTTP-backed
team the local agent's install_mcp lists a project config before writing a
server with any header, env value, argument or URL (only a bare stdio command is not), fails the install when it cannot, and only
teamai uninstall takes that line out. The next sync or teamai pull in the
workspace also lists a file an older local agent wrote a credential into; teamai doctor checks those files too.
ZCode servers use mcp.servers in ~/.zcode/cli/config.json or the project's .zcode/config.json. This follows the 3.16.2 source; 3.15.1 is not certified. Pull moves only unchanged teamai entries out of ~/.agents/mcp.json. Doctor names other servers there because the desktop app stops reading that fallback once the native config has servers.
Antigravity takes user servers in ~/.gemini/config/mcp_config.json. It reads a project's servers only from a plugin, so teamai writes them to .agents/plugins/teamai/mcp_config.json with a plugin.json ({"name": "teamai"}) beside it. agy takes stdio and HTTP servers; pull skips an sse server for agy with a warning. agy mcp list shows only the user file's servers.
WorkBuddy uses the first existing user file in ~/.workbuddy/.mcp.json, ~/.workbuddy/mcp.json, and ~/.codebuddy.json. CODEBUDDY_CONFIG_DIR moves the last file. A project uses .mcp.json, or mcp.json when only that exists. With sharing.gitExclude on, its servers use projects[<project path>].mcpServers in .codebuddy.json. These paths follow the CodeBuddy 2.168.0 engine; WorkBuddy's launcher binding is not certified. Pull removes only unchanged teamai entries from the former .workbuddy/mcp.json project file.
When .workbuddy-ai/ exists in the home or project (WorkBuddy AI, the international edition), the default skills path moves to .workbuddy-ai/skills. Every other surface still waits for .workbuddy/, so a member with only .workbuddy-ai/ gets no rules, team instructions, agents, MCP servers or hooks, and teamai doctor fails workbuddy receives ... with the ones held.
When a tool's home or configured MCP path moves, pull leaves old copies in place and names them once. Remove them after no tool reads them. Doctor reports unread mappings, moved files, and project MCP that is read only from a session started at the project root. Internal builds with an unknown MCP channel get a note instead of a guessed config.
Pi MCP delivery
Pi 0.99.0+ receives stdio and streamable HTTP servers through the existing MCP commands and teamai pull; SSE is skipped. User scope writes ~/.pi/agent/mcp.json, workspace scope writes .pi/mcp.json (Pi requires project trust). TeamAI keeps Pi's default codemode exposure and converts timeout milliseconds to seconds. User MCP follows PI_CODING_AGENT_DIR. Project MCP is read only from a session started at the project root. Local exposure/enabled edits on managed servers survive until the team definition changes; doctor reports differences from the team entry. Extensions that replace /mcp must be removed to use Pi's built-in MCP.
Invite a member
There is no CLI invite flag. Inviting is done on the Git platform's website:
- On the platform (GitHub / GitLab / CNB), add the person to the team repo (Settings → Collaborators / Members).
- Send them the full repo URL and this line to paste into their AI tool:
/teamai Help me join my team's TeamAI, repo URL is <URL>
(If you want to see who is already registered: teamai members /
teamai members list.)
See members and resources
teamai members list # registered team members
teamai list # all resource types
teamai list skills # just skills
teamai status # local vs team differencesRoles (skill namespaces per job function)
teamai roles list # roles defined + your current role
teamai roles init # create the roles manifest (admin, interactive)
teamai roles add <id> # add a role
teamai roles update <id> # change a role's namespaces / description
teamai roles remove <id> # remove a roleAfter editing roles, teamai push to publish the manifest. Members re-sync on
their next session.
To assign roles in the team repo instead of letting each member pick one, add
manifest/members.yaml (members: { alice: [frontend] }, default: [] for
members it does not list). While it exists, teamai roles set is refused and
an unlisted member receives shared resources only. Who may edit the file is the
forge's decision (protected branch, code owners for manifest/); teamai keeps
no access list. Details: docs/guide/distribution.md, "Assigning roles in the
team repo".
Projects (manage several projects from one repo)
project is a second dispatch dimension alongside role — one team repo can serve
multiple projects, each with its own skills/rules/learnings, without a separate
repo per project:
teamai projects list # projects defined + the ones active in this directory
teamai projects set [ids...] # set the active project(s) for this directory
teamai projects members <id> # who is registered on a project
teamai projects add <id> --namespaces common,<id> # add a project (creates projects.yaml if needed)
teamai projects update <id> --add-namespaces <ns> # or --remove-namespaces / --name / --description
teamai projects remove <id> # remove a projectA workspace (a folder set up with init) also delivers the projects of the
repos set up inside it, up to three levels down, with no list to keep: teamai projects list there shows each one and what it selects. A repo that uses
another team repo, or self mode, is left out and named.
A member gets the union of their role resources and their active project's
resources. Admins declare projects in manifest/projects.yaml with the commands
above, each of which opens a PR. roles init/add/update/remove and
projects add/update/remove support --dry-run without pulling the team repo.
Clone previews use the contents after a real pull on the checked-out branch: an
ahead branch stays ahead, a behind branch advances, and a diverged branch uses
origin/current-branch. roles init preview checks that manifest before asking
for overwrite confirmation. After projects remove,
keep the project's content in the team repo until members have pulled: that is
what lets their next pull clean up the copies they deployed.
roles init/add/update/remove and projects add/update/remove previews, and resource removal
previews, refuse a team clone with uncommitted changes. Commit or stash them before retrying. Self mode
previews still work with dirty business files because they read origin. Clone
previews refresh the configured upstream first, even when its branch or remote
name differs. A failed fast-forward or missing upstream uses origin/current-branch
for the real reset fallback. Removal refuses when that refresh also fails.
Every namespace that names a directory — knowledge, skills, agents, env,
hooks, mcp, models, docs and wiki in either manifest, and learnings in projects.yaml (a role's learnings: is
not checked) — must be a single path segment: no /, \, : or control character, no trailing
. or space, and not a Windows device name (CON, NUL, COM1, …). team-codebase
cannot be a docs namespace (docs/team-codebase/ is the legacy codebase output). Two
namespaces of one resource type may not differ only by case, across both
manifests. A manifest that breaks this, does not parse, or is empty stops
members' pull for that scope until it is fixed; the error names the entry. Fix
it rather than deleting it — with no roles.yaml, delivery is unfiltered.
An item in an active namespace replaces the root item of the same name, whole:
a skill by directory name (including a root skill a member gets through a tag),
an agent by file stem, a rule by first-level file name (rules/<ns>/<name>.md
replaces rules/<name>.md), and a claudemd/<ns>/<name>.md file replaces
claudemd/<name>.md. Use this to give a project its own version of a shared
item under the same name, and keep that shared item at the root rather than in
a namespace every role activates: rules/code-style.md is replaced by
rules/checkout/code-style.md for checkout members, while a
rules/common/code-style.md would reach them alongside it. The same skill or
agent name in two namespaces one member has active is an error naming both
files; two namespace rules or claudemd files of one name are both delivered.
Shared instructions live in claudemd/, or in agentsmd/ when the team names
that directory that way — the same rules apply under either name. A repo with
both directories delivers a same-named file once, the agentsmd/ copy first.
A replacement must be usable to replace anything: a skill directory needs its
SKILL.md (pull names one without it), and while an agent file does not parse
the root agent stays installed. teamai doctor lists each replacement as a note.
A member with no role or project (on a team without manifest/projects.yaml)
gets every skill namespace, so nothing replaces anything: the root skill wins
over a namespace skill of its name, then the namespace that sorts first, and
pull names each copy it skipped and the role that would deliver it
(docs/guide/distribution.md, "One skill name in the root and in namespaces").
Docs have no override. A top-level docs/<ns>/ that any role or project lists
under resources.docs reaches only members with that namespace active; a
docs/<dir>/ nobody lists stays shared with everyone. When a member leaves the
namespace, their next pull removes its docs that still match the team copy and
keeps (and names) the ones they edited. Recall and teamai doctor follow the
same filter.
Wiki codebase slugs follow the same rule under resources.wiki: once any role
or project lists a teamwiki/evidence/code/<slug>/ slug there, recall only
surfaces it for members with that namespace active; an undeclared slug stays
shared. The slug is the project: value that teamai import prints, not
necessarily the project's manifest id.
Keep delivered files out of git
With sharing.gitExclude.enabled: true in teamai.yaml, each member's pull lists
the skills and rules (one file per line, never a skill's directory, so a file a
member adds to a delivered skill stays visible), agents, teamai-context
files, hook files and team docs (one file per line) it delivered into a project,
and each shared config file (MCP, .codex/hooks.json, OpenCode's) and CLAUDE.md
instruction files (including .claude-internal/CLAUDE.md and .tclaude/CLAUDE.md)
while it holds only teamai's entries, in teamai's delivered block in the clone's
.git/info/exclude (local to the clone, never committed), so git add -A does
not commit them; a member's own files, and copies they edited, stay visible. init writes it for a
new team; an existing team adds the line and commits it through the normal
review flow. A member overrides it on their machine with gitExcludeEnabled: true|false in the project's config.yaml (~/.teamai/projects/<slug>/config.yaml).
Either takes effect on the next pull, no --force; turned off, the next pull
removes only that block. teamai doctor says where the setting comes from and
what git still sees; teamai pull --dry-run previews the block.
In a team in self mode the committed hook settings keep only the built-ins; the
team's hooks for Claude Code, CodeBuddy and Qoder go to the settings.local.json
beside them, listed in that block, and Codex's run from ~/.codex/hooks.json.
The other tools have no such file, so their team hooks stay in the committed file.
Team dashboard (web UI)
teamai dashboard # start the AI coding session dashboard (default port 3721)
teamai dashboard --port 8080 # custom portOpens a local web UI for team coding-session activity, workflow runs, scorer pass rates, benchmark runs over time, and knowledge-base health.
Team packages (npm + Claude plugins)
Declare packages once; members get a prompt to install them (TeamAI never runs third-party package code automatically):
teamai packages install typescript # npm dependency
teamai packages install eslint@latest --global # global CLI tool
teamai packages install code-review@claude-plugins-official # Claude plugin
teamai push # share the updated teamai.yamlShared environment variables, hooks and MCP servers
teamai env list # what reaches this directory, each with its namespace (values masked)
teamai env list --reveal # show variable values in plaintext (never a secret's)
teamai env add <KEY> <VALUE> # add or update in env/env.yaml
teamai env add <KEY> <VALUE> --project <id> # or --role <ns>: in that namespace's env/<ns>/env.yaml (warns if nothing declares <ns>)
teamai env remove <KEY> # remove (same --role / --project)
teamai env add <KEY> --secret -d "<what it is for>" --url <where to get one> # declare a secret in env/secrets.yaml, no value (same --role / --project)
teamai env remove <KEY> --secret # remove a declared secret (plain `env remove` does too when env.yaml does not set <KEY>)
teamai remove mcp <name> # root mcp/mcp.yaml or mcp/<name>/ if it has the name, else the one namespace; --role / --project pick a namespaceEnv variables, team hooks and MCP servers are scoped like skills: the root file
(env/env.yaml, hooks/hooks.yaml, mcp/mcp.yaml) reaches everyone, and
env/<ns>/env.yaml, hooks/<ns>/hooks.yaml, mcp/<ns>/mcp.yaml reach only
members whose role or project lists <ns> under resources.env, resources.hooks
or resources.mcp. A namespace entry replaces the root entry of the same key, hook
id or server name. A hook that runs a script is a folder, hooks/[<ns>/]<id>/HOOK.yaml
beside the script, its command naming it as "${TEAMAI_HOOK_DIR}/scan.sh"; an id
both in hooks.yaml and as a folder stops team hooks like a repeated name. An MCP
server the team writes is a folder too, mcp/[<ns>/]<name>/MCP.yaml beside its files,
stdio only, its args naming them as "${TEAMAI_MCP_DIR}/server.py"; a name both in
mcp.yaml and as a folder stops team MCP the same way. teamai remove mcp <name>
removes a server folder as it removes an mcp.yaml server.
Hooks and MCP servers have no add command, and teamai push
does not pick up hooks/ or mcp/: edit the file in the team repo, then commit
and push it with git. teamai doctor lists each override.
- A name twice in one file, in two active namespaces, or an active file that does
not parse: that type is not applied for affected members and their installed
state is kept. Fix the file the warning names. A hooks or MCP file with none of
its top-level keys (
server:forservers:) counts as one that does not parse. - Per-entry
projects:(androles:on env) no longer works: such an entry reaches nobody.roles:on hooks and MCP still filters for one more minor release. Pull, the list commands (teamai env list,teamai mcp list,teamai hooks list,teamai list <env|hooks|mcp> --source repo),teamai statusandteamai doctorname the namespace file each entry belongs in; move it there. Whenteamai env addupdates a variable carrying either removed key, it keeps the key and warns that pull will not deliver the variable, naming that file. - An env, hook or MCP entry with a key its schema does not know (a mistyped
role:) also reaches nobody. Pull, the list commands,teamai statusandteamai doctorname the file, entry and key; correct the key or remove it. A key a later teamai version adds is unknown to an older one, so upgrade every member before the team uses a new entry key. - Team model profiles work the same way:
models/<ns>/models.yaml, declared underresources.models, replaces the root profile with the sameidfor members who have<ns>active. A member's API key is bound to the profile's gateway origin: when an override points at another host, their pull leaves the agent alone and asks them to runteamai models switch team:<id>to set the key for it. - Secrets are declared with no value in
env/secrets.yamlorenv/<ns>/secrets.yaml(active throughresources.env; a namespace entry replaces the root entry with the same key): asecrets:list ofkey, optionaldescriptionand optionalurl(where a member gets one). Never put a value there:teamai env add <KEY> --secrettakes none and rejects one. Declare with it or edit the file in the team repo;teamai pushpicks it up. Each member sets their own value withteamai env set KEYin their terminal (--globalfor every team on their machine; a team value still wins). That updates MCP servers for the current scope. Runteamai pullafterwards only to updateenv.sh, and only when the key is an env variable.teamai env listshows each secret asteam,global,environment,missingorunreadableand never shows a value,--revealincluded. Thedescriptionis what agents see: the session-start hook lists each declared key with it and tells the agent to run the CLIs that need them throughteamai env exec --, so say which tool or server uses the key. As the agent, runteamai env add <KEY> --secretyourself and leave the value to each member's own terminal. A key declared as a secret and also set inenv.yamlis a secret: itsenv.yamlvalue is not delivered. A secrets file that does not parse keepsenv.shand MCP servers as they were, andteamai doctorfails a check naming the file. - Have every member upgrade before declaring
env,hooks,mcp,models,docsorwikiin a manifest: teamai 0.25.0 and the 0.26.0 betas reject those keys and their pull stops.
When sync fails
Run teamai doctor first. If it reports hook or path problems, load
the troubleshooting reference ("$(teamai skill path core)/references/troubleshooting.md"). Have the affected member reopen their session; if their tool
has no session-start hook, they run teamai pull manually.
Capture a lesson learned
Turning a tricky fix into team knowledge is automatic once recall is on for
the team (sharing.recall.enabled: true in teamai.yaml, then teamai push; it is
off by default, and teamai recall enable turns it on for one machine only): at the end of a session
worth sharing, TeamAI prompts the member and offers the teamai-share-learnings workflow:
its learning step runs the share skill (teamai skill get share) to summarize the
session, and its contribute step runs teamai contribute for each learning. A team file
workflows/teamai-share-learnings.yaml replaces teamai's default. Nobody has to invoke it by hand. (A member whose teamai config
cannot be loaded gets no prompt; teamai skill get share names the file and the error.)
Teams that work in English set language: en in teamai.yaml and teamai push.
That makes the built-in teamai-recall rule, the TodoWrite hint, and the merged-MR
hint English only. Omit language, or set zh, to keep the historical bilingual
text. Each scope reads its own team repo, so a project install and a user install
can differ. Members receive the recall rule in that language on the next
teamai pull.
(Publishing a reusable skill someone authored is a different task — any member
can do it, see "$(teamai skill path core)/references/contribute-member.md".)
Turn the sharing prompt on or off (admin)
The auto-share prompt is on by default once recall is on, and only shows in directories set up
with teamai (never on a read-only HTTP source, or while a member's teamai config cannot be loaded).
To disable it team-wide, set this in
teamai.yaml and teamai push:
sharing:
contributeHint:
enabled: false # team-wide default; members can still override locallyResolution order: TEAMAI_CONTRIBUTE_HINT_DISABLED=1 env kill switch > a member's
local override > this team setting > default (on). Turning it off here only removes
the nudge; members can still contribute on request.
Don't
- Don't hand-run raw
gitcommands. - Don't create a second team repo.
- Don't use
owner/reposhort form — always the full URL.
Superproject worktrees
Initialize each original submodule once. After the parent initializes submodules in a new worktree, run teamai pull --silent in each initialized child before starting an AI session; the children inherit the original config and install their own Git hooks. Independent child clones need separate init. On Git < 2.54, if the children use the parent's versioned core.hooksPath, put the dispatch line once in each applicable parent hook. Follow the admin guide for the full sequence.