Tips & tricks
The big picture: A handful of Claude Code mechanics worth knowing on purpose — permission modes, Plan mode — plus a CI trap (gates that read the GitLab issue tracker) and vetted links for going deeper than this site can.
Why it matters: These are the controls you’ll touch dozens of times a day. Knowing them well is the difference between babysitting a session and supervising one.
Toggling permission modes
Section titled “Toggling permission modes”Shift+Tab is identical on macOS and Windows/Linux — there’s no platform-specific
bind — but it cycles permission modes rather than toggling a single switch: Manual → Accept Edits → Plan → Auto → back to Manual. Auto sits last in the cycle, so
reaching it from Manual takes three presses, not one. (On a Pro, Max, or Team plan, a
new terminal session already starts in auto mode as of August 2026 — check
permissions.defaultMode in .claude/settings.json if a session isn’t starting where
you expect.) That’s also why the day-in-the-life setup passes
claude --permission-mode auto at startup rather than relying on the toggle: one flag
beats three keystrokes per new worktree terminal, and it’s the only way in on plans —
Enterprise, API-key accounts — whose built-in default is still Manual.
This is worth reaching for, not just a convenience: Anthropic’s own numbers are why.
Their classifier caught more dangerous actions than developers did approving prompts by
hand, held up under third-party red-teaming, and cut serious unintended harm from 6.3%
of manually-approved sessions to 2.4% of auto-mode sessions at production severity
(Auto mode is now the default,
Running auto mode in production).
Internally it’s the same shift this template’s worktree setup is built around — less
turn-by-turn approval, more monitoring: max consecutive tool calls per session rose 116%
and human turns per transcript fell 33% in one internal study
(How AI is transforming work at Anthropic),
and session length before stopping nearly doubled in three months in another
(Measuring AI agent autonomy in practice).
If the classifier blocks something routine over and over, that’s usually missing context
about your infrastructure, not a wrong call — /feedback reports it, and an admin can
add trusted repos/hosts via autoMode.environment.
Plan mode
Section titled “Plan mode”Enter it with Shift+Tab or by prefixing a single prompt with /plan. Claude reads and
explores but won’t edit until you approve. When the plan is ready:
- “Yes, and use auto mode” approves it and goes straight into auto-mode execution (see above) — the fastest path from design gate to implementation.
Ctrl+Gopens the proposed plan in your default text editor so you can rewrite it by hand before Claude proceeds, rather than only approving or asking for changes in-chat.
This is the mechanism behind the “plan before code” row in the
best-practices table, and
behind the architect → ux-design gates in the fast-path table in CLAUDE.md —
those agents produce the plan; Plan mode is how you review it before anything gets
edited.
CI gates that read the issue tracker
Section titled “CI gates that read the issue tracker”Any gate that looks up issue state over the GitLab API (an MR-description follow-up check, a known-issues freshness check, a suppression-marker check) can fail in ways that look like something else. The same trap has hit three repos:
- trueppm/trueppm#4452 —
docs:known-issues-freshnessturnedmainred with HTTP 429, and each retry failed on a different set of issues. That is a rate budget running out, not bad content. - macrodream/blueprint#123 —
check-mr-followups.shhad the identical shape (fixed in !96). - visiban/visiban#1694 —
suppressions-checkwas silently blind. It sent aJOB-TOKENheader, which this endpoint rejects with 401, and treated the failure as “unknown, non-blocking”. It stayed green only because no marker existed yet.
The rules that prevent all three:
- Anonymous calls share one per-IP budget. Every job on a self-hosted runner leaves through one egress IP, and GitLab.com’s anonymous limit is its lowest tier. A gate that makes one GET per reference exhausts it.
- Batch, do not loop.
GET /projects/:id/issues?iids[]=1&iids[]=2(and so on, up to 100 per page) resolves every reference in one call. Use the shared readerscripts/lib/gitlab-issues.sh(gitlab_issue_states), which does this and prints oneiid<TAB>state<TAB>titleline per issue. Never write a per-issuecurlloop in a new gate. - Retry 429, honoring
Retry-After, bounded, then decide the policy out loud. The helper retries 429, 5xx and network errors up toGITLAB_ISSUES_MAX_ATTEMPTStimes (default 5), waitsRetry-Afterwhen present (otherwise exponential backoff), caps each wait at 60 seconds, then returns status 2. The caller picks the policy:check-mr-followups.shfails closed, withMR_FOLLOWUPS_ALLOW_UNRESOLVED=1as an explicit escape hatch. It admits a missing issue as well as a confidential one, because GitLab answers both the same way; it is meant for a single job run, not a standing CI variable. Whichever you choose, make “could not read the tracker” distinguishable from a misconfiguration and from a real finding. - Never send
JOB-TOKENto the Issues API. It is not a job-token endpoint, and anyJOB-TOKENheader turns a public project’s anonymous 200 into a 401. A fail-open gate turns that into permanent, silent blindness. - Use
ISSUES_API_TOKENfor the authenticated limit. It is the shared fallback for per-script variables such asMR_FOLLOWUPS_TOKEN. On GitLab.com, project and group access tokens are a paid-tier feature (the Free plan answers HTTP 400 “User does not have permission to create project access token”), so on Free it is usually a personalread_apitoken, which reads everything that user can see, including private sibling repos. Scope it accordingly and store it masked. Protected plus masked givesmainand scheduled pipelines the token while MR pipelines stay anonymous, which batching plus retry make sufficient for a public tracker. On a private tracker an anonymous lookup returns 401, so the token must not be protected, or MR-pipeline gates cannot read issues at all. The comments in.gitlab-ci.ymlandscripts/lib/gitlab-issues.shgive the same advice. If a lookup with the token gets a 401, the helper warns and retries anonymously, so an expired token degrades instead of turning the pipeline red. - A confidential issue looks missing. GitLab leaves it out of the list response (and
answers 404 on the single read) for an anonymous caller and for a token whose user is
below Reporter on the project, exactly as for an issue that does not exist. A gate
cannot tell the two apart, so it must not report the reference as untracked work:
check-mr-followups.shreports it as UNRESOLVED (exit 2). If follow-ups may be confidential, give the token to a Reporter-or-higher member (macrodream/blueprint#337). - Know the tell. A fail-closed tracker gate that fails on different issues each
retry is rate-limited, not wrong. A fail-open one that never warns may be getting a
401 on every call. Probe it by comparing a request sent with
-H "JOB-TOKEN: x"against the same request with no header, both aimed at…/issues/1. - Keep pipes out of the check. Under
set -o pipefail,… | headand… | grep -qcan end the producer with SIGPIPE and report a present match as missing. Capture the output into a variable first, then test it.
Learning resources
Section titled “Learning resources”Nobody should have to reverse-engineer this template’s conventions from the diff of a generated migration. These are the primary sources this site’s own conventions are drawn from.
Claude Code
| Resource | What it’s for |
|---|---|
| Claude Academy — Claude Code 101, Claude Code in Action | Anthropic’s own free, self-paced courses (Skilljar-hosted). 101 covers the agentic loop, context, and the explore → plan → code → commit workflow; in Action covers steering long hands-off sessions, hooks, headless mode, and packaging skills for a team — the material this template’s harness assumes |
| Full course catalog | The broader Anthropic Academy catalog beyond Claude Code — AI Fluency, MCP, API fundamentals, cloud-platform tracks |
| Claude Code docs | Reference for everything this site only summarizes: permission modes, hooks, skills, subagents, settings |
| Claude Code best practices | Anthropic’s own engineering write-up — the source for most of the best-practices table |
| Claude Cookbooks | Copy-able recipes for building with Claude beyond Claude Code itself (tool use, RAG, evals, prompt caching) — useful once a project’s own product also calls the API |
Git & GitLab — this template assumes comfort with both; neither is optional once
you’re past /kickoff
| Resource | What it’s for |
|---|---|
| Pro Git | The free, official Git book — start here for branching, merging, and rebasing if scripts/wt’s worktree model feels unfamiliar |
| git-scm.com/docs and gittutorial | Git’s own command reference and shortest official tutorial |
| Learn Git — GitLab Docs | GitLab’s guided tutorials (first commit, rebase, rewriting commit messages, remotes) using the same glab-flavored workflow this template’s Git conventions assume |