Metagit context packs

Use this skill for the most token-efficient way to onboard into a metagit workspace. Prefer metagit context pack --tier N --json over reading raw trees or full manifests.

Umbrella .metagit.yml stays on disk. Do not inject it: no config show --json without --confirm-full, no workspace list --include-workspace, no metagit://workspace/config?view=full without confirm=1. Maps default to 80 repos; check truncated. 500+ repos: metagit prompt workspace -k large-workspace --text-only and context-reduction.md.

Set non-interactive defaults:

export METAGIT_AGENT_MODE=true

Run from the umbrella repo that contains .metagit.yml (or pass -c path/to/.metagit.yml).

When to use

• Session start in any metagit-managed workspace
• Before editing — need project/repo boundaries and health without cloning everything
• Returning after idle — tier 2 digest shows what changed since last session
• Scoping a bugfix — tier 1 cards + repomix profile instead of whole-repo dumps
• Coordinating humans and agents — objectives and approval queue state

Do not skip context packs and grep the filesystem when a manifest exists.

Tier workflow

Escalate tiers only when needed. Narrow tier 1/2 with --project and/or --repo.

Primary session command

metagit context pack --tier 0 --json --project P -c .metagit.yml   # large umbrellas
metagit context pack --tier 2 --json --project P --repo R -c .metagit.yml

Pair with operational prompts (paste --text-only output into agent context):

metagit prompt workspace -k session-start --text-only -c .metagit.yml
metagit prompt workspace -k context-pack --text-only -c .metagit.yml   # tier escalation guide

Escalation rules

1. Start tier 0 when you only need catalog boundaries (search-before-create, layout planning).
2. Move to tier 1 when git health, stack hints, or per-repo instructions matter.
3. Use tier 2 at session open/return — digest includes first_session, manifest_changed, per-repo commit counts, active objective id.
4. Tier 2 touches the session boundary — avoid running it from multiple agents simultaneously on a shared manifest (see multi-instance below).

Scoped packs

metagit context pack --tier 1 --json --project portfolio --repo api-gateway
metagit context pack --tier 2 --json --project portfolio

Mid-session context switch

Prefer one command instead of manually chaining pack + session-start + objective:

eval "$(metagit context switch portfolio api-gateway)"
metagit context switch portfolio --json
metagit prompt workspace -k context-switch --text-only

MCP: metagit_context_switch. Lean switch without pack/objective: metagit_project_context_switch. See Context switch.

Single repo card

When you already know the target repo:

metagit context repo-card --project P --repo R --json -c .metagit.yml

Card fields include: status, health_flags (missing_clone, dirty, behind_remote, stale_head_30d), stack_hints, resolved agent_instructions excerpts.

Repomix profiles (scoped snapshots)

Bundled profiles: bugfix-local, config-edit, cross-repo-impact.

metagit context repomix --profile bugfix-local --project P --repo R -c .metagit.yml
metagit context repomix --profile config-edit --project P --repo R --output /tmp/pack.txt

Use profiles instead of raw repomix on an entire tree. Pick profile by task:

Objectives (shared human ↔ agent state)

Persisted under .metagit/sessions/objectives.json.

metagit context objective list --json -c .metagit.yml
metagit context objective get --id obj-123 --json

echo '{"id":"obj-123","status":"in_progress","title":"Fix API timeout","repos":["portfolio/api"]}' \
  | metagit context objective set -c .metagit.yml

metagit context objective complete --id obj-123 -c .metagit.yml
metagit context objective cancel --id obj-123 -c .metagit.yml

Tier-2 digest surfaces active_objective_id when one objective is in progress.

Approvals (human-in-the-loop)

Queue under .metagit/approvals/pending.json.

metagit context approval request --action repo_sync --requested-by hermes --payload '{"project":"P","repo":"R"}' -c .metagit.yml
metagit context approval list --json -c .metagit.yml
metagit context approval list --status all --json

metagit context approval approve --id apr-001 --note "ok for staging" -c .metagit.yml
metagit context approval deny --id apr-002 --note "needs review" -c .metagit.yml

Agents: list pending approvals before mutating ops; never self-approve without operator policy.

Hermes session bootstrap

Wire metagit into Hermes (or any orchestrator) so every objective begins with bounded context.

When to call

Commands

export METAGIT_AGENT_MODE=true
PACK_JSON="$(metagit context pack --tier 0 --json -c .metagit.yml)"
PROMPT_TEXT="$(metagit prompt workspace -k session-start --text-only -c .metagit.yml)"

How to inject output

Token-tight bootstrap:

metagit context pack --tier 0 --json
metagit prompt workspace -k session-start --text-only

Default bootstrap (scope --project/--repo when known; unscoped tier 2 on 500+ repos is too large):

metagit context pack --tier 0 --json
metagit prompt workspace -k context-pack --text-only
metagit prompt workspace -k session-start --text-only

Flags: --max-cards, --max-map-repos, --max-tokens (drops cards → digest → map rows).

Parse pack JSON top-level keys: workspace_name, tier, map, cards, digest.

Multi-agent coordination (remote state vs Syncthing)

Preferred: separate machines share coordination JSON through a coordinator running metagit web serve and clients with METAGIT_STATE_URL / state.url. See skill metagit-sharing-state and docs/reference/sharing-state.md.

Verify MCP host config: resources/read → metagit://gate/status → state_backend.backend should be http.

Alternative: Syncthing (or similar) on the same manifest root — use only when remote state is unavailable.

Syncthing conflict zones

When multiple agents share a workspace root via Syncthing:

Conflict zones

Agent rules

1. Read after sync settles — wait for Syncthing idle, then metagit config validate and tier 0/1 pack.
2. One manifest writer — designate the Hermes controller for catalog mutations (metagit workspace …, metagit config patch --save).
3. Tier 2 once per session window — only the session-owning agent runs --tier 2; others use tier 0/1.
4. Git state is local — Syncthing syncs manifest/state files, not clone contents; run metagit project sync per machine.
5. Optional coordination file — teams may touch .metagit/.manifest-lock (pid + timestamp) as a human-visible lock; metagit does not enforce it.

Stale sync detection

metagit context pack --tier 2 --json    # check digest.manifest_changed
metagit config validate -c .metagit.yml

MCP equivalents (when MCP gate is ACTIVE)

Remote state: set METAGIT_STATE_* on the MCP server process; tools unchanged. Skill: metagit-sharing-state.

Use CLI when operating shell-only (METAGIT_AGENT_MODE=true); use MCP resources/tools when the IDE host exposes metagit (see metagit-mcp-resources for the read ladder).

MCP resource ladder (read-only)

Use tool metagit_session_begin once when a full bootstrap envelope must update the session boundary.

Output contract

After packing, report to the user or parent agent:

• workspace name and tier used
• project/repo count from map
• repos with health flags (from cards if tier ≥ 1)
• digest highlights if tier 2 (first_session, manifest_changed, active objective)
• recommended next step (search, sync, repomix profile, or prompt kind)

Related skills

• metagit-sharing-state — multi-agent remote coordination (METAGIT_STATE_URL)
• metagit-cli — full CLI prompt and catalog reference
• metagit-workspace-scope — gate and scope discovery
• metagit-control-center — ongoing multi-repo coordination
• metagit-workspace-sync — guarded fetch/pull after pack shows stale repos