metagit-cli

# Metagit CLI

> Multi-repo situational awareness for humans and AI agents. Install once; use from any workspace with `.metagit.yml`.

## Install

```bash
uv tool install metagit-cli
export METAGIT_AGENT_MODE=true
```

PyPI name: `metagit-cli` (not `metagit`).

## Session start (minimal tokens)

```bash
metagit context pack --tier 0 --json
metagit prompt workspace --kind session-start --text-only
```

- Tier 0: paged workspace map · Tier 1: + repo cards · Tier 2: + since-last-session digest
- 500+ repos: `metagit prompt workspace -k large-workspace --text-only` — never dump `.metagit.yml` (see [docs/reference/context-reduction.md](docs/reference/context-reduction.md))

## Agent docs (read in this order)

- [docs/agents-quickstart.md](docs/agents-quickstart.md): **day-1 Agent OS control loop** (start here)
- [AGENTS.md](AGENTS.md): GitHub/Cursor quick reference (this repo)
- [docs/agents.md](docs/agents.md): full agent guide (also on docs site)
- [docs/skills.md](docs/skills.md): bundled skill catalog + install
- [Published docs](https://metagit-ai.github.io/metagit-cli/agents/): agents guide on GitHub Pages

## Essential commands

| Goal | Command |
|------|---------|
| Context pack | `metagit context pack --tier 0\|1\|2 --json` |
| Find repo (manifest) | `metagit search "query" --json` |
| Resolve one repo path | `metagit search "query" --path-only` |
| List all managed targets | `metagit workspace repo list --json` |
| Grep file contents | `metagit workspace grep "query" --json` |
| Grep backend status | `metagit workspace grep info --json` |
| List workspace (paged) | `metagit workspace list --json` |
| Campaign page / ADO board | `metagit campaign status --json --limit 40` · `metagit campaign board-sync --dry-run --json` |
| Prompts | `metagit prompt list` |
| Skills | `metagit skills install --scope user` |
| MCP | `metagit mcp install --scope user` |
| Latest release / notes | `metagit version check --json` |
| Self-update | `metagit version upgrade --apply --json` |
| Agent profile / apply | `metagit agent profile show` / `metagit agent apply --vendor cursor` |
| Campaigns | `metagit campaign list` · `metagit campaign new` · `metagit campaign status --limit 40` · `metagit campaign board-sync` · `metagit campaign context` |
| ACL branch / lease | `metagit branch allocate` · `metagit lease acquire --allocate` |
| Task graph / intent | `metagit task create` · `metagit task ready` · `metagit task complete` |
| Context compile | `metagit context compile --project P --repo R --json` |
| Validate components | `metagit config validate` (nested `repos[].components[]`) |
| ACL worktree / claim | `metagit worktree create` · `metagit claim declare` (`--component` optional) |
| Semantic ownership | `metagit semantic declare` · `metagit semantic owners` · `metagit semantic conflicts` |
| Merge orchestration | `metagit merge enqueue` · `metagit merge integrate` · `metagit merge status` |
| Agent scheduler | `metagit schedule next` · `metagit schedule status` · `metagit schedule policy show` |
| Agent OS (composition) | `metagit aos status` · `metagit aos doctor` · `metagit aos next` (`coord` alias) |
| Local Atlas | `metagit atlas init` · `metagit atlas generate` · `metagit atlas validate` · `metagit atlas query` |
| Organization index | `metagit org index github ORG` · `metagit org search "query"` · `metagit graph neighbors REPO` · `metagit repo materialize REPO` |
| Agent coordination skill | `metagit skills show metagit-agent-coordination` |
| Agent OS skill | `metagit skills show metagit-aos` |
| Agent coordination (ACL) | [docs/reference/agent-coordination.md](docs/reference/agent-coordination.md) |
| Task graph (RFC-0008) | [docs/reference/task-graph.md](docs/reference/task-graph.md) |
| Context compiler (RFC-0009) | [docs/reference/context-compiler.md](docs/reference/context-compiler.md) |
| Semantic ownership (RFC-0010) | [docs/reference/semantic-ownership.md](docs/reference/semantic-ownership.md) |
| Merge orchestrator (RFC-0011) | [docs/reference/merge-orchestrator.md](docs/reference/merge-orchestrator.md) |
| Agent scheduler (RFC-0012) | [docs/reference/agent-scheduler.md](docs/reference/agent-scheduler.md) |
| Agent OS (RFC-0013) | [docs/reference/aos.md](docs/reference/aos.md) |

## Feature registry

Cross-modality index (CLI / MCP / Web / docs / skills): [docs/reference/modality-feature-registry.md](docs/reference/modality-feature-registry.md)

## Bundled skills (after install)

`metagit-cli`, `metagit-agent-coordination`, `metagit-workspace-grep`, `metagit-workspace-scope`, `metagit-control-center`, `metagit-workspace-sync`, `metagit-upstream-scan`, `metagit-projects`, `metagit-campaign`, `metagit-sharing-state` (multi-agent remote state) — see docs/skills.md.

## Optional

- Local web UI: `metagit web serve`
- HTTP API: `metagit api serve`
- **Shared coordination state** (multi-agent): [docs/reference/sharing-state.md](docs/reference/sharing-state.md) — `METAGIT_STATE_URL`, ops `PUT` routes, `ETag`/`If-Match`
- **Agent Coordination Layer (ACL):** isolated `agent/*` branches, branch leases, worktrees under `.worktrees/`, advisory file claims — distinct from handoff claim TTL. See [agent-coordination.md](docs/reference/agent-coordination.md).
- **Task Graph & Intent (RFC-0008):** DAG of executable nodes under `.metagit/tasks/`, ready-set, ACL bind hints — see [task-graph.md](docs/reference/task-graph.md).
- **Context Compiler (RFC-0009):** budgeted pack artifacts via `metagit context compile` — see [context-compiler.md](docs/reference/context-compiler.md).
- **Component model (RFC-0026):** optional `repos[].components[]` with `project/repo/component` identity; `metagit config validate` — see [components.md](docs/concepts/components.md).
- **Component resolve (RFC-0027):** `metagit component list|show|resolve`, MCP `metagit_component_list|show|resolve`, GET `/v3/ops/components` and GET `/v3/ops/components/resolve` — see [components.md](docs/concepts/components.md).
- **Component graph (RFC-0028):** `metagit component graph`, MCP `metagit_component_graph`, GET `/v3/ops/components/graph`; Cypher export emits `kind=component` nodes — see [components.md](docs/concepts/components.md).
- **Component compile (RFC-0029):** `metagit context compile --component` / `--depth` — see [components.md](docs/concepts/components.md) and [context-compiler.md](docs/reference/context-compiler.md).
- **Component claims (RFC-0030):** `metagit claim declare|check --component` — see [components.md](docs/concepts/components.md).
- **Component detect (RFC-0031):** `metagit component detect|init`, MCP `metagit_component_detect|init`, GET `/v3/ops/components/detect` and POST `/v3/ops/components/init` — see [components.md](docs/concepts/components.md).
- **Derived components (RFC-0032):** `metagit project derived create --from project/repo/component` and `--include-dependencies` — see [components.md](docs/concepts/components.md).
- **Semantic Ownership (RFC-0010):** concept ownership via `metagit semantic declare|query|owners|conflicts|ingest|seed`; advisory claim `concept_hints`; GitNexus import deferred — see [semantic-ownership.md](docs/reference/semantic-ownership.md).
- **Merge Orchestrator (RFC-0011):** local queue, conflict records, opt-in validators, CLI/MCP `metagit merge` / `metagit_merge_*` tools — see [merge-orchestrator.md](docs/reference/merge-orchestrator.md).
- **Agent Scheduler (RFC-0012):** score ready task nodes and emit dispatch hints via `metagit schedule` / `metagit_schedule_*` — see [agent-scheduler.md](docs/reference/agent-scheduler.md).
- **Metagit Atlas (RFC-0014):** repository-local curated intent plus generated evidence via `metagit atlas`; MCP, federation, and adapters are deferred — see [atlas.md](docs/reference/atlas.md).
- Repomix profile: `metagit context repomix --profile bugfix-local --project P --repo R`