Configuration

Environment Variables

CODEFACTORY_PORT is still accepted by the MCP server as a legacy fallback, but new MCP configurations should use PATCHDECK_PORT.

Storage

SQLite (Default)

By default, patchdeck stores all state in a local SQLite database:

~/.patchdeck/state.sqlite

No external database is required. This is ideal for single-user setups.

Activity Logs

patchdeck writes daily activity logs to:

~/.patchdeck/log/

These logs mirror the dashboard activity feed and are useful for debugging or auditing agent behavior.

The server also writes structured runtime logs to ~/.patchdeck/log/server.log by default. Use LOG_LEVEL, PATCHDECK_LOG_FILE, or PATCHDECK_NO_LOG_FILE=1 to tune file output.

CLI flags can override the same logging settings for a single run:

patchdeck --quiet
patchdeck --verbose
patchdeck --log-level warn
patchdeck --log-level=trace
patchdeck --log-file /tmp/patchdeck.log
patchdeck --no-log-file

The dashboard also exposes a server log viewer at /logs. It shows recent structured server logs from the in-memory ring buffer, supports level/source/search filtering, and tails new log records live while the page is open. The live tail uses Server-Sent Events over the local HTTP server, so keep access local and avoid putting the dashboard behind buffering proxies.

Dashboard Settings

The settings page in the dashboard provides a UI for:

• GitHub token management — Add, remove, and reorder saved tokens before falling back to GITHUB_TOKEN or gh auth.
• GitHub token permissions — For fine-grained PATs, grant the watched repos Metadata: read, Contents: read/write if PatchDeck will push commits, Issues: read/write, Pull requests: read/write, and Checks: read. Tokens from the same GitHub account still share one rate-limit bucket.
• Agent and model selection — Choose whether autonomous runs use Claude Code or OpenAI Codex, then select from models detected from the installed CLIs. Saved choices remain available when discovery is unavailable. If the default run fails and a code-owner fallback is launched, the fallback uses the same resolved agent; enabling Fallback to next coding agent lets patchdeck resolve that fallback to the other local CLI when needed.
• Second-model review — Optionally choose a separate Codex or Claude model to review and correct the primary agent's uncommitted work before patchdeck commits and pushes it.
• Babysitter tuning — Control polling, batching, merge-conflict handling, release automation, and automatic docs assessment.
• Runtime drain mode — Pause new background automation and manual agent-triggering actions while allowing in-flight work to finish. During drain mode, the dashboard disables Run now/apply, feedback retry, Ask Agent, manual Release, and release retry actions; matching API calls return 409 instead of queueing new agent work.
• Ignored bots — Add or remove bot logins whose comments and reviews should be ignored.
• Priority issue authors — Add GitHub logins whose issues should be evaluated and worked before the regular issue queue.
• PR comment branding — Customize the app name shown in agent-authored GitHub PR comments, or remove that signature entirely. Toggle whether the signature links back to patchdeck and includes the Posted by patchdeck footer.
• GitHub progress replies — Toggle whether the babysitter posts public Accepted/running/completed status replies while working through review comments.
• Babysitter run concurrency — Set how many babysit_pr jobs can be in-flight (queued + leased) across watcher sweeps.
• CI healing — Enable autonomous CI repair and tune retry/session limits.
• Deployment healing — Enable post-merge deployment monitoring and tune the deployment-healing timing keys listed below.
• Theme — Toggle between light and dark mode.

Agent Health and Drain Mode

Drain mode is reserved for failures that need operator action. patchdeck enables it when the selected agent is deterministically unavailable, such as a missing CLI, auth failure, or unsupported agent setting.

Transient agent health failures, including health-check timeouts, do not enable drain mode. Affected PRs log Automation skipped, leave existing queued or running feedback state intact, and can be retried on the next poll or manual run.

Repository Watch Settings

Watched repositories also have repo-level settings exposed in the dashboard's repository list and through GET /api/repos/settings plus PATCH /api/repos/settings.

New watched repos default to My PRs only with automatic release publishing disabled. If you want team-wide tracking for a repository, switch it to My PRs + teammates in the dashboard or patch ownPrsOnly: false through /api/repos/settings.

PRs added directly by URL stay tracked regardless of a repo's ownPrsOnly setting.

Issue Queue Priority

priorityIssueAuthors is a dashboard and API setting for GitHub issue queue ordering. Add GitHub account logins such as octocat; entries are matched case-insensitively and may include or omit a leading @.

Issues opened by these authors are evaluated and worked ahead of the regular issue queue. Matching evaluation and work jobs are also queued with elevated background-job priority. The default is an empty list, so issue ordering and job priority are unchanged until logins are configured.

