From 943538276eacd41c689d401582e6a746d297b4eb Mon Sep 17 00:00:00 2001 From: Alex Shapalov Date: Mon, 26 Oct 2026 11:05:51 -0700 Subject: [PATCH 1/2] feat: distribute PGX through Claude Code Plugin Marketplace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a Claude Code plugin marketplace (`pgrundev`, .claude-plugin/marketplace.json) with one plugin, `pgx` (plugins/pgx), so Claude Code users install the PGX Agent Skill inside a session: /plugin marketplace add pgrundev/pgx /plugin install pgx@pgrundev /pgx:pgx Set up isolated Postgres databases for this project. The plugin packages the canonical Skill (skills/pgx) unchanged: plugins/sync.sh copies it into plugins/pgx/skills/pgx and `--check` fails CI on drift. It ships no hooks, MCP servers or binaries; project hooks keep coming from `pgx agent setup`, so installing the plugin at user scope does nothing in projects that have not opted in, and install/uninstall never touch .claude/settings.json. SKILL.md gains the plugin install path for its helper scripts (${CLAUDE_PLUGIN_ROOT}/skills/pgx/scripts/…, substituted when loaded from the plugin) and its metadata.version moves to 0.1.1 to match the plugin version. Tests: plugins/tests/pgx/run.sh (manifests with `claude plugin validate --strict`, directory profile, drift, hygiene, isolated install/enable/disable/ update/scope/uninstall/reinstall cycle, hooks untouched, Skills-CLI copy alongside). CI job `plugin` runs it with a pinned Claude Code CLI and scans the package with gitleaks. Docs: README, agents.md, new claude-plugin.md, references/claude-code.md. Co-Authored-By: Claude Fable 5.1 --- .claude-plugin/marketplace.json | 19 ++ .github/workflows/ci.yml | 15 ++ README.md | 28 ++- docs/pgx/local-dev/agents.md | 15 +- docs/pgx/local-dev/claude-plugin.md | 156 ++++++++++++ plugins/pgx/.claude-plugin/plugin.json | 16 ++ plugins/pgx/README.md | 58 +++++ plugins/pgx/skills/pgx/SKILL.md | 228 ++++++++++++++++++ .../skills/pgx/references/agent-lifecycle.md | 85 +++++++ .../pgx/skills/pgx/references/claude-code.md | 75 ++++++ plugins/pgx/skills/pgx/references/codex.md | 49 ++++ plugins/pgx/skills/pgx/references/cursor.md | 45 ++++ .../pgx/references/database-branching.md | 70 ++++++ .../pgx/references/database-discovery.md | 59 +++++ .../skills/pgx/references/getting-started.md | 63 +++++ .../pgx/skills/pgx/references/installation.md | 65 +++++ .../skills/pgx/references/postgres-import.md | 65 +++++ plugins/pgx/skills/pgx/references/security.md | 41 ++++ .../skills/pgx/references/troubleshooting.md | 25 ++ plugins/pgx/skills/pgx/scripts/check-pgx.sh | 31 +++ .../pgx/skills/pgx/scripts/detect-project.sh | 93 +++++++ plugins/sync.sh | 21 ++ plugins/tests/pgx/run.sh | 102 ++++++++ skills/pgx/SKILL.md | 13 +- skills/pgx/references/claude-code.md | 25 ++ 25 files changed, 1455 insertions(+), 7 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 docs/pgx/local-dev/claude-plugin.md create mode 100644 plugins/pgx/.claude-plugin/plugin.json create mode 100644 plugins/pgx/README.md create mode 100644 plugins/pgx/skills/pgx/SKILL.md create mode 100644 plugins/pgx/skills/pgx/references/agent-lifecycle.md create mode 100644 plugins/pgx/skills/pgx/references/claude-code.md create mode 100644 plugins/pgx/skills/pgx/references/codex.md create mode 100644 plugins/pgx/skills/pgx/references/cursor.md create mode 100644 plugins/pgx/skills/pgx/references/database-branching.md create mode 100644 plugins/pgx/skills/pgx/references/database-discovery.md create mode 100644 plugins/pgx/skills/pgx/references/getting-started.md create mode 100644 plugins/pgx/skills/pgx/references/installation.md create mode 100644 plugins/pgx/skills/pgx/references/postgres-import.md create mode 100644 plugins/pgx/skills/pgx/references/security.md create mode 100644 plugins/pgx/skills/pgx/references/troubleshooting.md create mode 100755 plugins/pgx/skills/pgx/scripts/check-pgx.sh create mode 100755 plugins/pgx/skills/pgx/scripts/detect-project.sh create mode 100755 plugins/sync.sh create mode 100755 plugins/tests/pgx/run.sh diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000000..dbf698ebbb --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,19 @@ +{ + "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", + "name": "pgrundev", + "description": "PostgreSQL developer tools for AI coding agents", + "owner": { + "name": "PGRunDev", + "url": "https://pgx.dev" + }, + "plugins": [ + { + "name": "pgx", + "source": "./plugins/pgx", + "description": "Give every AI coding agent its own isolated, disposable Postgres database.", + "category": "database", + "tags": ["postgres", "postgresql", "database", "ai-agents", "database-branching"], + "homepage": "https://github.com/pgrundev/pgx" + } + ] +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1b2273f5b3..1eab7d18e2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -124,6 +124,21 @@ jobs: npx -y skills@latest add "$GITHUB_WORKSPACE/skills/pgx" -a claude-code codex cursor -y test -f .claude/skills/pgx/SKILL.md && test -f .agents/skills/pgx/SKILL.md test ! -e .claude/skills/pgx/tests + plugin: + name: Claude Code plugin (marketplace, manifest, install cycle) + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: { node-version: 22 } + - name: Install the Claude Code CLI (pinned; validate/install need no login) + run: npm install -g @anthropic-ai/claude-code@2.1.310 && claude --version + - name: Plugin package tests (drift, manifests, hygiene, isolated install cycle) + run: plugins/tests/pgx/run.sh + - name: Secret scan of the plugin package and marketplace (gitleaks) + run: | + curl -fsSL https://github.com/gitleaks/gitleaks/releases/download/v8.21.2/gitleaks_8.21.2_linux_x64.tar.gz | tar -xz gitleaks + for d in plugins .claude-plugin skills; do ./gitleaks dir "$d" --no-banner --redact; done docker: name: Docker image (${{ matrix.os }}) strategy: diff --git a/README.md b/README.md index 8cad73bb7f..cc6b0b2585 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,14 @@ License: AGPL-3.0

+```text +# Claude Code: install inside a session (native plugin) +/plugin marketplace add pgrundev/pgx +/plugin install pgx@pgrundev +``` + ```bash -# Recommended: AI coding agents (Claude Code, Cursor, Codex) +# Any agent host (Claude Code, Cursor, Codex): the Agent Skills CLI npx skills add pgrundev/pgx --skill pgx # Manual PGX installation @@ -396,7 +402,16 @@ permanent or system databases, and resumes cleanup automatically after a ### Every AI agent gets its own Postgres -Install the Skill in a project, then ask your agent: +Install the Skill, then ask your agent. In Claude Code, from inside a session: + +```text +/plugin marketplace add pgrundev/pgx +/plugin install pgx@pgrundev +/pgx:pgx Set up isolated Postgres databases for this project. +``` + +For Cursor, Codex or several hosts at once, the Agent Skills CLI installs the +same Skill into the project: ```bash npx skills add pgrundev/pgx --skill pgx @@ -404,6 +419,14 @@ npx skills add pgrundev/pgx --skill pgx > Use PGX to give this project isolated databases for coding agents. Set everything up. +The plugin is the Skill packaged for Claude Code's plugin manager (`/plugin` +lists, updates and removes it; the skill is `/pgx:pgx` and Claude also picks +it up on its own when a task touches the database). The Skills CLI copies +the Skill into `.claude/skills/pgx` and `.agents/skills/pgx` for every host. +Both contain no hooks and install no database engine: the `pgx` binary is +installed when the Skill first needs it, with your approval. Details and the +differences: [`docs/pgx/local-dev/claude-plugin.md`](docs/pgx/local-dev/claude-plugin.md). + The agent detects your database setup, installs PGX if needed, imports your development database **schema-only** into a template (`pgx copy`), writes a committed `.pgx.toml`, installs lifecycle hooks (`pgx agent setup`) and @@ -563,6 +586,7 @@ any semantic difference (`classify-regress-diffs.py --fail-on-semantic`). | [`v0.1-readiness.md`](docs/pgx/v0.1-readiness.md) | what is ready, known limitations, approved use | | [`linux-results.md`](docs/pgx/linux-results.md) | the full benchmark report | | [`compatibility-gate.md`](docs/pgx/compatibility-gate.md) | how to decide whether a database can run on PGX | +| [`local-dev/claude-plugin.md`](docs/pgx/local-dev/claude-plugin.md) | the PGX plugin for Claude Code: `/plugin marketplace add pgrundev/pgx`, `/plugin install pgx@pgrundev`, how it relates to the Skills CLI install, updates, removal | | [`local-dev/agents.md`](docs/pgx/local-dev/agents.md) | the PGX Skill and `pgx agent`: automatic per-session isolation for Claude Code, Cursor and Codex, with the compatibility matrix | | [`local-dev/copy.md`](docs/pgx/local-dev/copy.md) | `pgx copy`: import an existing PostgreSQL database and branch it per agent | | [`pgrun-integration.md`](docs/pgx/pgrun-integration.md) | the host-agent API PGRun builds against | diff --git a/docs/pgx/local-dev/agents.md b/docs/pgx/local-dev/agents.md index 1bda671277..8d7ec76780 100644 --- a/docs/pgx/local-dev/agents.md +++ b/docs/pgx/local-dev/agents.md @@ -5,11 +5,24 @@ Code, Cursor or Codex session that touches your database works in its own disposable branch of a template, created in milliseconds, never shared, and cleaned up on its own. Your real PostgreSQL is read once and never written. +```text +/plugin marketplace add pgrundev/pgx # Claude Code: the Skill as a native plugin, inside a session +/plugin install pgx@pgrundev +``` + ```sh -npx skills add pgrundev/pgx --skill pgx # the Skill (recommended) +npx skills add pgrundev/pgx --skill pgx # any host (Claude Code, Cursor, Codex): the Skills CLI npx pgxdb@latest # PGX itself, if you prefer to install it by hand ``` +Three channels, one Skill: the Claude Code plugin (native install, `/plugin` +manages updates and removal, skill name `/pgx:pgx`), the Agent Skills CLI +(copies the Skill into the project for every supported host, skill name +`/pgx` in Claude Code) and the PGX CLI itself for manual use. The plugin and +the Skills CLI copy are the same files; see +[claude-plugin.md](claude-plugin.md) for the differences and for running +both. + Then open your agent in the project and ask it to set PGX up: > Use PGX to give this project isolated databases for coding agents. Set everything up. diff --git a/docs/pgx/local-dev/claude-plugin.md b/docs/pgx/local-dev/claude-plugin.md new file mode 100644 index 0000000000..4997eadb1b --- /dev/null +++ b/docs/pgx/local-dev/claude-plugin.md @@ -0,0 +1,156 @@ +# The PGX plugin for Claude Code + +**One plugin. Every Claude Code agent gets its own Postgres.** + +The repository is a Claude Code plugin marketplace named `pgrundev` +(`.claude-plugin/marketplace.json`) with one plugin, `pgx` +(`plugins/pgx/`), which packages the PGX Agent Skill for Claude Code's +plugin manager. Nothing else changes: the Skill in `skills/pgx/` stays the +canonical implementation and the Skills CLI install keeps working. + +## Install, inside Claude Code + +```text +/plugin marketplace add pgrundev/pgx +/plugin install pgx@pgrundev +``` + +The second command opens the plugin's page in the `/plugin` panel. Choose a +scope: + +| Scope | Who gets it | Written to | +|---|---|---| +| user | you, in every project on this machine | `~/.claude/settings.json` | +| project | everyone who works in this repository | `.claude/settings.json` (committed) | +| local | you, in this repository only | `.claude/settings.local.json` | + +From a shell, without a session: `claude plugin marketplace add pgrundev/pgx` +then `claude plugin install pgx@pgrundev [--scope user|project|local]`. + +Then, in a project with a database: + +```text +/pgx:pgx Set up isolated Postgres databases for this project. +``` + +`pgx:pgx` is the skill's name under the plugin's namespace. You can also just +describe database work ("add a column and run the tests"); Claude selects +the skill when it is relevant. Both routes run the same Skill: detect the +project, check for PGX 0.1.1 or newer and offer to install it, prepare a +schema-only template, `pgx agent setup`, then work inside the session's +branch. See [agents.md](agents.md) for what that gives you. + +Check what is installed: + +```sh +claude plugin list # pgx@pgrundev Version: 0.1.1 Status: enabled +claude plugin details pgx # Component inventory: Skills (1) pgx, Hooks (0), MCP servers (0) +``` + +## What the plugin contains + +- `skills/pgx/`: the Skill, its eleven reference documents and two helper + scripts, identical to `skills/pgx/` at the repository root + (`plugins/sync.sh --check` fails CI on any difference). +- `.claude-plugin/plugin.json`: name `pgx`, version `0.1.1` (the Skill's + version), display name, links. +- `README.md`. + +About 84 KB; roughly 190 tokens of context in every session while installed. + +It contains **no hooks, MCP servers, commands or binaries**. Installing it at +user scope does nothing in projects that have not opted in: the Skill is +available, and database infrastructure appears only when you ask for it in a +project and `pgx agent setup` writes that project's `.pgx.toml` and hooks. + +## Hooks: one owner, no duplicates + +Lifecycle hooks (`SessionStart` → branch, `UserPromptSubmit`/`PreToolUse` → +keep-alive, `SessionEnd` → retire) are installed per project by `pgx agent +setup`, which is idempotent and recognises its own entries by their command +string. The plugin never registers hooks of its own, so there is exactly one +source of hooks whichever way the Skill was installed, and installing, +updating, disabling or removing the plugin never touches `.claude/settings.json` +(tested in `plugins/tests/pgx/run.sh`). Fail-closed behaviour is unchanged: +it lives in `pgx agent hook`, not in the Skill files. + +## The plugin and the Skills CLI together + +`npx skills add pgrundev/pgx --skill pgx` copies the Skill into +`.claude/skills/pgx` (and `.agents/skills/pgx`). That copy is a plain skill +named `pgx`. With the plugin installed as well, Claude Code lists both +`/pgx` and `/pgx:pgx` (verified: the session inventory shows the two names +side by side; neither hides the other). They are the same text, so whichever +Claude picks runs the same workflow, and nothing is duplicated at the +database level because branches and hooks come from `pgx agent`, not from +the skill files. The cost is two descriptions in context. + +To keep one copy, either remove the Skills CLI one (`npx skills remove pgx`, +which deletes only `.claude/skills/pgx` and `.agents/skills/pgx`) or the +plugin (`/plugin uninstall pgx@pgrundev`). Switching from the Skills CLI to +the plugin is those two steps; nothing in `.pgx.toml`, the hooks or the +databases changes. + +Cursor and Codex are not Claude Code plugins hosts: keep using the Skills +CLI for them. The PGX runtime itself is independent of both. + +## Update, disable, remove + +| Action | In a session | In a shell | +|---|---|---| +| Update | `/plugin` → Installed → pgx → Update now | `claude plugin update pgx@pgrundev` | +| Disable / enable | `/plugin` → Installed → Space | `claude plugin disable pgx@pgrundev` / `enable` | +| Remove | `/plugin uninstall pgx@pgrundev` | `claude plugin uninstall pgx@pgrundev` | +| Remove the marketplace | `/plugin marketplace remove pgrundev` | `claude plugin marketplace remove pgrundev` | + +Updates follow the plugin's `version` field: a new PGX Skill release bumps +it and `claude plugin update` (or the marketplace's auto-update, off by +default for third-party marketplaces) fetches it; users on an older copy keep +working. + +Uninstalling removes the Skill files from Claude Code's plugin cache and the +`enabledPlugins` entry, nothing else: PGX databases, templates, `.pgx.toml`, +the PGX runtime and any hooks `pgx agent setup` installed all stay. +`pgx agent uninstall` removes a project's hooks when you want that. + +## Performance and what gets downloaded + +`/plugin marketplace add pgrundev/pgx` clones the PGX repository once per +machine into `~/.claude/plugins/marketplaces/pgrundev/` (Claude Code reads +the catalog from a clone). The repository carries fuzzing corpora and +benchmark results, so that clone is about 190 MB over the network and 2.2 GB +on disk and takes one to two minutes; `claude plugin marketplace update` +afterwards is incremental. The plugin itself is copied out of that clone: +the installed plugin is the 84 KB Skill package, nothing from `crates/`, +`fuzz/` or `benchmarks/`. From a shell you can keep the clone small: + +```sh +claude plugin marketplace add pgrundev/pgx --sparse .claude-plugin plugins +``` + +which checks out only the marketplace file and the plugin (a few hundred KB). +The in-session `/plugin marketplace add` has no sparse option. Making the +default clone light would mean moving the corpora out of the main repository +or hosting the catalog elsewhere; both are repository decisions outside this +plugin. + +## Anthropic's plugin directory + +The marketplace above is self-hosted. PGX is not listed in Anthropic's +directory; `claude plugin validate --profile directory plugins/pgx` reports +no refusals (an icon is recommended), and a submission would go through +claude.ai/directory/manage with the metadata in `plugin.json`. That is a +separate, human-approved step. + +## Tests + +`plugins/tests/pgx/run.sh` (CI job `plugin`): drift check against +`skills/pgx`, version agreement, packaging hygiene (no hooks, binaries, +symlinks, parent paths, absolute paths, credentials), `claude plugin validate +--strict` on the plugin and the marketplace, the directory profile, and a +full install → list → details → disable → enable → update → project/local +scope → uninstall → reinstall → marketplace remove cycle from the repository +as a local marketplace in an isolated `CLAUDE_CONFIG_DIR`, plus the +"existing hooks untouched" and "Skills CLI copy alongside" cases. The +Skills CLI contract (`skills/tests/pgx/run.sh`, `skills-ref validate`) is +unchanged and still runs. diff --git a/plugins/pgx/.claude-plugin/plugin.json b/plugins/pgx/.claude-plugin/plugin.json new file mode 100644 index 0000000000..ed1d73ce81 --- /dev/null +++ b/plugins/pgx/.claude-plugin/plugin.json @@ -0,0 +1,16 @@ +{ + "name": "pgx", + "displayName": "PGX — Postgres for Agents", + "version": "0.1.1", + "description": "Isolated, disposable PostgreSQL-compatible databases for AI coding agents.", + "author": { + "name": "PGRunDev", + "url": "https://pgx.dev" + }, + "homepage": "https://pgx.dev", + "repository": "https://github.com/pgrundev/pgx", + "license": "AGPL-3.0", + "keywords": ["postgres", "postgresql", "database", "ai-agents", "database-branching"], + "documentationUrl": "https://github.com/pgrundev/pgx/blob/main/docs/pgx/local-dev/agents.md", + "supportUrl": "https://github.com/pgrundev/pgx/issues" +} diff --git a/plugins/pgx/README.md b/plugins/pgx/README.md new file mode 100644 index 0000000000..1f37514521 --- /dev/null +++ b/plugins/pgx/README.md @@ -0,0 +1,58 @@ +# PGX — Postgres for Agents + +One plugin. Every Claude Code agent gets its own Postgres. + +PGX is a local, PostgreSQL-compatible runtime built for disposable databases: +copy-on-write branches created in milliseconds and removed automatically when +their time-to-live runs out. This plugin ships the `pgx` Agent Skill, which +gives each Claude Code session its own branch of your project's database, so +parallel agents, migrations and test runs never touch your real PostgreSQL and +never overwrite one another. + +## Install inside Claude Code + +```text +/plugin marketplace add pgrundev/pgx +/plugin install pgx@pgrundev +``` + +Pick the scope in the dialog: **user** makes the skill available in every +project on this machine, **project** or **local** limit it to one repository. +Shell equivalent: `claude plugin marketplace add pgrundev/pgx` then +`claude plugin install pgx@pgrundev`. + +## Use it + +Invoke the skill explicitly: + +```text +/pgx:pgx Set up isolated Postgres databases for this project. +``` + +or just describe database work ("run the pending migrations and the tests", +"set up Postgres for my agents"); Claude selects the skill when it is relevant. + +The first activation in a project walks through detection of the existing +database setup, a one-time `pgx agent setup`, and from then on every new +Claude Code session in that project starts with `DATABASE_URL` pointing at its +own branch. + +## What it contains, and what it does not + +- The skill (`skills/pgx/SKILL.md`), its reference documents and two helper + scripts (project detection, version check). About 190 tokens of context + while installed. +- No hooks, MCP servers or background processes. Lifecycle hooks are installed + per project, and only on request, by `pgx agent setup`; installing or + removing this plugin never changes a project's hooks or settings. +- No database engine. The `pgx` binary (PGX 0.1.1 or newer) is installed + separately when the skill first needs it: `npm i -g pgxdb` or the official + installer. The skill asks before downloading anything. + +Removing the plugin (`/plugin uninstall pgx@pgrundev`) removes the skill only. +Databases, templates, `.pgx.toml` and the PGX runtime stay; `pgx agent +uninstall` removes a project's hooks when you want that. + +The same skill is also installable with the Agent Skills CLI for Cursor and +Codex: `npx skills add pgrundev/pgx --skill pgx`. Documentation: +https://github.com/pgrundev/pgx/blob/main/docs/pgx/local-dev/agents.md diff --git a/plugins/pgx/skills/pgx/SKILL.md b/plugins/pgx/skills/pgx/SKILL.md new file mode 100644 index 0000000000..4e32151f28 --- /dev/null +++ b/plugins/pgx/skills/pgx/SKILL.md @@ -0,0 +1,228 @@ +--- +name: pgx +description: > + Give every AI coding agent its own isolated, disposable PostgreSQL-compatible + database with PGX. Use when a task touches a Postgres database: setting up a + database for development or tests, running Rails, Django, Prisma, SQLAlchemy, + Go or Node migrations and seeds, testing a migration without touching the + existing database, creating a disposable Postgres or a database branch for a + feature, isolating concurrent coding agents, or "set up Postgres for my AI + agents". Detects the project's database setup, installs PGX if missing, + prepares a safe schema-only template from an existing PostgreSQL or a fresh + PGX database, sets up per-session branches with automatic DATABASE_URL + injection for Claude Code, Cursor and Codex, and cleans up expired branches. +license: AGPL-3.0 +metadata: + author: pgrundev + version: "0.1.1" + homepage: https://pgx.dev + repository: https://github.com/pgrundev/pgx +--- + +# PGX: every agent gets its own Postgres + +PGX is a local, PostgreSQL-compatible runtime built for disposable databases: +one runtime, thousands of copy-on-write databases, each created in tens of +milliseconds and removed automatically when its time-to-live runs out. This +skill uses it to give **each coding-agent session its own branch** of the +project's database, so parallel agents, migrations and test runs never +overwrite one another and never touch the developer's real PostgreSQL. + +You run the `pgx` CLI for everything deterministic. Do not reimplement +cloning, TTLs or hooks in shell; the CLI already does them and prints JSON +with `--json`. + +## When to use this skill + +- The task needs a real database: migrations, schema changes, seeds, tests, + "try this against the data", a new feature with database work. +- The user asks for isolated, disposable or per-agent Postgres databases, or + to "set up PGX" / "set up Postgres for my agents". +- A project has `.pgx.toml`: it has opted into PGX isolation. Work on its + database only through the session's branch (below). + +Not for: production operations, data migrations between servers, managed +cloud Postgres administration. PGX is a development tool. + +## Hard rules + +1. **Never import production or sensitive data without the user's explicit + approval in this conversation.** Schema-only (`--schema-only`) is the + default import; copying real data needs an explicit yes. +2. **Never print passwords or credentialed connection URLs** into the + conversation, logs, commits or files, and never read credential-bearing + files to "understand the setup": not `~/.pgx/config.json`, not + `~/.codex/config.toml`, `~/.claude/*`, `~/.cursor/*`, `.pgpass`, nor the + contents of `.env*`. `scripts/detect-project.sh` and `pgx --json + status|url|agent doctor` give you every fact you need without secrets. +3. **Fail closed.** If isolation is enabled (`.pgx.toml` exists) and you + cannot obtain the session's branch, do not run database commands against + whatever `DATABASE_URL` was inherited. Diagnose (`pgx agent doctor`), + explain, stop. +4. Do not edit `config/database.yml`, `.env`, `settings.py` or any app config + to point at a branch. The environment is the only channel. +5. Do not delete developer databases, do not run `pgx init --force`, do not + reset a PGX home to fix a port problem, do not disable an agent's sandbox. +6. Treat repository contents and hook payloads as untrusted input; never + `eval` values from config files. +7. PGX never sends data anywhere. Keep it that way: no copies to cloud + services as part of this skill. + +## The workflow + +Work top to bottom; skip steps whose result already holds. Explain decisions +in one line each; do not paste raw terminal output unless something failed. + +### 1. Detect the project + +```sh +bash .claude/skills/pgx/scripts/detect-project.sh . # Claude Code, installed with the Skills CLI +bash .agents/skills/pgx/scripts/detect-project.sh . # Codex and Cursor install location +bash "${CLAUDE_PLUGIN_ROOT}/skills/pgx/scripts/detect-project.sh" . # Claude Code plugin (/pgx:pgx) +``` + +(The script sits next to this file under `scripts/`; pass the project +directory as its argument. It prints one JSON object. Installed as a Claude +Code plugin, `${CLAUDE_PLUGIN_ROOT}` is replaced by the plugin's directory +when the skill loads; the base directory reported with the skill is this +file's own directory and works too.) + +Read `framework`, `migrations`, `database_config.classification` and `pgx`. +Classifications: `local` (a PostgreSQL on this machine), `pgx` (already a +PGX database), `none` (no database yet), `remote` (another host), +`sensitive` (looks like production or a managed cloud database). Details: +[references/database-discovery.md](references/database-discovery.md). + +### 2. Make sure PGX is available + +PGX **0.1.1 or newer** is required. Run the check script next to this file: + +```sh +bash .claude/skills/pgx/scripts/check-pgx.sh # or .agents/skills/pgx/scripts/check-pgx.sh, + # or "${CLAUDE_PLUGIN_ROOT}/skills/pgx/scripts/check-pgx.sh" (plugin) +``` + +It prints `{"ok":true,"version":…}` and exits 0 for a compatible binary; +exit 3 means `pgx` is missing, 2 too old (for example the published 0.1.0, +which has no `pgx agent`), 4 an unreadable `pgx --json version`. It reads the +structured version only: `pgx agent --help` prints the global help on every +version and proves nothing. If `pgx` is missing or too old, +follow [references/installation.md](references/installation.md): prefer an +installed binary, then `npm i -g pgxdb` (Node 18+), then the official +installer `curl -fsSL https://pgx.dev/install | sh`. Supported: macOS arm64, +Linux amd64, Linux arm64. PGX picks a free port and never disturbs a +PostgreSQL on 5432. Installing is a network download: follow the host's +approval flow and say what will be installed and where. + +### 3. Prepare the source template + +The template is the database every agent branch is cloned from. It must be +idle (nothing connected to it); agents never connect to it directly. + +| Classification | What to do | +|---|---| +| `local` | Existing PostgreSQL: `pgx copy --from "" --to _template --schema-only`. Read [references/postgres-import.md](references/postgres-import.md) first (source rules, extensions, data-copy approval). Pass the URL through an environment variable or a file the user already has; never type credentials into the conversation. | +| `pgx` | The project already has a PGX template: reuse it (`pgx ls`), do not copy again. | +| `none` | New project: `pgx agent setup` creates an empty `app`; then run the framework's normal schema setup *inside the branch* (step 5). | +| `remote` / `sensitive` | Stop and ask. Explain that PGX would copy from that server, offer schema-only, and proceed only with explicit approval. Never auto-import. | + +### 4. One-time project setup + +```sh +pgx agent setup --source