GitMesh Logo

GitMesh

Audit and govern every coding agent from your repo.

What is GitMesh?

Every coding agent reads its own configuration from your repository, and no two agree on where it lives or what it may do. Instructions get copied between AGENTS.md, CLAUDE.md and GEMINI.md and drift apart. MCP servers are hand-copied into a different file for each agent. Nobody has audited what those agents are permitted to do.

GitMesh is the agent workspace compiler. One git-versioned source of truth for instructions, tools and guardrails - AGENTS.md plus .gitmesh/ - audited, compiled to each agent's native config, drift-checked in CI, and enforced through each agent's own mechanisms, which differ from agent to agent (the coverage matrix will show what each one can enforce). Only the audit ships today: gitmesh doctor reads Claude Code, Codex, Cursor, Copilot, Antigravity, OpenCode, Devin, Cline and Roo configuration in one pass. The status table lists what comes next.

It is a single CLI (and, later, a GitHub Action). No server, no login, no database, no daemon, and no new instruction format: instructions stay in AGENTS.md. The entry command writes nothing.

Quickstart

Node.js 20 or newer, from any directory inside a git repository:

npx gitmesh-cli@next doctor

The npm package is gitmesh-cli and the installed binary is gitmesh; the unscoped npm name gitmesh belongs to an unrelated project (ADR-005).

gitmesh doctor reads the agent configuration in the repository's working tree across eleven registered adapters in one pass - instruction files, rules, MCP configs, skills, commands, subagents, permission and hook settings - diffs the instruction copies different agents read, and reports risk findings with stable ids. It never writes a file, never opens a network connection and never runs a subprocess; the test suite holds every release to that. Pass a directory to audit another checkout: npx gitmesh-cli@next doctor ../other-repo scans that directory's git root. A symlink that resolves outside the repository is reported as broken and never read or followed, so an unreviewed checkout cannot make doctor quote files of the machine running it.

| Flag | Effect | |---|---| | --fail-on | severity that makes the run exit 1: error, warning (default), info, or none to never fail | | --json | versioned machine-readable report | | --md | Markdown report for a PR comment or job summary | | --user | also inventory two user-scope files: ~/.claude/CLAUDE.md and Codex's config.toml (in ~/.codex, or $CODEX_HOME when set), and run the machine-level presence probes (org-managed Claude settings, Codex's requirements.toml, the Antigravity CLI settings file) |

Exit codes are the CI contract: 0 no finding at or above --fail-on, 1 at least one, 2 the run itself failed. No finding can be suppressed in this release, so a gate on the default warning stays red until every warning is fixed; --fail-on error gates on errors only. Full walkthrough: docs/doctor/quickstart.md.

What doctor reports

| Id | Severity | Finding | |---|---|---| | GM001 | error | Plaintext secret or token in an MCP config, settings, hooks or config file | | GM002 | warning | No deny/ask protection for .env files in an agent that can express one | | GM003 | error | Bypass-permissions, auto-approve or danger-full-access mode in shared config | | GM004 | warning | Skill with executable content and no recognized pin | | GM005 | warning | Same MCP server defined with different urls or credentials across tools | | GM006 | warning | Generated-looking file hand-edited: broken gitmesh:managed markers | | GM007 | warning | Instruction file exceeds the 40,000-character threshold | | GM008 | info | Orphan config for an agent unseen in repository history | | GM009 | warning | Inconsistent local-vs-shared hygiene: .gitignore vs committed status | | GM010 | warning | CLAUDE.md without an AGENTS.md bridge | | GM011 | warning | Semantic contradictions inside one tool's own config |

GM008 and GM009 are implemented but silent in this release: doctor does not yet read the repository history or the tracked and ignored file status they need.

A GM001 finding names the file, the line and, when there is one, the key of a secret, never any part of its value. Other parts of the report quote configuration text, and a secret with no credential signal around it, such as a password in prose, is printed as written: read what the report can quote before posting output publicly. Which files doctor reads for each agent is listed in the coverage matrix.

Status

GitMesh ships in layers. Each one is useful alone, and only what is marked available exists today.

| Command | What it does | Status | |---|---|---| | gitmesh doctor | audit, cross-tool drift, risk findings - read-only | available (gitmesh-cli@next) | | gitmesh init / migrate | import existing configs (incl. Ruler, rulesync, .agents/agents.json) into one source | planned | | gitmesh apply | compile that source into each agent's native files, rewriting only content inside gitmesh:managed markers | planned | | gitmesh check | fail CI when generated files drift from source | planned | | gitmesh policy | compile one policy into each agent's own permission model, with a generated coverage report | planned | | gitmesh receipt | signed, offline-verifiable record of workspace state | later |

The plan behind these layers, with its evidence and its kill criteria, is doc/pivot/pivot.md.

What GitMesh does not do

It does not enforce anything itself. Doctor reports; each agent's own permission model enforces. GitMesh never claims uniform enforcement across agents, and never calls an instruction a guardrail.
It does not phone home. No telemetry, usage pings, crash reports or update checks, and no opt-in that turns any of them on (ADR-006). Every pull request and every release runs each top-level command of the packaged CLI under a spy that fails CI on the first network call, DNS query or subprocess.
It does not scan content for prompt injection, tool poisoning or malicious skills. That lane belongs to Snyk Agent Scan and Cisco's scanner; GitMesh checks structure and hygiene.
It does not fight the manager you already use. Ruler, rulesync, .agents/agents.json, symlink managers, skills-lock.json and mcp-lock records are detected and labeled managed by X; being managed is never itself a finding. Their files are still checked, so a token in .ruler/mcp.json is still GM001.
It is not the only auditor. Claude Code's /doctor, cc-health-check, agents-lint and AgentLint each audit one tool or one file class well; GitMesh audits the whole multi-vendor workspace.

Documentation

Quickstart - run doctor and read its report
Findings GM001-GM011 - what each rule checks and how to clear it
Coverage matrix - what doctor inventories per agent today
Scanners - where doctor stops and content-security scanners begin

Legacy: the GitMesh Agents runtime

The multi-agent orchestration runtime, governed MCP server, PostgreSQL control plane and dashboard that GitMesh shipped before the pivot are still in this repository, in maintenance mode. They are not part of the gitmesh-cli package and are not published to npm: run them from a checkout of this repository (pnpm install, then pnpm gitmesh legacy ). Setup is in doc/SETUP.md and doc/DEVELOPING.md, with doc/DATABASE.md and doc/DOCKER.md for the database and container options; the rest of their documentation moved to docs/legacy/. Nothing in the new CLI path needs a server or a database.