# jiezeng2004-design/PatchWarden [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/jiezeng2004-design/PatchWarden  
**GitHub Stars:** 6  
**npm Downloads (last month):** 604  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/jiezeng2004-design-patchwarden

## Description
Local-first MCP safety and verification layer for AI coding agents with workspace confinement, command allowlists, scope-violation detection, and auditable task evidence. Install: npx -y patchwarden@0.6.1.

## Tools
Capabilities this server exposes over MCP:

- **save_plan** — Save an execution plan — ChatGPT writes the plan, PatchWarden stores it for local agent execution. Supports plan_ref to load a plan file already placed inside .patchwarden/plans.
- **get_plan** — Read a saved plan by its plan_id.
- **health_check** — Check MCP catalog consistency, watcher freshness/supervisor state, workspace readiness, and configured agents. Use detail=self_diagnostic for expanded read-only evidence.
- **list_agents** — List configured local agents and check whether each executable currently exists. This does not start an agent or contact its model provider.
- **create_task** — Create a repo-scoped task from exactly one source. For ChatGPT, prefer the guarded inspect_only, feature_small, or fix_tests template when it fits. A stale watcher preserves the task but returns execution_blocked and directs the client to health_check; otherwise call wait_for_task until terminal. Use execution_mode=assess_only to pre-assess risk and get an assessment_id without creating a task; then invoke the returned next_tool_call using only execution_mode=execute and the full assessment_id.
- **get_task_status** — Check task status, execution phase, watcher health, pending reason, current command, timeout, and change evidence.
- **get_result** — Read result.md, or return structured availability and watcher evidence while the task is not terminal.
- **get_result_json** — Read the structured result.json for deterministic task acceptance.
- **get_diff** — Read task diff evidence, or return structured availability and watcher evidence while it is not ready.
- **get_test_log** — Read test.log, or return structured availability and watcher evidence while it is not ready.
- **list_workspace** — List files and directories within the workspace (sensitive files excluded).
- **read_workspace_file** — Read a file within the workspace. Sensitive files (secrets, keys, tokens) are blocked. In Direct mode (with session_id), reads are scoped to the session's repo_path and return sha256.
- **list_tasks** — List recent tasks with status/repo/active filters plus watcher state and computed pending reasons.
- **cancel_task** — Request graceful cancellation. The runner that owns the child process performs termination; the MCP server never kills a PID read from task files.
- **kill_task** — Request immediate termination of a pending or running task. The runner validates and kills only the child process it owns.
- **retry_task** — Create a new task with the same plan, agent, repo_path, and test_command as an existing task. The original task is unchanged.
- **get_task_stdout_tail** — Read the last N lines of agent stdout/stderr. Reads from real-time stdout.log/stderr.log during execution, falls back to result.md after completion. Works on pending, running, and completed tasks. Default 80 lines.
- **get_task_log_tail** — Read the last N lines of a task log file (stdout/stderr/test/verify) with automatic secret redaction. Default 80 lines, max 200. Always returns tail only — never the full file. Use this instead of read_workspace_file to avoid triggering platform content filters on log output.
- **get_task_progress** — Read progress.md for task phases and the most recent heartbeat/current command.
- **wait_for_task** — Long-poll a task for up to 30 seconds. If continuation_required=true, call wait_for_task again immediately and do not finish the assistant turn. Terminal responses include get_task_summary acceptance evidence.
- **get_task_summary** — Return structured acceptance evidence. Use view=compact first for bounded counts and risk excerpts; use standard only when full changed-file and log-tail detail is required.
- **audit_task** — Independently audit a task's outputs. Verifies status, result.md, test.log, git.diff, repo_path consistency, cross-references agent claims with package.json scripts, and flags unverified release/publish claims. Evidence-backed failures, possible heuristic false positives, and manual-verification items are returned separately. Writes independent-review.md to the task directory.
- **safe_status** — Return minimal task lifecycle status without exposing diff, log content, file contents, or sensitive paths. Use this when only task state is needed and content-bearing tools may be blocked by upper-layer security.
- **create_direct_session** — Create a Direct editing session for ChatGPT to apply patches directly. Requires enableDirectProfile: true in config.
- **search_workspace** — Search file contents (grep-like) within a Direct session's repo_path. Skips .git, node_modules, dist, release, and sensitive files.
- **apply_patch** — Apply JSON patch operations to a file within a Direct session's repo_path. Validates expected_sha256 before applying. Supports replace_exact, insert_before, insert_after, replace_whole_file.
- **run_verification** — Run a whitelisted verification command within a Direct session. Command must be in the Direct allowlist.
- **finalize_direct_session** — Finalize a Direct session: capture after snapshot, generate diff/summary/change artifacts, mark session as finalized. Must be called before audit_session.
- **audit_session** — Independently audit a Direct session's changes. Performs 16 deterministic checks and returns pass/warn/fail decision. Requires session to be finalized first.
- **sync_file** — Copy a file from source to target within the same Direct session repo. Both paths must be inside the session repo_path. Returns before/after sha256 hashes and whether the target changed.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "patchwarden": {
    "command": "npx",
    "args": ["-y","patchwarden@0.6.1"],
    "env": {
      "CONTROL_PLANE_API_KEY": "",
      "PATCHWARDEN_OWNER_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `CONTROL_PLANE_API_KEY`, `PATCHWARDEN_OWNER_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What jiezeng2004-design/PatchWarden MCP server does

jiezeng2004-design/PatchWarden provides a controlled execution path between a planning interface such as ChatGPT and coding agents already installed on the local machine. The local agent remains responsible for performing the development task, while PatchWarden applies workspace and command boundaries around that work.

The server is intended for tasks where a developer wants an agent to modify a specific project, run approved checks, and produce evidence that can be reviewed afterward. It is not an unrestricted remote shell, remote desktop, or replacement for Codex CLI, Claude Code, or OpenCode.

## How it works

A typical workflow starts with a task and constraints from ChatGPT. PatchWarden selects an available local agent, requires work to remain under the configured `workspaceRoot`, and limits verification commands to an allowlist. After execution, it records the actual changed files rather than relying only on the agent's summary.

The resulting evidence can include a task ID, lineage ID, diff, verification result, out-of-scope change status, audit state, and final lineage state. Independent verification is recorded separately from task execution. A task may remain `ready_for_review` after an audit succeeds; local `patchwarden-attest <task_id> --accept` is used for evidence-bound human acceptance.

jiezeng2004-design/PatchWarden can be exposed through the project's MCP tunnel workflow for ChatGPT or through local HTTP MCP. The local HTTP mode requires an owner token for detailed health information and the `/mcp` endpoint. Direct editing is optional and remains subject to workspace, sensitive-path, and confirmation controls.

## Setup and configuration

The documented packaged installation uses the Windows x64 installer or portable release. Running from source or npm requires Node.js 20 or newer. Git is recommended when reliable diffs are needed. At least one of Codex CLI, Claude Code, or OpenCode must be installed and logged in locally before it can be called.

Choose a dedicated project directory for `workspaceRoot`; the documentation advises against using a disk root, home directory, Desktop, or Downloads directory. In the desktop application, inspect the local agent and model settings, then confirm workspace, agent, and Core health before connecting an external client.

For ChatGPT access, configure a dedicated Core Tunnel with a runtime key having Tunnels Read and Use permissions. The runtime key maps to `CONTROL_PLANE_API_KEY` and should not be placed in ChatGPT's authentication field. If using local HTTP MCP directly, configure `PATCHWARDEN_OWNER_TOKEN` first.

## Tools and capabilities

Documented MCP operations include `health_check` for service status and `list_agents` for discovering callable local agents. The execution workflow also supports controlled task handling, verification, diff inspection, audit evidence, lineage tracking, and acceptance-related status.

## Limitations and notes

jiezeng2004-design/PatchWarden does not automatically expose every local file and should not be used to bypass existing host security controls. Verification commands that are absent from the project or fail the allowlist are rejected. Direct is not a read-only channel: when enabled, it can support constrained patching, creation, moving, and deletion, so it should remain disabled unless needed and protected by confirmation.

The project recommends testing first in a disposable repository and preserving manual confirmation for higher-risk operations. Tunnel keys, API keys, account secrets, and tunnel identifiers should not appear in prompts, screenshots, logs, or repositories. The software is licensed under MIT.

_Full upstream README: https://allmcps.com/mcp/jiezeng2004-design-patchwarden/readme_