GitMesh

---

What is GitMesh?

GitMesh is an open-source multi-agent orchestration runtime and governed MCP server for open source projects. It runs AI agent teams (Triage, PR Review, Docs, Security, Community, Onboarding, and Release) against your repository, with every connected tool (Claude Code, Copilot, Cursor, Codex, Gemini CLI, and others) governed by a single maintainer-defined Policy-as-Code layer via OPA.

The orchestration engine provides atomic task checkout, persistent agent context, heartbeat scheduling, and budget enforcement. Governance is distributed over MCP and ACP, so any compatible tool is covered. Adoption requires one YAML file and one CI step.

Core Capabilities

• Multi-Agent Orchestration: Pre-defined OSS agent roles (Triage, PR Review, Docs, Security, Community, Onboarding, Release) with configurable heartbeat schedules, token budgets, and permission scopes
• Policy-as-Code via OPA: Maintainers define governance rules in simple YAML that auto-compiles to Rego. No agent merges a PR, modifies CI/CD files, or publishes a security advisory without human approval
• GitHub/GitLab Native Sync: Bidirectional issue and PR synchronization via webhooks. Agent actions (label, comment, review) push directly to the forge
• MCP Server: Any MCP-compatible IDE (VS Code, Cursor, JetBrains) connects once and every AI tool is automatically governed by the project's policy
• ACP Orchestrator: JSON-RPC 2.0 agent-to-agent coordination. Multiple agents work simultaneously without conflicts, double work, or runaway costs
• Immutable Audit Log: Every action logged with actor, policy version, and outcome (allowed/blocked). Filterable and exportable as JSON/CSV
• Project Templates: Pre-configured agent teams for CLI tools, JS libraries, DevOps projects, CNCF sandboxes, and solo maintainers

Three-View Dashboard

View	Purpose
Active Agents	Agent status, budget consumption, current work. Pause, terminate, or reconfigure
Pending Approvals	Mobile-first approval queue for merges, CVE disclosures, and issue closures
Audit Log	Chronological action history with policy outcome filtering

---

Installation

Prerequisites

• Node.js 20+
• pnpm 9+ (the setup script can install it via Corepack if missing)
• Docker: optional, only needed if you run PostgreSQL in Docker instead of using the embedded database

One-command setup (macOS / Linux / Windows)

From the repo root:

Platform	Command
macOS / Linux	./setup.sh
Windows (PowerShell)	./setup.ps1
Windows (cmd)	setup.cmd

These wrappers run scripts/setup.mjs, which checks Node, ensures pnpm, copies .env.example → .env when missing, installs dependencies, and builds the workspace.

Useful flags (all platforms):

node scripts/setup.mjs --start          # install + build + pnpm dev
node scripts/setup.mjs --with-docker-db # also start Docker Compose Postgres on localhost:5433

Manual setup

git clone https://github.com/LF-Decentralized-Trust-labs/gitmesh.git
cd gitmesh
pnpm install --no-frozen-lockfile   # first clone; CI uses frozen lockfile
pnpm dev                            # API + UI, see below

Database (embedded vs external)

GitMesh uses PostgreSQL (via Drizzle). For local development you have two common paths:

1. Embedded PostgreSQL (default, no extra install)

• Do not set DATABASE_URL (leave it unset, or keep it commented out in .env).
• The dev server starts an embedded PostgreSQL instance and stores data under
  ~/.gitmesh-agents/instances/default/db/ (overridable with GITMESH_HOME / GITMESH_INSTANCE_ID).
• This works for most developers on a normal machine with disk space and a writable home directory.
• It is not universal: unusual environments (strict permissions, missing native binaries for your OS/arch, incomplete installs) may fail. In those cases use path 2.

2. External PostgreSQL (DATABASE_URL)

• Set DATABASE_URL to a real server (local Docker, cloud, etc.).
• Apply migrations when needed:
  DATABASE_URL='postgres://...' pnpm db:migrate
  (same connection string the app uses).
• If you copy .env.example to .env and uncomment a URL such as
  postgres://gitmesh:gitmesh@localhost:5433/gitmesh, you must run Postgres on that host and port first (for example pnpm db:up, or node scripts/setup.mjs --with-docker-db). Otherwise the app will fail to connect (for example ECONNREFUSED on port 5433).

Authoritative detail: doc/SETUP.md, doc/DEVELOPING.md, doc/DATABASE.md.

Start the platform

pnpm dev

In development, the API and the maintainer UI share one origin:

• http://localhost:3100: REST API (/api/...) and UI

For a single run without file watching:

pnpm dev:once

Optional: pnpm gitmesh-agents run: onboarding, doctor --repair, and start when checks pass.

Docker images

• Dockerfile: production-style image; persistent state under GITMESH_HOME (volume /gitmesh-agents), embedded PostgreSQL by default in typical deployments. See doc/DOCKER.md.
• Dockerfile.e2e: installs/runs gitmesh-agents from npm for E2E-style bootstrap inside a container.

Configuration

See .env.example for a full template. Highlights:

Variable	Description
DATABASE_URL	When set, uses that PostgreSQL server; when unset, embedded PostgreSQL is used (see Database (embedded vs external) above).
PORT	HTTP port (often 3100).

Deployment mode, auth, and GitHub integration are documented in .env.example and doc/DEVELOPING.md.

---

Adoption Path

Stage	What Happens	Time
1. Zero-config entry	Add gitmesh/agent-gate to CI; contributions are policy-checked immediately	5 min
2. First agent	Add .gitmesh/agents.yaml, enable Triage Agent, approve onboarding	15 min
3. Connect tools	Each developer adds GitMesh MCP server URL to their IDE config once	2 min/dev
4. Expand the team	Enable PR Review, Docs, Security agents as the project grows	On demand
5. Publish a template	Share your agent configuration for other projects to adopt	Optional

---

Contributing

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.

---

Maintainers

parvm1102

Ronit-Raj9

License

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

---

A Lab under the Linux Foundation Decentralized Trust