promptvc

Local-first, prompt-by-prompt diff tracking for AI coding sessions.

Requirements

• Node.js 22+ (use nvm: nvm install 22 && nvm use 22)
• npm 11.5.1 (set PROMPTVC_EXPECTED_NPM_VERSION to override)
• Git
• Codex CLI 0.80.0 (set PROMPTVC_EXPECTED_CODEX_VERSION to override)
• Claude Code (for Claude session capture)
• Gemini CLI (for Gemini session capture)
• jq (optional; legacy hook fallback)
• macOS/Linux
• Windows: Git Bash required (run promptvc + codex in Git Bash)

Windows notes

If the legacy shell hook fallback is used, install jq (pick one):

winget install jqlang.jq

choco install jq

scoop install jq

Install

npm install -g promptvc

Setup (recommended)

promptvc config

This command finds the installed notify hooks, verifies Codex/npm versions, and updates ~/.codex/config.toml, ~/.claude/settings.json, and ~/.gemini/settings.json. If it cannot edit a file, it prints a ready-to-paste snippet.

If you need to bypass the version guard, set:

PROMPTVC_ALLOW_VERSION_MISMATCH=1

Manual setup

Add to ~/.codex/config.toml:

notify = ["/absolute/path/to/promptvc/hooks/codex-notify.sh"]

If installed globally via npm, the hook is typically at:

$(npm root -g)/promptvc/hooks/codex-notify.sh

Add (or merge) into ~/.claude/settings.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/absolute/path/to/promptvc/hooks/claude-notify.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/absolute/path/to/promptvc/hooks/claude-notify.sh"
          }
        ]
      }
    ]
  }
}

If installed globally via npm, the hook is typically at:

$(npm root -g)/promptvc/hooks/claude-notify.sh

Add (or merge) into ~/.gemini/settings.json:

{
  "tools": {
    "enableHooks": true
  },
  "hooks": {
    "AfterAgent": [
      {
        "hooks": [
          {
            "name": "promptvc-notify",
            "type": "command",
            "command": "/absolute/path/to/promptvc/hooks/gemini-notify.sh",
            "description": "Capture prompt responses for PromptVC"
          }
        ]
      }
    ]
  }
}

If installed globally via npm, the hook is typically at:

$(npm root -g)/promptvc/hooks/gemini-notify.sh

Version guard

PromptVC checks Codex and npm versions during promptvc config and promptvc init.

• Expected Codex: 0.80.0 (override with PROMPTVC_EXPECTED_CODEX_VERSION)
• Expected npm: 11.5.1 (override with PROMPTVC_EXPECTED_NPM_VERSION)
• Bypass the guard: PROMPTVC_ALLOW_VERSION_MISMATCH=1

Usage

Initialize a repo:

cd /path/to/your/repo
promptvc init

Run Codex:

codex

List sessions:

promptvc list

Show a session:

promptvc show <session-id>

Optional Codex wrapper:

promptvc-codex

Troubleshooting

• If promptvc resolves to a Python shim, run which promptvc and ensure your npm global bin is ahead of pyenv on PATH.
• If you’re using the legacy shell hook fallback, ensure jq is installed and available on PATH.