@jgalego/teamapi

Who owns this? Just curl your org.

Write your org as Team API as Code — one teamapi.yml per team declaring services, roles, members, interactions and cognitive load, reviewed in pull requests and versioned in git — and teamapi turns it into organigrams, org-health checks, a REST API with a live dashboard, an MCP server for LLM assistants, a chat persona per team, trend reports over your git history, and config for tools like CrewAI and Backstage.

Install#

npm install -g @jgalego/teamapi

Quick start#

teamapi init my-org                       # scaffold a whole org repo: config, CI, first teams
teamapi validate examples/acme-org
teamapi render examples/acme-org --scope topology
teamapi serve-api examples/acme-org --port 3000   # REST API + dashboard at /dashboard
teamapi serve-mcp examples/acme-org       # point Claude Desktop/Code at this command
teamapi chat examples/acme-org --team stream-checkout --ask "is payments overloaded?"

<patterns> in every command accepts a file, a glob, or a directory to auto-discover every teamapi.yml/.yaml under it — or comes from teamapi.config.yml so the everyday commands take no arguments at all.

Commands#

Author and validate

Command	Purpose
`teamapi init [dir]`	Scaffold a whole org repository: config, CI workflow, first teams
`teamapi scaffold <id> --type <type> --out <file>`	Generate one minimal, schema-valid document
`teamapi validate <patterns...>`	Resolve every `$ref` transitively; report unresolved refs and conflicts
`teamapi fmt <patterns...> [--check]`	Rewrite documents into canonical form (comment-preserving)
`teamapi migrate <patterns...>`	Bring documents up to the latest `teamApiVersion`
`teamapi schema`	Print the document JSON Schema for editors and CI

Check the org's shape

teamapi assess <patterns...> combines every check into text, JSON, HTML or SARIF, with optional baseline comparison.

Command	Purpose
`teamapi gaps <patterns...>`	Report accountability holes between teams — unowned event contracts, vacant seats, unowned agents
`teamapi policy <patterns...>`	Check declared `policies[]`, and report the ones nothing enforces
`teamapi topology <patterns...>`	Report Team Topologies design smells — overrunning collaborations, inverted platform flow
`teamapi shadow-ai <patterns...> --scan <dir>`	Report AI adoption found in repositories against what teams declare in `agents[]`

The individual checks take --format text|json|sarif. assess also supports a self-contained HTML report and --state <file> for stable new/resolved finding comparison. See the evaluation guide for a bounded adoption workflow.

See and track it

Command	Purpose
`teamapi render <patterns...> --scope topology\|hierarchy\|context-map\|org-hierarchy`	Render a Mermaid/DOT diagram
`teamapi diff <patterns...> --against <ref>`	Diff the resolved org graph against a git revision
`teamapi history <patterns...> --period week`	Trends over git history: cognitive load, agent adoption, supervision, churn
`teamapi digest <patterns...> [--webhook <url>]`	Gaps/policy/topology findings and what moved since last run, to Slack or email

Serve it

Command	Purpose
`teamapi serve-api <patterns...>`	REST API + dashboard; opt-in `--metrics`, `--mcp`, `--embeddings`, `--propose-to`, `--watch`
`teamapi serve-mcp <patterns...>`	MCP server over stdio, for Claude Desktop/Code
`teamapi chat <patterns...> --team <id> [--ask <q>]`	Chat as a team or member — Anthropic or any OpenAI-compatible endpoint

Connect it to everything else

Command	Purpose
`teamapi import github-org\|backstage\|okta\|slack\|csv <arg> --out <dir>`	Bootstrap documents from the systems an org already has
`teamapi generate crewai\|backstage\|paperclip\|codeowners\|agents-md\|port\|otel <patterns...> --out <dir>`	Generate config for another tool from the org graph
`teamapi apply <patterns...> --org <github-org> [--yes]`	Reconcile GitHub teams/memberships (plan by default)
`teamapi apply-to slack\|okta\|pagerduty <patterns...> [--yes]`	Reconcile membership in Slack usergroups, Okta groups, PagerDuty
`teamapi slack-sync <patterns...> [--yes]`	Set each declared Slack channel's topic to name the owning team
`teamapi okta-drift` / `pagerduty-drift` / `paperclip-drift`	Read-only drift reports against live systems
`teamapi doctor github\|slack\|pagerduty\|okta\|paperclip`	Check a live integration: auth, the read, field shapes, pagination

See teamapi.dev (or the main README) for the full walkthrough, rendered diagrams, REST/MCP reference, and the extended spec.

The TeamAPI toolchain#

One org graph, seven doors into it — install only the ones you need:

Package	What it does
`@jgalego/teamapi` (this package)	The CLI — validate, diagram, check, import, reconcile, serve and chat with your org
`@jgalego/teamapi-core`	The engine: `$ref` resolution, the org graph, scoring, checks, diagrams, generators
`@jgalego/teamapi-schema`	Zod schemas and TypeScript types for the extended spec
`@jgalego/teamapi-rest-api`	REST API, live dashboard, Swagger UI, Prometheus metrics
`@jgalego/teamapi-mcp-server`	The org graph as MCP tools for LLM assistants
`@jgalego/teamapi-chat`	Chat as a team or member — Anthropic or any OpenAI-compatible endpoint
`@jgalego/teamapi-backstage`	Live Backstage catalog entity provider

Docs, examples and the extended spec: teamapi.dev · github.com/JGalego/TeamAPI

License#

MIT