# Govforge

> Local-first governance for AI coding agents — MCP server, CLI, audit trail, policies. Apache 2.0.

- **Type:** MCP server
- **Install:** `agentstack add mcp-ericvaillancourt-govforge`
- **Verified:** Pending review
- **Seller:** [ericvaillancourt](https://agentstack.voostack.com/s/ericvaillancourt)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [ericvaillancourt](https://github.com/ericvaillancourt)
- **Source:** https://github.com/ericvaillancourt/govforge
- **Website:** https://govforge.dev

## Install

```sh
agentstack add mcp-ericvaillancourt-govforge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

**Govern AI coding agents before they govern your codebase.**

[](https://github.com/ericvaillancourt/govforge/releases/latest)
[](https://pypi.org/project/govforge/)
[](https://www.npmjs.com/package/@govforge/cli)
[](LICENSE)
[](https://github.com/ericvaillancourt/govforge/actions/workflows/backend.yml)
[](https://github.com/ericvaillancourt/govforge/actions/workflows/cli.yml)
[](https://github.com/ericvaillancourt/govforge/actions/workflows/ui.yml)
[](backend/pyproject.toml)
[](cli/go.mod)
[](docs/mcp-integration.md)

[Website](https://govforge.dev) · [Docs](https://docs.govforge.dev) · [MCP integration](https://docs.govforge.dev/mcp-integration) · [Workflow example](https://docs.govforge.dev/workflow-example) · [Threat model](https://docs.govforge.dev/threat-model) · [API](https://api.govforge.dev/docs)

---

## What is GovForge?

GovForge is a **local-first governance layer** that sits between AI coding
agents (Claude Code, Codex, Cursor, Cline, Aider, …) and your repository.
It captures every code-shaping decision an agent makes — the rationale,
the diff, the policy results, peer-agent reviews, and the human approval —
into an append-only, queryable audit log. No SaaS, no telemetry, no
network egress: the entire stack runs on the developer's machine.

## Why

- **Agent code is invisible by default.** A few tokens turn into a
  migration script or an auth refactor. The repo only sees the diff;
  the *why* and the *risk* vanish.
- **Two-agent workflows compound the problem.** When Claude proposes
  and Codex reviews, the disagreement that mattered most is gone the
  moment the IDE tab closes.
- **Approval has to be explicit.** "I read the diff" isn't a record.
  GovForge records the human gate as a first-class entity, alongside
  policy results and structured findings.

## Quickstart

Common setup, then pick the entry point that fits how you work — typing
in a terminal (**CLI**) or chatting with your AI assistant (**Agent**).

```bash
# Install once
git clone https://github.com/ericvaillancourt/govforge
cd govforge/cli && go build -o ~/bin/gf ./cmd/gf
cd ../backend && pip install -e .

# In any repo you want governed
cd ~/your/repo
gf init                              # creates .govforge/
gf api serve --port 8787 &           # local API
(cd /ui && npm ci && npm run dev)   # http://localhost:8788
```

> Self-hosted only: bootstrap your first admin token via
> [`infra/RUNBOOK.md`](infra/RUNBOOK.md) §8. The hosted API at
> `api.govforge.dev` requires `Authorization: Bearer ` on every
> write; local `gf` against your own backend goes through the same
> code path but the bootstrap is automatic in `gf init`.

### CLI

Walk a decision through the pipeline by typing commands:

```bash
gf task create --title "Refactor auth" --risk high --actor claude
gf decision create --task TASK-001 --author claude \
  --title "Migrate to signed cookies" --risk high
gf git attach --decision DEC-001 --commit HEAD
gf policy check --decision DEC-001
gf review request --decision DEC-001 --reviewer codex
gf review submit DEC-001 --reviewer codex --status approved   # or via cockpit / MCP
gf approve DEC-001 --comment "OK after rotation patch"
gf decision timeline DEC-001
```

The full Claude → Codex → human-approval walkthrough lives in
[`docs/workflow-example.md`](docs/workflow-example.md).

### Agent

Don't want to learn the CLI? Drive the same flow by chatting with the
agents you already use. Mint a scoped token per agent:

```bash
gf token create --label claude-author  --agent claude \
  --scopes tasks:write,decisions:write,reviews:write,decisions:read,reviews:read
gf token create --label codex-reviewer --agent codex \
  --scopes reviews:write,reviews:read,decisions:read
```

Paste each `gfp_…` into the matching agent's MCP config — exact
snippets per client (Claude Code, Codex, Cursor, Cline) in
[`docs/mcp-integration.md`](docs/mcp-integration.md). Then chat:

> **You** (in Claude Code): *"Refactor session auth to signed cookies.
> Flag it as high-risk in GovForge before you start."*
>
> **Claude**: *opens `TASK-001`, edits the code, records `DEC-001`,
> attaches the diff, runs the policy checks, and requests a review
> from Codex — all in the background.*
>
> **You** (switching to Codex): *"Review `DEC-001` in GovForge. Focus
> on session security."*
>
> **Codex**: *reads the diff and submits a structured review with
> findings.*

When the decision is ready, approve it at
. The agent tokens never
carry `approvals:write` — by design, the final signature stays a
human action.

Full vibe-coder walkthrough:
[`docs/workflow-example-agents.md`](docs/workflow-example-agents.md).

## Install

Pick whichever fits your stack — every channel ships the same `v0.1.0` `gf` binary, all signed with cosign.

| Platform                        | Method                                                                       | Status   |
|---------------------------------|------------------------------------------------------------------------------|----------|
| Pre-built binary (curl one-liner) | `curl -fsSL https://govforge.dev/install.sh \| sh`                          | ✅ today |
| Homebrew tap (macOS / Linux)    | `brew install ericvaillancourt/tap/govforge`                                 | ✅ today |
| `pipx` / `pip` (backend wheel)  | `pipx install govforge` *(or `pip install govforge` for the FastMCP server + HTTP API)* | ✅ today |
| `npx` wrapper (no Go/Python)    | `npx -y @govforge/cli@latest --version` *(postinstall downloads the signed `gf` binary)* | ✅ today |
| Docker (backend container)      | `docker pull ghcr.io/ericvaillancourt/govforge-backend:v0.1.0`               | ✅ today |
| Source (any OS)                 | `git clone` + `go build` + `pip install -e .`                                | ✅ today |

## How it works

```
agents (Claude / Codex / Cursor / Cline / Aider)
    │   stdio
    ▼
FastMCP server  ──┐
                  │
gf CLI ──HTTP─▶  FastAPI (127.0.0.1:8787)  ──▶  Services  ──▶  Models / SQLite
                  │                                │  │
UI cockpit ───────┘                                │  └──▶  Event store (audit log)
                                                   │
                                                   ├─▶  Git extractor (read-only)
                                                   └─▶  Policy engine (5 defaults)
```

Three components on the developer's machine: the Python backend (services
+ MCP + HTTP API), the Go CLI `gf`, and the Next.js cockpit at
`localhost:8788`. Full architecture in
[`docs/architecture.md`](docs/architecture.md), data model in
[`docs/data-model.md`](docs/data-model.md).

