# 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 2 --json
metagit prompt workspace --kind session-start --text-only
```

- Tier 0: workspace map · Tier 1: + repo cards · Tier 2: + since-last-session digest

## Agent docs (read in this order)

- [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` |
| Grep file contents | `metagit workspace grep "query" --json` |
| Grep backend status | `metagit workspace grep info --json` |
| List workspace | `metagit workspace list --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 expand` |
| 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` |
| ACL worktree / claim | `metagit worktree create` · `metagit claim declare` |
| 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` |
| 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).
- **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`
