Metagit for AI agents

Compact guide for agents told to install and use Metagit across Git repositories. Prefer these commands over reading full repo trees.

Day-1 control loop: start with agents-quickstart.md (install → context pack → aos next → work → complete).

PyPI package: metagit-cli (not metagit).

Install

uv tool install metagit-cli
export METAGIT_AGENT_MODE=true   # non-interactive CLI (no fuzzy finder / prompts)
metagit version
metagit version check --json

Optional — install bundled playbooks into your agent host:

metagit skills list
metagit skills install --scope user --target openclaw   # or claude_code, hermes, …
metagit mcp install --scope user --target openclaw      # MCP server registration

Session start (do this first)

Run from the umbrella repo that contains .metagit.yml (workspace manifest):

metagit context pack --tier 2 --json
metagit prompt workspace --kind session-start --text-only

Escalate tiers only when needed. Use --project / --repo to narrow tier 1/2.

Discovery & readiness

Before escalating packs, check workspace readiness:

metagit workspace summary --json
metagit workspace health --json

summary returns readiness.score (0–100), dimension breakdown, and blockers. Exit 0 even when the score is low (report-only). Details: workspace-discovery.md.

Core CLI (agent mode)

Set --definition path/to/.metagit.yml when not in the manifest repo root.

Agent profile and campaigns: reference/agent-profile.md, reference/campaigns.md. Derived projects: reference/derived-projects.md. Skills surface: reference/skills-surface.md. Local repository Atlas: reference/atlas.md. Master index: reference/modality-feature-registry.md.

Prompt kinds (metagit prompt list)

metagit prompt workspace --kind context-pack --text-only
metagit prompt project --kind sync-safe --project myproj --text-only

MCP vs CLI

Key MCP tools (when gate ACTIVE): metagit_context_pack, metagit_session_begin, metagit_repo_search, metagit_workspace_search, metagit_workspace_grep_info, metagit_workspace_discover, metagit_workspace_health_check, metagit_workspace_sync, metagit_objective_list, metagit_approval_request, metagit_campaign_status, metagit_campaign_board_sync, metagit_campaign_context.

MCP resources (read-only, token-efficient): metagit://catalog → workspace/map?limit=80 → prompt/workspace/session-start?instructions=0 → session/meta. Do not read workspace/config?view=full on large umbrellas. See context-reduction.md.

metagit_version_check and metagit_version_upgrade are available even when the workspace gate is inactive. Use version check (or metagit_version_check) to compare against the latest GitHub release and PyPI. Use version upgrade (or metagit_version_upgrade with apply: true) to run the detected package-manager upgrade (uv tool upgrade metagit-cli by default). Upgrades default to dry-run; pass --apply or apply: true explicitly.

Start MCP: metagit mcp serve (stdio). Install config: metagit mcp install --scope user.

Shared coordination state (multi-agent)

Objectives, handoffs, approvals, and the events feed use the same backend as the CLI. When several agents must share one queue, configure the MCP server process (not just the IDE shell):

export METAGIT_STATE_URL=https://coordinator.example.com:8787
export METAGIT_STATE_TOKEN='…'
metagit mcp serve --root /path/to/manifest-root

Verify: resources/read → metagit://gate/status → state_backend.backend is http.

Resources: metagit://objectives, approvals/pending, handoffs/open, events/recent?since=.

Skill: metagit-sharing-state. Docs: Sharing state across a team.

Workspace content grep (not manifest search)

Search on-disk files in managed repos. Always excludes node_modules, .venv, and similar scaffold paths.

Do not use metagit search for file contents — that command searches .metagit.yml metadata only.

Install skill: metagit-workspace-grep (see Skills). Examples: metagit workspace grep --help.

Skills catalog

Install once; skills are short playbooks (when to use which command):

Full table: Skills.

Optimize a target repo (on demand)

Use the metagit-agent-access skill when a repository needs agent-friendly metadata without bloating human docs:

# Audit gaps (llms.txt, AGENTS.md, hidden README HTML comment)
skills/metagit-agent-access/scripts/optimize-agent-access.sh /path/to/repo --json

# Scaffold missing artifacts from templates
skills/metagit-agent-access/scripts/optimize-agent-access.sh /path/to/repo --apply --json

For large or unfamiliar repos, dispatch the subagent prompt in skills/metagit-agent-access/subagent-prompt.md (returns JSON summary only — no full file dumps in chat).

Hidden marker convention in README:

<!-- agent-access:start
install: ...
session_start: ...
refs: llms.txt, AGENTS.md
agent-access:end -->

Single-repo first run

Inside any Git repo without a manifest:

metagit init          # safe to re-run when .metagit.yml already exists and is valid
metagit config validate

Re-running init on a valid manifest exits 0 with “Already initialized” and does not overwrite. Use --force only when you intend to replace the file (blocked in agent mode without removing it first).

Catalog adds support --ensure (auto-enabled in agent mode): re-run succeeds with operation: noop when the project/repo already exists with matching url/path. MCP/API default ensure: true.

Human ↔ agent shared state

