# GitMesh
[](LICENSE)
[](https://github.com/LF-Decentralized-Trust-labs/gitmesh/graphs/contributors)
[](https://www.bestpractices.dev/projects/10972)
[](https://zoom-lfx.platform.linuxfoundation.org/meeting/96608771523?password=211b9c60-b73a-4545-8913-75ef933f9365)
---
## 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):
```bash
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
```bash
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/SETUP.md), [doc/DEVELOPING.md](doc/DEVELOPING.md), [doc/DATABASE.md](doc/DATABASE.md).
### Start the platform
```bash
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:
```bash
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)](#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
[](https://insights.linuxfoundation.org/project/lf-decentralized-trust-labs/repository/lf-decentralized-trust-labs-gitmesh)
[](https://github.com/LF-Decentralized-Trust-labs/gitmesh/actions/workflows/gov-sync.yml)
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](CONTRIBUTING.md) for the full workflow.
---
## Maintainers
[](https://zoom-lfx.platform.linuxfoundation.org/meeting/96608771523?password=211b9c60-b73a-4545-8913-75ef933f9365)
**A Lab under the [Linux Foundation Decentralized Trust](https://www.lfdecentralizedtrust.org/)**
