GitMesh Community Edition

---

What is GitMesh?

GitMesh Community Edition is an open-source multi-agent orchestration runtime and governed MCP server purpose-built for open source projects. It enables AI agent teams — Triage, PR Review, Docs, Security, Community, Onboarding, and Release — to handle maintainer work autonomously, with every connected tool (Claude Code, Copilot, Cursor, Codex, Gemini CLI, and more) governed by a single maintainer-defined Policy-as-Code layer via OPA.

Built on a proven orchestration engine with atomic task checkout, persistent agent context, heartbeat scheduling, and budget enforcement, GitMesh extends this foundation with native GitHub/GitLab integration and distributes governance through MCP and ACP compatibility with every major AI coding tool. Any project can adopt it with 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. One-click adoption

Three-View Dashboard

View	Purpose
Active Agents	Agent status, budget consumption, current work. One-click pause, terminate, or reconfigure
Pending Approvals	Mobile-first approval queue — merge PRs, CVE disclosures, issue closures. Clear in 5 minutes
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 required if you use Docker for PostgreSQL instead of 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/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

---

Join the Pack

We believe the strongest solutions emerge from diverse perspectives working in concert. Whether you're fixing a bug, proposing a feature, or improving documentation, your contribution matters.

Contribution Path

1. Fork the repository
2. Create your feature branch: git checkout -b type/branch-name
3. Commit your changes with sign-off: git commit -s -m 'Add innovative feature'
4. Push to your branch: git push origin type/branch-name
5. Open a signed pull request

Read our detailed Contributing Guide for best practices and guidelines.

---

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

---

GitMesh is a governed mesh for AI agents on your repo: policies define the boundaries, the runtime keeps work coordinated and auditable, and humans stay in charge when it matters—so open-source teams ship clear, trusted software, not runaway automation.