Use local mode
By default every repo-facing subcommand (review, fix, rebase, address, implement, propose, audit, gap-analysis, review-prepared, elaborate) performs a fresh gh repo clone into a temp directory and deletes it on exit. The --local flag makes the command operate on the current working directory instead — no clone, and the checkout is left in place when the command exits.
This unlocks three workflows the temp-dir clone blocks:
- CI:
actions/checkoutalready populates the runner workspace, so a second clone of the same repo doubles the cold-start time and network cost.--localreuses the existing checkout. See Local mode in CI. - Local-first iteration: review or fix unpushed commits and experimental branches without pushing them first.
- Post-run inspection: after
fixorimplementfinishes, the working tree it operated on is still there tocdinto and inspect — it is neverrm-ed.
Semantics
- Reference inference. The PR/repo reference may be omitted for the repo-facing commands:
review/fix/rebase/addressinfer the PR from the current branch (viagh pr view);propose/audit/gap-analysis/review-preparedinfer owner/repo from theoriginremote.elaborateandimplementstill require their issue reference (you must name the issue) — only the repository checkout is taken locally. When a reference is given explicitly, its owner/repo must match the cwd'sorigin, otherwise the run aborts. - Branch left on. For
review/fix/rebase/addressthe working tree is switched to the PR head viagh pr checkout(no restore afterwards). The runner logsworking tree left on PR branchso you know where you landed.rebasethen rewrites that branch in place; pass--pushto publish it with--force-with-lease. - Dirty-tree gate. If the working tree has uncommitted changes,
--localasks for confirmation before doing anything. With--forceit proceeds and logs a warning instead. In a non-interactive context (stdin is not a TTY, e.g. CI) a dirty tree aborts with an actionable error suggesting--force— the tool never silently stashes or discards your changes. - Never deletes your tree. The cleanup step that removes a temp-dir clone is a no-op in local mode, so there is no code path that can
rm -rfyour working directory. fixloop. Each fix iteration fast-forwards the existing checkout withgit pull --ff-onlyinstead of re-cloning, which is materially cheaper and produces the same state for the next Claude session.fixcommit strategy. The fix is folded into the branch's existing commits by default — in both temp-dir and--localruns — instead of being appended as a fresh "Fix failing CI checks" commit: each change is staged against the commit that introduced the code it repairs (git commit --fixup=<sha>), all fixups are squashed in withgit rebase --autosquashbounded toorigin/<base>..HEAD, and the rewritten branch is published withgit push --force-with-lease. A new standalone commit is created only when a change belongs to no existing commit on the branch.--localtherefore changes only where the fix runs (your checkout vs. a temp-dir clone), not how it is committed. Pass--no-fixupto opt out: the fix is then appended as a single on-top follow-up commit and pushed without force. Force-pushing only ever uses--force-with-leaseand never touches commits that already exist on the base branch.
bash
# Review the PR for the current branch, using this checkout
planwerk-agent --local
# Audit the repo whose origin is this checkout (no clone)
planwerk-agent audit --local
# Fix the current branch's PR, proceeding even if the tree is dirty
planwerk-agent fix --local --force--local does not change cache behavior, gh authentication, or the --patterns flag. It also does not (yet) accept an arbitrary directory other than the current one.