Manual Repository Releases

Each watched repository row in the dashboard includes a Release button. Pressing it queues a manual release run for the latest unreleased merged PR in that repository, using the same release evaluation, version bump, notes, and GitHub publishing flow as automatic release creation.

Manual release runs are allowed even when autoCreateReleases is disabled, so you can keep automatic publishing off and still publish releases on demand. If the repository has no unreleased merged PRs, the API returns 409 and no release run is created.

Runtime drain mode also blocks manual release creation and release retries until drain mode is disabled. Release work already in flight is allowed to finish.

App Update Banner

On builds where APP_VERSION is a stable semver string, the dashboard calls GET /api/app-update and compares the running version to the latest stable GitHub release for jeremymcs/patchdeck. When a newer release exists, the dashboard shows an update banner with a link to the matching release page and step-by-step npm update instructions:

1. Stop the running patchdeck process.
2. Run npm install -g @jeremymcs/patchdeck@latest.
3. Start patchdeck again.

Selecting dismiss for now stores a release-scoped key in browser sessionStorage, so the banner stays hidden only for the current browser session and only for that specific latestVersion. Opening a new browser session or publishing a newer release makes the banner eligible to appear again. If the app is running a non-semver build such as dev, or if the release check fails, the banner stays hidden and the API falls back quietly.

PR Comment Branding

Agent-authored GitHub PR comments posted by the babysitter — follow-up replies on review threads, agent-command acknowledgements, status updates, and CI alerts — are branded as patchdeck by default. Each comment references the configured app name and, by default, appends a Posted by [patchdeck](https://github.com/jeremymcs/patchdeck) footer that links back to this repository. Set the GitHub reply signature to a different name to replace patchdeck, or leave it blank to remove the visible app signature from GitHub replies and footers.

These settings are available in the dashboard settings page and as githubCommentAppName (string), includeRepositoryLinksInGitHubComments (boolean), and postGitHubProgressReplies (boolean) in GET /api/config, PATCH /api/config, and the MCP update_config tool. Turning repository links off is useful for private forks or environments where operators do not want outgoing PR comments to link to the upstream patchdeck repository.

CI Healing Settings

patchdeck can track failing CI checks as first-class healing sessions and, when enabled, dispatch bounded repair attempts in isolated worktrees.

The dashboard shows healing state on each tracked PR, while the local API exposes GET /api/healing-sessions and GET /api/healing-sessions/:id for external tooling.

Babysitter Queue Settings

patchdeck paces autonomous PR babysitter dispatch using a global in-flight cap for babysit_pr jobs.

This value maps to maxConcurrentBabysitRuns in GET /api/config and PATCH /api/config.

Agent Spend Settings

Every spawn of the codex or claude CLI is recorded in a local ledger, whichever path caused it: PR work, feedback evaluation, issue work, issue decompose and verify, CI healing, deployment healing, PR questions, release notes, and social posts. Agent health-check probes are recorded too, but never counted against the ceiling.

The window rolls continuously rather than resetting at the top of the hour. When the ceiling is reached, the dispatcher stops claiming agent-invoking jobs and any agent run started inside an already-running job is refused. Queued work is not failed: it waits, and resumes on its own as the oldest run ages out of the window. The header shows current usage once a ceiling is set.

This value maps to maxAgentInvocationsPerHour in GET /api/config and PATCH /api/config. GET /api/agent-spend reports usage, the ceiling, when the next slot frees up, and a breakdown by work kind.

Deployment Healing Settings

patchdeck can monitor merged PRs for failed Vercel or Railway deployments and open a follow-up fix PR when the deployment breaks after merge.

A repository is eligible only when platform detection finds one of these markers in the app-owned repo cache:

• Vercel — vercel.json, .vercel/project.json, or a package.json script containing vercel
• Railway — railway.toml, railway.json, or nixpacks.toml

These values map to autoHealDeployments, deploymentCheckDelayMs, deploymentCheckTimeoutMs, and deploymentCheckPollIntervalMs in GET /api/config and PATCH /api/config.

Deployment healing also requires the matching platform CLI on the machine running patchdeck:

• Install and authenticate vercel to heal Vercel deployments.
• Install and authenticate railway to heal Railway deployments.

Deployment session history is exposed on the dashboard Deployments page, through GET /api/deployment-healing-sessions, GET /api/deployment-healing-sessions/:id, and the matching MCP read tools.

Build & Deploy

Development

npm run dev          # Start dev server with hot reload

Production

npm run build        # Bundle client and server
npm run start        # Run production server

Desktop App

npm run tauri:dev    # Tauri dev build
npm run tauri:build  # Tauri production build