## MCP integration

Drop GovForge into Claude Code by adding a server entry to
`~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "govforge": {
      "command": "python",
      "args": ["-m", "govforge.mcp.server"],
      "env": {
        "GOVFORGE_DB": "/absolute/path/to/.govforge/govforge.db"
      }
    }
  }
}
```

Codex / Cursor / Cline configs in
[`docs/mcp-integration.md`](docs/mcp-integration.md).

The agent gets **11 tools**, **5 resources**, and **3 prompts** —
schemas in
[`backend/src/govforge/mcp/schemas.py`](backend/src/govforge/mcp/schemas.py).

## Built-in policies

Five defaults ship with `gf init`. Override via `.govforge/policies.toml`.

| Policy                              | Trigger                                                          |
|-------------------------------------|------------------------------------------------------------------|
| `auth_change_requires_review`       | a file path matches `auth`, `session`, `jwt`, `permission`, `middleware` → BLOCKED |
| `secret_pattern_detection`          | diff content matches `AWS_SECRET_ACCESS_KEY`, `PRIVATE_KEY`, etc. → BLOCKED; `.env`-style filenames → WARNING |
| `test_required_for_high_risk`       | risk ≥ HIGH but no test file in the diff → WARNING               |
| `migration_requires_review`         | path matches `migrations/` or `alembic/versions/` → BLOCKED      |
| `large_diff_requires_human_approval`| insertions + deletions exceed threshold (default 500) → BLOCKED  |

Adding a policy is one Python class — see
[`backend/src/govforge/core/policies/defaults.py`](backend/src/govforge/core/policies/defaults.py).

## Repository layout (monorepo)

| Folder | Role | Status |
|---|---|---|
| [`backend/`](./backend/) | Python: FastMCP + FastAPI + SQLAlchemy services | ✅ feature-complete (97 tests, 90 % coverage) |
| [`cli/`](./cli/) | Go: `gf` binary | ✅ feature-complete (75–100 % per package) |
| [`ui/`](./ui/) | Next.js: local cockpit (`gf ui serve`) | ✅ feature-complete |
| [`brand/`](./brand/) | Brand assets (SVG wordmark + marks) | ✅ |
| [`docs/`](./docs/) | Architecture, data model, MCP integration, threat model, workflow | ✅ |
| [`infra/`](./infra/) | Caddy + Podman quadlet + sudoers | ✅ deployed |
| [`.github/workflows/`](./.github/workflows/) | CI: backend / cli / ui / release | ✅ |

> The **marketing site** at  lives in a separate
> private repo so brand and copy can iterate without OSS ceremony. The
> product (this repo) stays Apache 2.0.

## Documentation

- [Architecture](https://docs.govforge.dev/architecture) — components + sequence diagram + audit-log invariant
- [Data model](https://docs.govforge.dev/data-model) — 14 entities (incl. User + ApiToken) + ER diagram + state machine
- [MCP integration](https://docs.govforge.dev/mcp-integration) — Claude Code / Codex / Cursor / Cline wiring
- [Threat model](https://docs.govforge.dev/threat-model) — security guarantees pinned by tests
- [Workflow example](https://docs.govforge.dev/workflow-example) — full Claude → Codex → human-approval walkthrough
- [API auth runbook](infra/RUNBOOK.md#85-stage-b-live-since-2026-05-10-05-11) — operator-side recipe for the Stage B env vars + signed-in UX (GitHub + Google OAuth)
- [Brand guide](https://docs.govforge.dev/brand) — assets, palette, tagline, tone of voice
- [CHANGELOG](CHANGELOG.md)

## Contributing

Contributions welcome — see
[`CONTRIBUTING.md`](CONTRIBUTING.md). For security issues, follow the
private disclosure process in [`SECURITY.md`](SECURITY.md). All
participants are bound by the
[Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).

## License

[Apache License 2.0](LICENSE) — see [`LICENSE`](LICENSE) and
[`NOTICE`](NOTICE).

Copyright 2026 Eric Vaillancourt and GovForge contributors.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ericvaillancourt](https://github.com/ericvaillancourt)
- **Source:** [ericvaillancourt/govforge](https://github.com/ericvaillancourt/govforge)
- **License:** Apache-2.0
- **Homepage:** https://govforge.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ericvaillancourt-govforge
- Seller: https://agentstack.voostack.com/s/ericvaillancourt
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.