Skip to main content
Glama

pgcow

ci npm JSR JSR Score Rust license

One line: npx pgcow branch feat-a --allow-write (or bunx pgcow branch feat-a --allow-write): instant local data-directory branches via OS copy-on-write, aligned with git checkout.

What it is (and is not)

pgcow branches an on-disk app data directory (SQLite files, seeds, local vector indexes) under .pgcow/work/. It does not manage a live PostgreSQL PGDATA cluster (no PG_VERSION lifecycle, no running server handoff). Point --data-dir at whatever folder your tool reads; pgcow keeps per-git-branch copies cheap.

Related MCP server: conversation-branch

Why

  • database-lab-engine (dblab): ZFS/LVM thin clones on dedicated Linux hosts, not npx or bunx on a laptop.

  • Neon / Snaplet: Cloud or slow dump workflows, not offline folders on disk.

pgcow clones trees with clonefile / reflink / hardlink fallbacks, then junctions or symlinks the active --data-dir to the selected branch work tree (no full-directory copy on checkout when linking works).

Windows

Checkout uses directory junctions (mklink /J semantics via Node symlink type junction). Junctions require the work tree and --data-dir to live on the same volume; cross-volume paths fall back to copying on first init only.

Install

Bun / npm:

bunx pgcow init --data-dir ./pgdata
npx pgcow init --data-dir ./pgdata

# or install in your project / globally
bun add -d pgcow
npm i -D pgcow

JSR:

bunx jsr add @kanchingyg/pgcow
npx jsr add @kanchingyg/pgcow

Cargo (Rust native binary):

cargo install --git https://github.com/kanchingyg/pgcow

The core engine is Rust (src/lib.rs, src/main.rs, src/mcp.rs). TypeScript under src/*.ts is included for npx / bunx / JSR usage and MCP bridge helpers.

Quick start

pgcow init --data-dir ./pgdata
pgcow branch feat-a --allow-write
pgcow checkout main
pgcow reset --allow-write
pgcow sync-git --allow-write   # maps git branch names; slashes become filesystem slugs

MCP + local models

npx pgcow --mcp --allow-write
bunx pgcow --mcp --allow-write

Register in Cursor, Claude Code, or Ollama-driven agents so each session can create_db_branch without duplicating gigabytes on disk.

Flags

Flag

Purpose

--allow-write

Enable branch create/reset (default read-only)

--dry-run

Probe CoW / show restore plan

--data-dir

Active data directory (default ./pgdata; not Postgres PGDATA)

--mcp

JSON-RPC MCP server on stdio

MCP Tools Reference

Tool

Mutates

Description

create_db_branch

true

Clone the active data directory into .pgcow/work/<branch> using OS copy-on-write (clonefile, reflink, or hardlink fallback; requires --allow-write).

checkout_db_branch

true

Point the active --data-dir symlink or Windows directory junction at the target branch worktree (requires --allow-write).

list_db_branches

false

List all local data branches and identify the currently linked branch.

reset_db_branch

true

Reset the active branch data directory back to its base snapshot (requires --allow-write).

Editor and Agent Integration

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "pgcow": {
      "command": "npx",
      "args": ["-y", "pgcow", "--mcp"]
    }
  }
}

Claude Code CLI

claude mcp add pgcow -- npx -y pgcow --mcp

Programmatic Usage (JSR / TypeScript)

import * as bridge from "jsr:@kanchingyg/pgcow/bridge";

Runtime Safety and Guardrails

  • Stdio frame isolation: When --mcp is active, hijackStdoutForMcp() redirects accidental console.log calls to stderr so JSON-RPC 2.0 frames on stdout never corrupt.

  • Read-only by default: Mutating tools (mutates: true) are blocked in --dry-run mode and require explicit --allow-write authorization.

  • Loop breaker: Repeated identical (toolName, args) invocations are hashed with SHA-256 and halted after 3 consecutive repeats to prevent runaway agent loops.

  • Context budget truncation: Tool outputs are middle-truncated (60% head / 40% tail) scaled to the probed local model n_ctx (Ollama /api/show, llama.cpp /props, vLLM /v1/models).

  • Secret redaction and path normalization: AWS keys (AKIA*, ASIA*), bearer tokens, and sk-* keys are scrubbed before returning tool output, and Windows drive paths (C:\...) translate cleanly to /mnt/c/... when WSL mode is enabled.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables git-branch-style A/B experimentation for long-running tasks, allowing users to create, compare, promote, discard, or roll back parallel conversation branches via MCP tools.
      15
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to checkpoint, diff, search, branch, merge, and restore intermediate states of pending Perforce changelists without submitting them. Each snapshot is stored as a local Git commit outside the Perforce workspace, so agents can commit milestones automatically and roll files back to earlier revisions.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude Code, Codex, Cursor, and other MCP clients to run agent file edits and shell commands inside isolated copy-on-write workspace branches guarded by a kernel-level macOS Seatbelt sandbox. Exposes tools to inspect status, diff, merge branches, and apply changes back to the real project folder only on explicit request.
      MIT