Codiff
Apps & AutomationcodiffCodiff is an Agent Skill for apps & automation published in the nkzw-tech/codiff repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Open Codiff for a narrative code walkthrough, a blocking plan handoff, or a shared walkthrough URL. Use when the user writes "$codiff", "/codiff", "$codiff plan", "$codiff share", "show me codiff", "open Codiff", or asks to review a change or edit a plan in Codiff.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/nkzw-tech/codiff/blob/HEAD/opencode/skills/codiff/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/codiff, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Codiff
Use Codiff either to review a narrative walkthrough of a code change or to hand a Markdown plan to the user for visual editing before execution.
You write the JSON yourself because you already hold the conversation that produced the change. Codiff owns the format and authoring guidance, so this skill only handles the handoff.
Choose The Mode
- Use plan share mode for
$codiff plan share, or when a share request is clearly about the proposed plan in the current discussion. - Use walkthrough share mode when the request includes
share,upload,link,URL,web, or browser wording and is about code changes. An underspecified$codiff sharedefaults to a walkthrough. - Use plan mode for
$codiff planor when the user explicitly asks to edit or approve a plan in Codiff before execution. - Use desktop mode for plain
$codiff,/codiff, "open Codiff", or "show me Codiff". - In share mode, only pass
--openwhen the user explicitly asks to open the resulting share in a browser. Otherwise return the URL without opening it.
Plan Mode
-
Write the complete proposed plan to a Markdown file. Use a unique temporary file outside the repository unless the user named a canonical plan file.
-
Make the intended next action explicit in the document. The user should be able to edit, remove, or reorder any part of the plan.
-
Open the blocking handoff:
node scripts/open-codiff.mjs --plan /tmp/codiff-plan-<id>.md -
Wait for Codiff to return.
status: "done"means the user clicked Done.status: "closed"means the user closed the window after Codiff flushed the file and comments. A canceled handoff means the app could not complete the handoff and must not be treated as approval. -
Read the
CODIFF_PLAN_RESULTJSON emitted when Codiff closes. Re-read the entire Markdown file and process every thread inreview.threadswhosestatusis"open". Treat edits, additions, removals, reordered steps, and open comments as user direction. Use quoted anchor context for detached comments. Resolved comments are retained history and must not be processed again. -
After successfully applying one or more open comments, acknowledge only the handled thread IDs using the exact
reviewPathfromCODIFF_PLAN_RESULT:node scripts/open-codiff.mjs --resolve-plan-comments "<reviewPath>" <thread-id>...Do not resolve comments that were ambiguous, deferred, or not applied.
-
For
status: "done", execute the edited plan when the next action is clear. Forstatus: "closed", continue only whendocumentChangedis true or unresolved comments contain user direction; otherwise treat the close as cancellation. If the feedback is materially ambiguous, ask one focused question before changing code.
The edited Markdown file is the feedback. Do not require comments, annotations, or a separate approval document.
Plan Share Mode
-
Write the complete plan to a Markdown file, using the same authoring rules as plan mode.
-
Upload it without opening a blocking desktop handoff:
node scripts/open-codiff.mjs --plan /tmp/codiff-plan-<id>.md --share -
Add
--openonly when the user explicitly asks to open the shared plan in a browser. -
Return only the
/p/…URL printed by the command.
Walkthrough Workflow
-
Get the current guidance from Codiff. It explains the data model and prints the JSON schema:
node scripts/open-codiff.mjs --guide -
Pick the change. Default to the staged diff (
git diff --staged). If the user named a target such as a commit,HEAD, a PR/MR, a range, or a path, use that. If nothing is staged, fall back to the working tree (git diff) and say so. -
Author the JSON per the guide and write it to a unique temporary file outside the repository, such as
$TMPDIR/codiff-walkthrough-<id>.json. -
Complete the selected handoff.
Desktop mode:
node scripts/open-codiff.mjs --file /tmp/codiff-walkthrough-<id>.json /path/to/repositoryShare mode:
node scripts/open-codiff.mjs --share --file /tmp/codiff-walkthrough-<id>.json /path/to/repositoryShare and open in the default browser:
node scripts/open-codiff.mjs --share --open --file /tmp/codiff-walkthrough-<id>.json /path/to/repositoryForward an explicit target after the flags:
node scripts/open-codiff.mjs --share --file /tmp/codiff-walkthrough-<id>.json HEAD /path/to/repository node scripts/open-codiff.mjs --share --file /tmp/codiff-walkthrough-<id>.json mr 123 /path/to/repositoryThe share command prints the final walkthrough URL to stdout. When the cached Cloudflare Access token is missing or unusable, Codiff automatically opens the system browser for authentication and resumes after sign-in. This authentication browser is independent of
--open, which only controls whether the completed walkthrough is opened.Agent integration: Desktop launches link the most recent OpenCode session for the current project and run Codiff with the OpenCode backend. The launcher's
--sharepath retains OpenCode as the authoring agent without attaching the conversation transcript. Codiff's managed/codiffcommand can use the OpenCode model selected in Codiff; direct$codiffskill mentions continue with the current session model.Codiff validates and repairs the document against the live diff, so anchors that drift are pinned to a real section rather than dropped.
Emit walkthrough JSON only into the temporary file. In desktop walkthrough mode, do not summarize the conversation back to the user. In walkthrough share mode, respond with the URL printed by the command. In plan share mode, respond with the shared plan URL. In plan mode, continue from the edited Markdown after the blocking handoff returns.