How TeamAI syncs skills, hooks, and MCP servers across Claude Code, CodeBuddy, and Cursor

Last month we plugged TeamAI into our team’s AI workflow. It fixed a few nagging problems we hadn’t found a good solution for:

  • Each member had different versions of local skills and rules. The same request produced different results on different machines.
  • Hook configurations relied on verbal sync. Someone forgot to install a security scanning script, and we almost committed a test‑environment secret.
  • Onboarding new members meant manually copying configs to each local tool. Missing one step cost hours of debugging.

TeamAI is not another AI coding tool. It’s a harness that stores skills, rules, docs, and hooks in a Git repository, then distributes them to Claude Code, Codex, CodeBuddy, and Cursor. Every time a member starts a session, the SessionStart hook automatically triggers teamai pull to sync the latest resources locally.

This post walks through the setup and the core features we actually use.

teamai init – connect to your team repository

The first person on the team needs to create a repository. You can use a template from the teamai-hub organisation – click “Use this template” to generate your own repo, then run:

teamai init https://github.com/yourorg/yourrepo

This command does three things: OAuth login, repository association, and pulling resources into your local AI tools. If the repository doesn’t exist yet, init creates it automatically.

Other team members point to the same repository. The default scope is project, which installs resources inside the current project directory:

cd /path/to/my-project
teamai init https://github.com/yourorg/yourrepo

Use --scope user to install globally in your home directory:

teamai init https://github.com/yourorg/yourrepo --scope user

A third option is layered mode: keep the project scope as the main configuration, while also inheriting resources from an already‑initialised user scope:

teamai init https://github.com/yourorg/project-repo --inherit-user-scope

Project scope takes precedence over user scope – if the same resource exists in both, the project version is used.

After initialisation, teamai pull runs automatically at the start of every AI session. No manual sync needed.

teamai push and MRs – enforce code review

After modifying a local skill or rule, submit it with:

teamai push

The command creates a branch, commits the changes, and opens a merge request. After a reviewer approves and merges it, other members get the update the next time they run teamai pull (which is automatic on session start).

This workflow forces peer review. We once had someone push directly to main with a broken hook configuration that broke every session. Since then we require all changes to go through push + MR, with at least one reviewer.

Hooks – uniform security policies

Hooks are declared in hooks/hooks.yaml. teamai pull distributes them to each AI tool natively.

A typical secret‑scanning hook:

hooks:
  - id: block-secret
    description: Scan for secrets before commit
    event: PreToolUse
    matcher: Bash
    command: 'bash -lc "~/.teamai/team-scripts/scan-secret.sh" || true'
    tools: [claude, cursor]

The hook triggers before a Bash tool execution (event: PreToolUse + matcher: Bash). If the scan script detects a secret, it returns a non‑zero exit code and blocks the call. The || true ensures the script doesn’t break the entire flow – it only logs a warning.

The tools field restricts this hook to Claude and Cursor. TeamAI translates the declaration into each tool’s native format.

List active hooks:

teamai hooks list

Re‑inject or remove all TeamAI‑managed hooks:

teamai hooks inject
teamai hooks remove

remove only deletes hooks that TeamAI injected – manually written hooks stay untouched.

MCP servers – declare once, sync everywhere

MCP configuration works similarly. Write mcp/mcp.yaml and teamai pull writes it into each tool’s native location:

servers:
  - name: gpu-analysis
    transport: http
    url: https://example.com/api/mcp
    headers:
      Authorization: Bearer ${GPU_ANALYSIS_TOKEN}

Secrets are referenced as environment variables – never hard‑coded. Supported transports: stdio, http, sse.

Management commands:

teamai mcp list
teamai mcp inject
teamai mcp remove

Capturing learnings – friction signals trigger documentation

At the end of each session, the Stop hook scores the session based on friction signals: you interrupted the AI, corrected it, rejected a tool call, or the AI retried failing tools multiple times.

A long, smooth session with no friction doesn’t trigger anything. Only sessions where you actually struggled are eligible.

When the score passes the threshold, the AI shows a short English prompt listing the actual signals (e.g., “you interrupted twice, the AI retried failing tools 8 times”) and a task summary. At that point you can run /teamai-share-learnings – the skill automatically summarises the session and pushes it to the team repository. Each session triggers at most once.

The shared content goes into the search index. Later, other members can find it with teamai recall. Duplicate entries (same title, date, author, and content) are merged – sharing the same learning twice doesn’t occupy two slots.

Knowledge retrieval – AI proactively searches team history

Recall is disabled by default. Enable it explicitly – team admins can set sharing.recall.enabled: true in teamai.yaml as a default, and members can override locally:

teamai recall enable
teamai recall disable
teamai recall status

After enabling, teamai pull deploys the teamai-recall sub‑agent to the agents/ directory of each AI tool. The AI calls this sub‑agent before starting a task. The sub‑agent first runs a relevance check – if the task has nothing to do with team knowledge, it skips retrieval.

