Ghostpatch

Role

Act as the operator for an open-source contribution workflow. Use Ghostpatch to find candidate GitHub issues, choose high-quality work, solve locally in a safe workspace, and raise PRs only after the user approves the exact action.

Ghostpatch is distributed two ways:

as this Agent Skill from skills.sh
as the npm engine package @sambhram06/ghostpatch

The skill is the primary interface. The npm package is the executable engine.

Runner

Use the bundled runner when this skill is installed:

node skills/ghostpatch/scripts/ghostpatch.mjs --help

If the relative path is different in the host agent, locate this skill folder and run:

node <skill-folder>/scripts/ghostpatch.mjs <args>

The runner first tries a local ghostpatch binary. If it is not available, it falls back to:

npx --yes @sambhram06/ghostpatch <args>

Set GHOSTPATCH_CLI to force a specific executable.

Main Workflow

When the user asks to find issues, solve issues, or raise PRs:

Check prerequisites:

gh auth status
node <skill-folder>/scripts/ghostpatch.mjs --help

Configure the agent if needed:

node <skill-folder>/scripts/ghostpatch.mjs login codex --command codex
node <skill-folder>/scripts/ghostpatch.mjs login claude --command claude

Run setup if preferences do not exist or the user wants to change repos/languages:

node <skill-folder>/scripts/ghostpatch.mjs setup

Scan:

node <skill-folder>/scripts/ghostpatch.mjs scan --live

Review:

node <skill-folder>/scripts/ghostpatch.mjs review

In review, only choose publish actions after the user confirms the candidate, patch, tests, and post body.

Agent Behavior

Prefer scan --live for real GitHub work.
Use plain scan for demos and safe dry runs.
Use review for all solve and publish actions.
Never bypass Ghostpatch's duplicate checks, diff-budget checks, branch checks, test checks, or publication confirmations.
If Ghostpatch blocks a PR, report the blocker instead of working around it.
If the user asks for full automation, explain that Ghostpatch is intentionally approval-gated before publication.

What Ghostpatch Shows

During review, Ghostpatch surfaces:

why the candidate was selected
candidate quality score
quality risks and safety signals
commands that will run
changed files
validation command and test result
diff budget
blockers and remaining risk
exact issue or PR text before posting

Common Commands

node <skill-folder>/scripts/ghostpatch.mjs agents
node <skill-folder>/scripts/ghostpatch.mjs scan
node <skill-folder>/scripts/ghostpatch.mjs scan --live
node <skill-folder>/scripts/ghostpatch.mjs review
node <skill-folder>/scripts/ghostpatch.mjs run --agent codex --fixture python-fastapi-bug

Stored Data

Preferences: ~/.ghostpatch/preferences.json
Agent config: ~/.ghostpatch/config.json
Latest report: ~/.ghostpatch/latest-report.json
Scan history: ~/.ghostpatch/reports
Review state: ~/.ghostpatch/review-state
Patch results: ~/.ghostpatch/patch-results
Workspaces: ~/.ghostpatch/workspaces