• Objectives — .metagit/sessions/objectives.json (local default); CLI metagit context objective …
• Approvals — mutating ops queue; metagit context approval …
• Handoffs — .metagit/sessions/handoffs.json; CLI metagit context handoff …
• Web UI (local): metagit web serve → objectives/approvals at /v3/ops/*

Objective pause/resume and notes ergonomics

Use pause when you need a low-friction checkpoint, then resume to pick the best objective quickly.

metagit context pause --title "Paused for handoff" --repo demo/svc --left-off "completed parser" --next "wire CLI" --blockers "none"
metagit context resume --format detailed
metagit context resume "demo/svc" --json

Resume selection prefers in_progress objectives, then most recently updated entries. The optional filter matches objective id/title/repos plus human/agent notes.

Objective set/edit supports ergonomic updates without rewriting full payloads:

metagit context objective set --id obj-123 --status in_progress --left-off "tests green" --next "open PR" --human-notes "handoff"
metagit context objective edit --id obj-123 --field human_notes --value "Waiting on review"

Helper script template: examples/resume-project.sh

MCP parity: metagit_context_resume exposes the same resume candidate logic.

Handoffs and leases

metagit context handoff claim --id <id> --by agent-1 --ttl 30m
metagit context handoff heartbeat --id <id> --by agent-1 --ttl 30m
metagit context events --campaign <slug> --json
metagit context events --objective <id> --since "2026-07-06T00:00:00Z" --json

Expired claims auto-release when listing handoffs. Objectives may carry mr_url and approval_id for campaign rollups (modality:objective_mr_approval_binding).

Agent Coordination Layer (ACL)

For isolated agent checkouts, branch leases, and advisory file claims, see Agent coordination (ACL) and skill metagit-agent-coordination. ACL branch leases are distinct from handoff claim TTL leases above.

metagit branch allocate --repository project/repo --agent-id agent-1 --task-id 412
metagit lease acquire --repository project/repo --agent-id agent-1 --task-id 412 --allocate
metagit worktree create --repository project/repo --agent-id agent-1 --task-id 412 --branch agent/412
metagit claim declare --repository project/repo --agent-id agent-1 --pattern 'src/*'
metagit claim declare --repository platform/core --agent-id agent-1 --component web
metagit context events --json   # includes source=acl lifecycle events

Task Graph & Intent (RFC-0008)

Expand objectives into a DAG of executable nodes, compute ready sets, and store optional ACL command hints. See Task graph.

metagit task create --title "Ship auth" --goal "…" --json
metagit task expand --graph-id … --from-outline outline.txt
metagit task ready --json
metagit task complete --node-id …
metagit task bind-acl --node-id … --agent-id agent-1 --json
metagit context events --json   # includes source=taskgraph

Context Compiler (RFC-0009)

Compile a budgeted context artifact for a project/repo (optionally bound to a task node). See Context compiler.

metagit context compile --project P --repo R --tier 1 --budget 8000 --json
metagit context compile --project P --repo R --task-id NODE --graph-id G --json

Context switch

Mid-session bootstrap into a project (optional repo): env exports, tiered pack, context-switch prompt, and an objective. See Context switch.

eval "$(metagit context switch <project> [<repo>])"
metagit context switch <project> --json
metagit prompt workspace -k context-switch --text-only

MCP: metagit_context_switch (full bootstrap). Lean alternative: metagit_project_context_switch.

Human FuzzyFinder shortcut (not for agent mode): metagit nav --all lists every managed project/repo with the repo-picker preview; --print-path prints the absolute path instead of opening an editor; --unmanaged includes extra sync-folder dirs. Agents must use workspace repo list --json and search --path-only instead.

Semantic Ownership (RFC-0010)

Declare concept-level ownership for repository paths, resolve path owners, and surface advisory claim hints without replacing Git or GitNexus. See Semantic ownership.

metagit semantic declare --concept Authentication --repository project/repo --pattern 'src/auth/**' --json
metagit semantic owners --repository project/repo --path src/auth/token.py --json
metagit semantic conflicts --repository project/repo --json
metagit semantic ingest --json

Sharing state across machines (remote backend)

When multiple agents or humans must see the same objectives, handoffs, and approvals, configure a shared ops server instead of per-machine JSON files:

export METAGIT_STATE_URL=https://coordinator.example.com:8787
export METAGIT_STATE_TOKEN='…'
# CLI / MCP commands unchanged — stores use RemoteHttpBackend automatically
metagit context objective list --json

Run metagit web serve on the coordinator host; set the same state.url in app config on every client. Repo clones remain local; only coordination documents are centralized.

See Sharing state across a team for architecture diagram, HTTP contract (ETag / If-Match), and troubleshooting.

What metagit is not

Not a Git client, SBOM tool, or full-repo packer. For whole-repo dumps use metagit context repomix with a profile, not raw repomix on the entire tree.

More

• Terminology — workspace / project / repo
• CLI reference
• Hermes multi-repo IaC
• Site: https://metagit-ai.github.io/metagit-cli/