Metagit

What This Is

Metagit gives you situational awareness across Git repositories. It helps multi-repo projects feel manageable, discoverable, and cohesive. It captures cross-repository relationships and project knowledge in easy to understand version controlled manifests.

Day-1 Agent OS loop: docs/agents-quickstart.md — install → context pack → aos next → compile/ACL → complete.

After Every Task

After meaningful work, run GROW:

• Prepare: Run task qa:prepush and resolve any errors. Rerun until all failures are resolved.
• Ground: what changed in reality?
• Record: update .mex/ROUTER.md and relevant .mex/context/ files
• Orient: create or update a .mex/patterns/ runbook if this can recur
• Write: bump last_updated on changed scaffold files and run mex log when rationale matters

Navigation

At the start of every session, read .mex/ROUTER.md before doing anything else. For full project context, patterns, and task guidance — everything is there.

Metagit — agent quick reference

For agents instructed to use Metagit (not necessarily to contribute to this repository).

Install: uv tool install metagit-cli · set METAGIT_AGENT_MODE=true · PyPI name metagit-cli.

Quickstart: docs/agents-quickstart.md · example examples/agent-aos-loop/

Session start (from repo with .metagit.yml):

metagit -c .metagit.yml context pack --tier 0 --json
metagit -c .metagit.yml prompt workspace --kind session-start --text-only

Large umbrellas (500+ repos): keep .metagit.yml on disk. Use search + paged packs + prompt workspace -k large-workspace. Do not run config show --json or workspace list --include-workspace. See docs/reference/context-reduction.md.

Skills: metagit skills install --scope user · MCP: metagit mcp install --scope user

Full guide: docs/agents.md · Index: llms.txt · Skills: docs/skills.md · Docs: https://metagit-ai.github.io/metagit-cli/agents/

GitNexus — Code Intelligence

This project is indexed by GitNexus as metagit-cli (17846 symbols, 38515 relationships, 1008 execution flows).

Index stale? Run node .gitnexus/run.cjs analyze --index-only from the project root — it auto-selects an available runner. No .gitnexus/run.cjs yet? Bootstrap with npx, bunx, or pnpm dlx — e.g. bunx gitnexus@latest analyze (npm 11 npx crash; #1939).

Always Do

• MUST run impact before editing. Use impact({target: "symbolName", direction: "upstream"}) or node .gitnexus/run.cjs impact "symbolName" --direction upstream --repo .; report callers, processes, and risk. Never substitute grep for graph analysis.
• MUST analyze graph changes before committing. Use detect_changes({scope: "all"}) (MCP) or node .gitnexus/run.cjs detect-changes --scope all --repo . (CLI fallback). partial: true or truncated: true is not a clean check — a zero means unseen, not unaffected; re-run it. For regression review: detect_changes({scope: "compare", base_ref: "main"}) or node .gitnexus/run.cjs detect-changes --scope compare --base-ref "main" --repo ..
• MUST warn on HIGH/CRITICAL risk pre-edit; never use riskSharedAxes to waive a HIGH/CRITICAL risk warning. Compare File/symbol: MCP File omits axes; Graph-RAG expands File.
• MUST treat risk: UNKNOWN as unresolved, not as low. An empty caller set is not evidence the symbol is unused — it can also mean the callers are not resolvable by the index (plain-object property access, dynamic dispatch, cross-language calls). impact pairs UNKNOWN with a riskNote saying so. Confirm with a text search before treating the symbol as safe to change or delete; do not proceed on the strength of a zero.
• MUST use query({search_query: "concept"}) for concepts/flows, context({name: "symbolName"}) for a named symbol, or impact for blast radius, on read-only callers, dependencies, imports, or execution flow. Graph first; text search only for empty/UNKNOWN/literals.
• For security review, explain({target: "fileOrSymbol"}) lists taint findings (source→sink flows; needs analyze --pdg).

Never Do

• NEVER edit a function, class, or method before MCP/CLI impact analysis.
• NEVER ignore HIGH or CRITICAL risk warnings from impact analysis, and never read UNKNOWN as an all-clear — it means the walk could not answer, which is the one verdict that requires confirming by other means.
• NEVER rename symbols with find-and-replace — use rename which understands the call graph.
• NEVER commit before MCP/CLI graph change analysis.

Resources

CLI