---

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>	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 <command>). 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.

Contributing

Adapters are the on-ramp: one directory per agent under lib/workspace-adapters/, one interface, and golden fixtures for every detector.

1. Fork the repository
2. Create a branch: git checkout -b type/branch-name
3. Commit with sign-off (DCO is enforced): git commit -s -m "feat: add ..."
4. Push the branch: git push origin type/branch-name
5. Open a pull request

See the Contributing Guide for the full workflow and AGENTS.md for how coding agents should work in this repository.

---

Maintainers

parvm1102

Ronit-Raj9

License

Licensed under the Apache License 2.0. See the LICENSE file in this repository for the full text.

---