You can also run the underlying command manually:

$ teamai recall "port conflict"
[1/2] MR review caught a port-conflict bug ★1 [user]
Author: member-a | Score: 18.5 | Tags: troubleshooting, networking

[2/2] Deployment configuration best practices [project]
Author: member-b | Score: 12.0 | Tags: deploy, config
Matched: conflict | Missing: port

Notice the second result only matched “conflict” but not “port” – the output adds a Missing: port line. The caller decides whether to use that result; recall does not filter it out.

In multi‑scope setups: if the current directory has a project scope, recall searches that first. If the project was initialised with --inherit-user-scope, it also searches the user scope and marks the source. Identical entries in project scope override user scope. When no project scope is present, only user scope is searched.

Recall covers four types: learnings (session experiences), docs (team documents), rules (coding rules), and skills (from each SKILL.md). These are built into search-index.json during teamai pull or teamai contribute. The code knowledge graph, generated by teamai import, is queried in real time.

Ranking uses BM25 plus graph enhancement. Hits in the current scope get an implicit vote; inherited user hits are read‑only.

Code knowledge graph with teamai import

teamai import parses source repositories into a structured graph stored under teamwiki/:

teamai import --from-repo https://github.com/org/repo
teamai import --from-org myorg

--from-org imports all repositories in an organisation. You can also import from MRs and iWiki.

The graph stores components, interfaces, configurations, and cross‑repo dependency edges. teamai recall uses this graph for enhanced ranking. When a recall result matches a codebase page, it includes a Sources: line listing the relevant source file paths – the sub‑agent can use those directly as entry points, without re‑exploring the codebase.

Health check:

teamai codebase --lint

Cross‑team skill subscriptions

Subscribe to public skill repositories from other teams:

teamai source add https://github.com/other-team/teamai-public.git --name other-team
teamai source list
teamai source browse other-team

browse lets you see available skills before deciding whether to keep the subscription. Remove a source:

teamai source remove other-team

Subscribed skills sync during teamai pull. Only the skill definitions (SKILL.md and associated scripts) are pulled – not the entire repository.

Other daily commands

Exclude a skill from local sync (so pull doesn’t overwrite it):

teamai skill exclude add <skill-name>
teamai skill exclude list
teamai skill exclude remove <skill-name>

Show differences between local and team repository:

teamai status

Delete a resource and create an MR:

teamai remove <type> <name>

Diagnose configuration issues:

teamai doctor

Remove all TeamAI resources and hooks:

teamai uninstall

Global flags --dry-run and --verbose work with any command – preview what will happen before actually executing.

Quick reference

Action Command
First‑time setup (project scope) teamai init https://github.com/yourorg/yourrepo
User‑wide setup teamai init <repo> --scope user
Layered setup (project + user) teamai init <repo> --inherit-user-scope
Submit local changes teamai push
Manually pull updates teamai pull
List hooks teamai hooks list
Inject hooks teamai hooks inject
Remove TeamAI‑managed hooks teamai hooks remove
List MCP servers teamai mcp list
Enable recall teamai recall enable
Disable recall teamai recall disable
Search team knowledge teamai recall "query"
Import code graph teamai import --from-repo <url>
Subscribe to external skills teamai source add <repo> --name <name>
Diagnostic check teamai doctor

FAQ

What is the difference between teamai init and teamai pull?

init handles first‑time setup: OAuth login, repository association, member registration, and hook injection. It also runs a pull once. pull only fetches resources and injects them into local AI tools – use it for subsequent updates.

When should I choose project scope vs user scope?

Project scope installs resources inside the project directory, so different projects can have independent configurations. User scope installs globally in your home directory – better if you share the same rules and hooks across all projects.

What is --inherit-user-scope for?

You have a project with its own configuration, but you also want to inherit security‑related resources (e.g., secret‑scanning hooks) and searchable knowledge from the user scope. Project resources take precedence over user resources if both exist.

Why is recall disabled by default?

The sub‑agent adds an extra retrieval step before every task, which increases token consumption and response latency. It’s safer to evaluate whether the benefits outweigh the costs for your team before enabling it.

How does teamai push differ from a direct git push?

push automatically creates a branch and an MR, enforcing the review workflow. Direct git push bypasses review – changes might be merged without being checked. If your CI runs checks on MRs, using push ensures every change passes those checks.

Do cross‑team subscribed skills take up a lot of local space?

Only the skill definition files (SKILL.md and associated scripts) are synced – not the whole repository. The footprint is small. Remove a source with teamai source remove <name> when you no longer need it.

If I uninstall TeamAI, will my existing hooks be removed?

teamai uninstall only removes hooks that TeamAI injected. Manually written hooks are left untouched. If you’re unsure, run teamai hooks list first to see which hooks are managed by TeamAI before deciding to uninstall.