Skip to main content
command CX Codex

plan-attest — Claude Code command: what it does, how to install

plan-attest locks the active task_plan.md file using a SHA-256 hash. Built-in hooks prevent plan injection into model prompts whenever the file content diverges from the attested hash.

MIT ★ 28,179 updated 2026-11-04

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
Open on GitHub

What plan-attest does

The command delegates execution to attest-plan.sh or attest-plan.ps1 from the planning-with-files repository. It records a SHA-256 digest for the active plan without manual file writes, running under Bash with model invocation disabled. The feature is available starting with v2.37.0.

Once locked, every UserPromptSubmit and PreToolUse hook checks task_plan.md against the stored checksum. If the file diverges, the hook outputs [PLAN TAMPERED — injection blocked] and stops feeding plan data into the context.

PowerShell installs support -Show and -Clear but omit the -Target parameter available in the shell script. If multiple plan files exist without an explicit PLAN_ID, the helper halts instead of choosing an arbitrary task.

What it helps with

  • Prevent unauthorized changes to task_plan.md during agent runs
  • Block modified plan injection in PreToolUse and prompt hooks
  • Inspect the stored SHA-256 attestation digest and path
  • Clear the stored attestation to allow manual plan edits

Example prompts for the agent

  • /plan-attest
  • /plan-attest --show
  • /plan-attest --clear

How to install plan-attest

1Plugin marketplace

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

2Manually: put the files in place

.claude/commands/plan-attest.md

Call it with /plan-attest. For all projects use ~/.claude/commands/

Questions about plan-attest

How to install plan-attest in Claude Code?

Run /plugin marketplace add OthmanAdi/planning-with-files followed by /plugin install planning-with-files@planning-with-files. You can also configure it via .claude/commands/plan-attest.md.

What does plan-attest do?

It calculates a SHA-256 hash of task_plan.md and saves the attestation. The hooks compare the file to this hash before passing plan context to the model.

What happens when task_plan.md changes after attestation?

Hooks detect the hash divergence and return [PLAN TAMPERED — injection blocked]. To apply the updates, run /plan-attest again or unlock the file with /plan-attest --clear.

Source text

plan-attest.md · MIT
---
description: "Lock the current task_plan.md content with a SHA-256 attestation. Hooks then refuse to inject plan content if the file diverges from the attested hash, blocking silent tampering. Use --show to print the stored hash, --clear to remove the attestation. Available since v2.37.0."
disable-model-invocation: true
allowed-tools: "Bash"
---

Run the plan attestation helper for the active plan.

Steps:
1. Forward the requested operation to the installed helper: `--show` or `--clear` for `attest-plan.sh`, `-Show` or `-Clear` for `attest-plan.ps1`, or no flag to attest.
2. Let that helper resolve the selected plan and storage path. Do not reproduce its selection logic or write an attestation manually.
3. If it reports an invalid explicit selector or multiple named plans, stop and ask for the exact `PLAN_ID`; do not substitute another task.
4. Report the helper's result and storage path to the user, including `Multiple plans are available` when it refuses ambiguity. The shared pointer does not bind a parallel session.

An explicit `${PLAN_ID}` or `${PWF_PLAN_ROOT}` that does not resolve exits with an error. It never falls back to another plan.

Implementation:
- On Linux/macOS/Git Bash: `sh ${CLAUDE_PLUGIN_ROOT}/scripts/attest-plan.sh`
- On Windows PowerShell plugin installs: `& "$env:CLAUDE_PLUGIN_ROOT\scripts\attest-plan.ps1"`
- On Windows PowerShell standalone installs: `& "$env:USERPROFILE\.claude\skills\planning-with-files\scripts\attest-plan.ps1"`

Flags:
- `--show` — print the currently stored hash and where it lives.
- `--clear` — remove the attestation (re-open the plan to free editing).
- Shell `--target root` or `--target <plan-id>` selects an explicit attestation target for this call; forward it when requested. PowerShell has `-Show` and `-Clear`, but no `-Target` parameter.

After running an attestation, every UserPromptSubmit and PreToolUse hook fire compares `task_plan.md` against the stored hash. If they diverge, the hook emits `[PLAN TAMPERED — injection blocked]` instead of feeding plan content into the model. Re-run `/plan-attest` whenever you intentionally edit and re-approve the plan.

© OthmanAdi · MIT · OthmanAdi/planning-with-files

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set14

The whole set →
pwf The pwf command sets up the planning-with-files workflow, generating a task plan, findings log and progress file for the current project. CX Codex +1 ★ 28,179repo stars status Displays current task phases, completion percentage, and errors from task_plan.md. Runs when you need a quick status check without loading companion files into context. CX Codex +1 ★ 28,179repo stars plan-doctor The plan-doctor command for Claude Code checks planning-with-files plan lookup, injection, and attestation. Run it when hooks go silent or on a new machine. CX Codex +1 ★ 28,179repo stars plan-goal plan-goal builds a completion condition out of task_plan.md and feeds it to /goal, so the agent keeps moving through the whole plan. CX Codex +1 ★ 28,179repo stars plan-loop plan-loop — a planning-aware slash command runs recurring /loop checks against your plan files. Use it when phased work needs a regular progress tick. CX Codex +1 ★ 28,179repo stars planning-with-files planning-with-files keeps a multi-step task plan in three markdown files and pulls the agent back to them every turn, so long sessions hold their context. CX Codex +1 ★ 28,179repo stars planning-with-files planning-with-files saves agent task plans, research notes, and execution logs directly into project markdown files. Useful for multi-step tasks requiring 5 or more tool calls. CX Codex +1 ★ 28,179repo stars planning-with-files planning-with-files — a skill for Claude Code and Codex that writes the task plan, research findings, and session log to disk as Markdown files. On the next run the agent reads those files and picks up from the last incomplete phase. CX Codex +1 ★ 28,179repo stars

Project sponsors

Companies that keep this analytics open