Claude Code User Configuration

Reusable agents, skills, standards, rules, hooks, and mods for Claude Code. Drop this into your ~/.claude directory to get an opinionated, productivity-focused setup — from a single edit up to a full Linear-driven, issue-to-merge workflow.

Not an engineer? Linear for stakeholders explains how the agents read your Linear board and how to influence what they work on next — labels, priority, cycles, and how to unblock a parked issue.

Want to set up your own project? Project setup takes a fresh Mac from nothing to a working setup — your GitHub repository, your Linear board, and this toolkit — in seven steps, most of which Claude does for you.

Why

This started as a fix for one problem and grew into an opinionated operating system for agentic development.

The original problem — context rot. LLMs degrade as their context fills with too much information. The fix is agent delegation: specialized agents (developer, debugger, reviewer, researcher) each get their own clean context while you stay the main thread, orchestrating from above. Each agent reports back a tight summary, keeping both the top-level and the agent contexts small and focused. Every agent pins its own model and effort, and effort is the main cost lever — see Agents. For a deeper overview of this pattern, read ClaudeLog: You Are the Main Thread.

What it became. On top of that foundation, this repo is now a complete, mostly self-maintaining toolkit:

• A Linear-native issue lifecycle — plan → start → review → finish → next — driven by slash-command skills that assign issues, cut branches, run an adversarial review-and-fix loop, then mark work Ready For Release.
• Worktree parallelism so multiple issues (and multiple concurrent Claude sessions) run in isolation, with background launchd daemons that reap finished worktrees and drain deferred merges on their own.
• Safety rails and quality gates — hooks that block destructive git commands and the shell idioms that fail silently under zsh, and a pnpm check gate (lint, types, tests) before every commit.
• Codified standards and path-scoped rules so every agent shares the same conventions for git, commenting, problem-solving, and language-specific style.

How we use it below ties these together end to end.

How we use it

Top-down, in the order the work actually flows: research the idea, turn it into certified Linear issues, then ship the backlog with a fleet. The hands-on tiers below that — targeted /auto, /full, /start//finish — are the same machinery driven one step at a time, for when a single issue needs your judgment mid-flight.

1. Research & plan

Step	Command	Notes
Research	Use the research-lead agent to research foo bar baz; write the analysis to doc/analysis-foo.md	Lands an analysis doc you can review
Plan	Read @doc/analysis-foo.md and create an implementation plan as doc/plan-foo.md	Use plan mode. Split into parallel workstreams only where they are independent

2. Seed & certify the backlog

Step	Command	Notes
Linear setup	Optionally set $LINEAR_TEAM (single key or comma list, e.g. PL,BF) to pin the team scope	Unset = /next and /spec search every team in the workspace
Create issues	/prd @doc/plan-foo.md	Review stages and accuracy before approving; approval creates the issues in Linear
Triage	/triage scan, then /triage apply	Revalidates the pool against the code as it stands now — cancels what no longer applies, closes what shipped, marks duplicates, narrows partial ships, certifies by research where the evidence clears the bar. scan runs unattended and read-only; apply is the interactive session that writes
Prioritize	Move stage 1 to "Planned", stage 2 to "Backlog"
Certify	/spec	Interviews you, rewrites the issue in the canonical spec shape, and adds the specified label — the certification gate /auto requires. Interactive only; no args surfaces the top uncertified issues, including the Triage inbox

3. Ship with a fleet

The primary shipping mode: N parallel autonomous sessions draining the certified backlog as background agents in claude agents, bookended by prep and retro.

Step	Command	Notes
Prep	/auto-prep	Certification honesty audit (the needs decision / solo / human gates), family consolidation, blocks edges only for prerequisites, same-method collisions and deliberate increments (file-level overlap is related), and a recommended session count — interactive; run it before every launch
Forecast	/fleet-forecast 12 hours	Optional dry run of the drain — projected pick order as waves, when Planned burns down into Backlog, what the horizon can't reach, and what is stranded behind blockers the fleet can never ship. Read-only; an estimate, never a plan
Launch	/fleet-launch 3 10 hours	Staggered background sessions. Count defaults to prep's persisted recommendation (an explicit count is your quota throttle); the duration winds the fleet down cleanly at the deadline. An epic:<ID> token — or the scope /epic-prep persisted — confines every session to one epic's graph (see Scoping a fleet to one epic)
Sequence	/fleet-sequence BF-1 BF-2 BF-3	The targeted, serialized sibling: an explicit issue list shipped strictly one at a time onto one integration branch — each in its own background session, forked from its predecessor's merged code — with one PR onto the launch branch when the list completes (merge ships straight into the launch branch instead). The runner for solo work and for big issues that must land in order; never mid-fleet
Watch	/fleet-status	One screen, any time, read-only: time remaining, per-session shipped/failed ledgers with liveness, in-flight issues, merges cross-checked against git, remaining runway
End early	/fleet-stop	Rationing quota or done for the day — ends the timer; in-flight issues finish; nothing is killed
Post-mortem	/fleet-retro	Where the capacity went, what the run filed, what to fix before the next launch — its findings feed the next /auto-prep

Top-ups compose (/fleet-launch 2 <remaining> adds two sessions) — but every launch resets the shared deadline, so re-pass the remaining duration. What keeps N sessions honest is the label contract (standards/issue-spec.md) plus worktree isolation and the serialized merge — see Parallel safety.

Scoping a fleet to one epic

One epic, worked to completion by a fleet that sees nothing else. The same machinery as the table above with one scope threaded through it, and a different release shape: the fleet merges into an integration branch as it goes, and the epic ships as one PR from that branch onto the branch it forked from.

Step	Command	Notes
Prep	/epic-prep BF-1826	/auto-prep scoped to the epic's graph, plus what a team prep lacks: /spec over the uncertified members blockers-first, a boundary review (outside dependents and related partners — include by re-parenting, default leave out), promotion of the whole graph to Planned, the epic/<id> branch forked from the checkout's branch (or start.wt-source-branch), and a hard gate that every already-resolved member's code is on it — a Ready-for-Release member whose PR sits open against another branch stops the prep until it is merged in. Persists the scope, the member snapshot, the branch, and a lane count with the recommendation
Launch	/fleet-launch — bare, or /fleet-launch 2 8h epic:BF-1826	Every session runs /loop /auto epic:BF-1826. Each session's /auto points a per-issue fork key at the integration branch before every dispatch, so each fleet /start wt forks from it and each /finish merge advances it ref-only; the main checkout is never moved — keep working on it while the fleet runs
Watch	/fleet-status	Adds the scope and branch, and a member burn-down: shipped · remaining (in flight) · added since prep. Membership is recomputed at every pick, so a child filed mid-run joins the pool and shows up here rather than silently widening the work
Close	automatic	mark-ready-for-release.sh walks up from every released child: an epic whose children are all terminal moves to Ready for Release itself, recursively. Then ~/.claude/scripts/epic-pr.sh <id> pushes epic/<id> by ref and opens the epic's PR — resolving the branch, base and landed roster from what prep and launch recorded — and /pr-update <PR#> writes its description

Membership is decided by scripts/epic-graph.sh: the epic, its transitive descendants, and the transitive blockers of any member — non-terminal only, cross-team included. Dependents are not members (the epic enables them; it does not need them), and neither are related partners; both are the boundary the prep reviews. The same scope token drives the hand tools — /next epic:<ID>, fleet-forecast.py --root, fleet-blockers.sh --root — and every one of them fails closed on an issue that is not an epic. Expect one or two lanes: members of one epic share its files and specs by construction, so they collide more than a team pool, and the related de-rank plus the merge gate carry what the count leaves.

Stepping down: one loop, one issue, one command

Every tier runs the same pipeline (/start → /quality-review → /finish); each step down trades autonomy for control.

Tier	Command	You decide	It decides
One autonomous session	/loop /auto	when to stop	everything else
Targeted auto	/auto BF-123	the issue	plan, review, merge — fully unattended
End-to-end, attended	/full wt BF-123	the issue, plan approval, the deferred-items call	implementation and review flow
Two-command loop	/start wt BF-123 … /finish	everything above, plus when to finish	review still runs inside /start
Human in a worktree	/start interactive BF-123	all of it — claims the issue, sets up the isolated worktree, hands off	nothing

Parallel safety

The wt token is what makes fan-out safe — it is how every fleet session runs, and the same mechanics protect a hand-driven fan-out:

agent 1:  /full wt PL-1
agent 2:  /full wt PL-2
agent 3:  /full wt PL-3

Each runs end to end independently, and the machinery keeps them from colliding:

• Isolation by worktree. /start wt checks out the issue's branch in its own git worktree under <repo>/.claude/worktrees/<issue>, so every agent gets a private working tree and branch — edits, installs, and checkpoints never step on each other or on your main checkout.
• Serialized merge. When each /finish lands, it advances the shared source branch under a per-repo lock (scripts/with-repo-lock.py): the worktree branch is first brought up to source's tip inside its own worktree (any conflicts resolved there, never in the main checkout), then source moves by a clean git merge --ff-only or an atomic git update-ref. Concurrent finishes block briefly and merge in turn, so source is only ever advanced cleanly.
• Deferred, never forced. A merge that can't advance right now — e.g. the main checkout is sitting on the shared branch with another session's WIP — is enqueued rather than failed: it leaves the worktree intact and a launchd drainer retries every ~15 min until it lands. Inspect with /merge-queue; conflicts are never resolved unattended.
• Self-cleanup. Finished worktrees are reclaimed by the hourly reaper — check with /reap-worktrees. Aged tmp/ scratch is reclaimed by a daily reaper that keeps the named handoff files other skills still read — check with /reap-tmp.
• Human alongside. /start interactive PL-4 claims an issue and sets up its worktree (opened in its own VS Code window), then hands off without planning or implementing — so you can work by hand in the same isolation while background agents keep shipping.

For heavy fan-out, keep your main checkout parked on a quiet branch (not the shared integration branch) so every merge advances source by a ref-only update and the queue rarely engages. The full merge protocol lives in standards/git-worktrees.md.

Standalone skills

Reach for these as needed — between loop steps or on their own:

Skill	When
/checkpoint	Mid-task — commits WIP and posts a progress update to Linear
/quality-review	On demand — adversarial review + triage/fix loop until convergence (also auto-runs inside /start)
/next	Starting a day or week — suggests the best next issue to pick up
/sentry	Working a project's Sentry queue — ranks unresolved production issues, then files, archives, resolves, or merges each one, and keeps the sentry-labeled Linear issues placed to match
/update	Start of day, and first thing to try when a tool is missing or a skill behaves like an older version — pulls the latest project code and ~/.claude, then re-runs the setup script

Autonomous (/auto)

/auto is the engine every fleet session runs — the pick-and-ship loop with the human taken out, or in targeted mode out of everything but the pick — and /loop is what keeps it running unattended. /fleet-launch dispatches N of these as background agents; this section is the single-session mechanics reference.

• /auto ships exactly one Linear issue per invocation, end to end: finish any in-flight work, pick the best unblocked issue via /next specified (certified issues only), ship it via /full auto wt, record the outcome. Worktree mode is always on (so successive issues chain without stacking branches), and every underlying auto default chooses abort/preserve over guess — the worst acceptable outcome is "nothing happened and Linear says why," never "something wrong shipped." Invoking /auto is the run-scoped grant for the commits and pushes it makes (see standards/git.md).
• /auto BF-123 is targeted mode — same run, your pick. It skips the /next pick and ships exactly that issue: still certified-only (the issue must carry the specified label — /spec it first if not, or drop to /full wt BF-123 for an interactive run), still always-worktree, still the full unattended gauntlet (plan composed and posted to Linear with no approval pause, adversarial review, finish/merge, a Linear comment on failure). One-shot by nature — run it directly, not under /loop. This is the middle ground between driving /full wt by hand and letting the loop choose.
• /loop /auto is the way you actually run it. /loop supplies the recurrence — its wakeup machinery re-invokes /auto for the next issue — while each /auto call stays a single, self-contained iteration. (Deliberately: in-prose "keep going" scaffolding is the documented failure mode of autonomous macros, so /auto leans on /loop's reliable recurrence instead of inventing its own.) Iterations run back-to-back: /auto schedules its next wakeup at the 60s minimum, because the backlog is the work queue and there is nothing external to wait on — /loop's 20–30 minute idle-tick default is for polling loops and would otherwise idle away hours between ships.

Launch it with --model opus[1m] --effort xhigh. Not opusplan — that means "Opus in plan mode, Sonnet otherwise", and /start auto skips plan mode entirely, so an opusplan run executes end-to-end on Sonnet. [1m] because context accumulates within an iteration.

Point it at a seeded, certified (via /prd or /spec) backlog and walk away. It works the queue one issue at a time and ends itself — no runaway loop:

• NO-CANDIDATES — the backlog has no more certified, workable issues. Certify more via /spec (or seed via /prd), delete the run's tmp/auto-state-<runKey>.json, and re-invoke.
• AUTO-HALTED — the circuit breaker tripped (two consecutive failures, likely systemic) or an environment halt (e.g. a dirty tree left by an issue that already failed to finish — dirt it can't attribute does not halt it). Each failing issue gets a Linear comment explaining why before the loop stops.

The loop-boundary mod compacts the main conversation at every /loop /auto iteration boundary, so each iteration starts near the session's floor; growth inside an iteration is left to the harness's own summarization, and the loop itself never invokes /compact or /clear. The run's actual memory lives in tmp/auto-state-<runKey>.json (shipped / skipped / failed lists + the failure counter, keyed by the session's own id) and Linear, not the conversation — so the run survives compaction, and the terminal halt stays sticky even under a fixed-interval /loop 15m /auto. A human starts a fresh run by deleting that file — or simply by starting a new session, whose fresh id names a fresh file.

Parallel and stoppable. Several /loop /auto sessions can drain the same repo concurrently: Linear claims keep their picks disjoint, every worktree is stamped with its owning session's identity (session id + harness PID — id-first, so claude agents fleets that share one root process still resolve correctly) so a live sibling's in-flight issue is never mistaken for an orphaned dead run (only a provably dead owner gets resumed), run state is per-session, and the per-repo lock serializes every git mutation. Stopping is scoped, too — telling a session "don't run another loop" ends the recurrence, while the in-flight issue still completes normally; parking work mid-issue takes explicit words.

   /loop /auto  ──  the autonomous driver: re-invokes /auto each iteration
        │
        ▼
  ┌───────────────────────  one iteration  =  one issue  ───────────────────────┐
  │                                                                             │
  │  0  re-anchor + read  tmp/auto-state-<runKey>.json (cross-iteration memory) │
  │  1  preflight ......... finish any in-flight work / resume orphaned wt      │
  │  2  /next specified ... rank certified, unblocked candidates, take top one  │
  │  3  /full auto wt <ISSUE>                                                   │
  │        ├─ /start auto ........... branch · plan → Linear · implement        │
  │        ├─ /quality-review auto .. adversarial review + fix loop             │
  │        └─ /finish auto .......... commit · push · merge · Ready For Release │
  │  4  record outcome → tmp/auto-state-<runKey>.json,  emit one lifecycle tag  │
  │                                                                             │
  └──────────────────────────────────────┬──────────────────────────────────────┘
                                          │
              AUTO-CONTINUE  ─────────────┤  shipped / skipped / recorded-failure
                                          ▼   → /loop wakes the next iteration
              ─────────────────────────────────────────────────────────────────
              NO-CANDIDATES  (backlog drained of certified issues)  ─┐
              AUTO-HALTED    (2 consecutive fails / env) ─┴─►  loop stops, awaits a human

/auto accepts two optional tokens: pr opens a PR per issue instead of merging (use only when the queued issues are independent, since the source branch won't advance until PRs land), and a team scope (BF, or a comma list PL,BF) restricts the run to those teams' certified backlogs.

What's Included

Agents

Specialized personas the main thread delegates to — directly, or through skills like /start and /quality-review. Each file pins its own model and effort.

• architect — solution design, ADRs, technical recommendations; /quality-review's escalation path
• developer — code implementation from specifications
• debugger — root cause analysis through systematic evidence gathering
• quality-reviewer — adversarial review: edge cases, contract violations, security
• quality-verifier — verification pass over a fix delta, and the simple tier's scoped review
• research-lead — multi-perspective research and synthesis
• technical-writer — concise documentation for completed features

The spawn-policy mod rewrites developer spawns to Sonnet and forces synchronous dispatch of quality-reviewer, quality-verifier and developer once /auto has run in the session or the spawn's permission mode is auto.

Skills

The harness lists every installed skill with its description at the start of each session; that listing is the catalog. /skill-doctor shows what each skill costs in context and how often it is used.

Standards

Universal rules governing agent behavior. standards/README.md is the index and owns the per-standard summaries.

Rules

Path-scoped conventions in rules/, injected when Claude works on a file matching a rule's paths: frontmatter. CLAUDE.md § Path-Specific Rules lists them.

Hooks

Registered in settings.json; each has a sibling *.test.sh that pnpm test runs.

• git-permissions (before Bash) — blocks destructive git operations (reset --hard/--mixed, restore/checkout <file>, clean -f, --force).
• scratch-path-guard (before Bash, Write and Edit) — denies scratch writes to bare root paths and system /tmp (session scratchpads exempt), steering them to project-relative tmp/.
• zsh-trap-guard (before Bash) — refuses the bash-only idioms that fail silently under the zsh tool shell; standards/shell.md has the mechanics.
• no-blind-sleep (before Bash) — refuses a sleep wait that cannot end early; marker polls with an exit condition still run.
• linear-create-state-guard (before Bash) — refuses a linear-cli issues create with no --state, which would land in Triage where /next and /auto never look.
• auto-deadline-gate (before Bash) — refuses a new /auto pick once the fleet deadline has passed.
• finish-flow-guard (before Bash) — refuses PR mode in an unattended run whose invocation carried no pr token.
• full-continue (on stop) — re-dispatches /finish when /full stalls at a passing review verdict or after READY-FOR-FINISH.
• auto-heartbeat (on stop) — blocks a self-paced /loop /auto turn that ended without arming the next wakeup.
• auto-rewake (on stop and stop-failure, asyncRewake) — wakes a /loop /auto session whose armed wakeup never fired or whose turn a transient API error killed.

No hook lints on edit: markdownlint (and Biome, in projects) run through pnpm check, the gate before every commit.

Mods

Hooks-only plugins under mods/ that act on the harness itself: per-phase effort, the spawn policy above, compaction at each /loop /auto iteration boundary, and rate-limit readings for the fleet gates. update.sh installs them user-wide; mods/README.md owns the list, the kill switches, and the checks to run before committing one.

Background daemons

Local launchd agents installed by update.sh (macOS only) that keep the worktree and merge machinery tidy without any manual step.

Daemon	Cadence	What It Does
merge-queue-drain	Every 15 min	Lands /finish merges that were deferred — e.g. main was busy with another session's WIP
worktree-reap	Hourly	Reclaims completed or abandoned /start wt worktrees
tmp-reap	Daily	Ages tmp/ scratch out by name-based lane, never the handoff files other skills still read (/reap-tmp)
auto-stall-watch	Every 10 min	Surfaces a /loop /auto background session gone silent mid-iteration — the backstop for the auto-rewake hook when that hook failed or never ran
cswap-auto	Continuous, opt-in	Keeps claude-swap's auto-switch engine running on a machine that rotates accounts. Installed by scripts/cswap-setup.sh, not update.sh; see Multi-account rotation

Setup

1. Install Claude Code

curl -fsSL https://claude.ai/install.sh | bash

2. Clone into your user directory

Assuming you already have a ~/.claude directory from using Claude Code, add this repo:

cd ~/.claude
git init
git remote add origin https://github.com/alienfast/claude.git
git fetch
git checkout -b main origin/main
git pull

Note: This supplements your user directory with reusable configurations — it does not overwrite personal settings or data. Always check before committing to ensure no local user data is included, and adjust .gitignore accordingly.

3. Install skills and tools

Prerequisites: Homebrew, Node, pnpm, git, and Claude Code must already be installed — the script bootstraps everything else and fails fast if Homebrew is missing.

~/.claude/update.sh

From then on, /update is the skill that does this — it pulls the latest project code and ~/.claude first, then runs the script.

If the ~/.claude checkout has drifted — it sits on a branch (a /keeper proposal, a PR checked out for review) or carries uncommitted edits — run this outside Claude Code (Git Bash on Windows, Terminal on macOS). It returns the checkout to the latest main without discarding anything (edits are committed on their branch, local-only main commits are kept under backup/main-<stamp>), runs update.sh, and proves the tooling works:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/alienfast/claude/main/scripts/sync-main.sh)"

It has to run outside a session because the git-permissions hook refuses branch switches inside one — deliberately, since another session may own the working tree. The bash -c form matters: piped into bash, the script is read from stdin as it runs, and the skills installer inside update.sh reads stdin and swallows the rest of it.

This installs:

• The TypeScript LSP plugin
• The mods, as user-wide plugins
• gh and jq via Homebrew (installed or upgraded), then runs gh auth login if you aren't already authenticated
• pnpm brought up to the version this repo pins (packageManager in package.json, the same pin the projects carry), through whichever installer owns it — Corepack, Homebrew, the standalone installer, or npm
• Vercel agent-browser and skill-creator
• Vercel React best practices and composition patterns
• npm-check-updates (ncu) as a pnpm global — required by the dependency-updater skill
• Linear CLI via cargo (the Linear skills already ship with this repo), authenticating it if needed
• launchd background daemons on macOS — the merge-queue drainer, the worktree and tmp/ reapers, and the stall watch
• Runs markdown linting

4. Configure MCP servers (optional)

See mcpServers.md for some available MCP server configurations. The current approach favors skills over MCP servers for context efficiency — most MCP servers have been removed in favor of CLI tools and skills.

Customization

Adding skills

Create a directory in skills/ with a SKILL.md containing YAML frontmatter. See skills/README.md for the full guide.

Adding standards

Add a markdown file to standards/ and index it in standards/README.md. Agents read a standard on demand when its domain comes up, so the index entry is how one gets found.

Adding rules

Add a markdown file to rules/ with a paths: glob in its frontmatter; the frontmatter alone decides where the rule is injected.

Scope the glob to where the rule's principle actually applies: use **/* (plus **/.* and **/.*/** to also cover dotfiles and dot-directories like .github/) when the rule is language-agnostic — e.g. comments — and reserve a curated extension list for genuinely language-specific rules. A curated list silently exempts every file type it omits, and the gap stays invisible until a violation slips through an unlisted type.

Multi-account rotation (optional)

For a machine that runs more than one Claude subscription. Nothing in this repo installs or requires it: a single-account user skips this section, and update.sh is unchanged for them.

The switcher is claude-swap (cswap), a third-party tool that swaps the Claude Code login in place, polls every account's 5-hour and 7-day windows, and moves the login before a limit is hit. It lives outside Claude Code because the switch has to: no mod hook can replace a credential, and CLAUDE_CONFIG_DIR is read at process start. What this repo adds is the policy, since cswap's defaults are wrong for us. Its default best strategy parks on the account with the most headroom, which is the quota with the longest to live, so weekly quota on the soon-to-reset accounts expires unused. cswap-setup.sh sets consume-first instead: drain the account whose weekly window resets soonest, move at 95% of the binding window, and return to it once its 5-hour window rolls over. The script's header explains why 95 and not higher, and which upstream issues would let the weekly line sit at 98.

To try it, from a terminal rather than a Claude session (the account logins need a TTY):

~/.claude/scripts/cswap-setup.sh

It installs cswap through uv where it is missing (the latest release; from then on update.sh upgrades it, only on a machine where it is installed), enrolls the current login, then loops: answer y, complete a claude auth login for the next account, and it is added, until you answer n. Never /logout between accounts; cswap backs the live login up before the next one replaces it. It then applies the policy, prints one dry-run tick so you can see the engine's decision, and loads a launchd agent that keeps cswap auto running. Every step is idempotent; re-run it with --threshold or --strategy to change the policy, and the engine restarts on the new values.

Day to day, in a session (skill):

/cswap            # same as /cswap quota
/cswap quota      # every account's 5-hour, weekly and Fable usage in one table, the age of each figure, and only the conditions that need action
/cswap log        # whether the engine is running, its last switches, and why it is holding right now
/cswap next       # the move it would make this minute, as a dry run
/cswap setup      # the setup command to run in a terminal, or re-apply --threshold / --strategy without enrolling

The rate-limits mod pins the active account and its 5-hour and weekly use under the prompt on a rotating machine, so a switch landing on a running session is visible. /auto's fleet headroom gate (fleet-headroom.sh) asks cswap before it parks a session: while another enrolled account is under the threshold with a fresh figure, the pick goes ahead and the engine moves the login when the active account fills; the gate parks only when no account has room or the engine is idle, and its line says which. From a terminal:

cswap list                            # every account's usage and reset times
cswap switch 2                        # move by hand; the engine never undoes a manual move
cswap auto --once --dry-run --json    # what the engine would do right now
tail -f ~/.claude/logs/cswap-auto.log # one JSON event per poll, switch, quarantine or error

update.sh refreshes the agent and upgrades cswap to the latest release only where the setup script installed it, restarting the engine onto the new code when the version moved, so run it with no fleet in flight; on any other machine it never installs cswap. The tool holds every enrolled account's refresh token and its 0.2x releases change the credential path often, so if a release breaks switching, uv tool install --reinstall 'claude-swap==<last good>' rolls it back until the next update.sh.

Known edges while this is a trial:

• The rate-limits mod records the active account's windows without naming the account; on a rotating machine, fleet-launch's readout is whichever account the last session ran on.
• cswap is a 0.2x release with an active issue list on its credential path. Its account backups live in the macOS Keychain; cswap export is plaintext by default.

To remove: launchctl bootout gui/$(id -u)/com.alienfast.cswap-auto, then uv tool uninstall claude-swap. The Keychain backups stay until cswap remove.

References

• Anthropic Cookbook: Patterns
• ClaudeLog: You Are the Main Thread
• Agent configuration inspiration: solatis/claude-config
• Claude Code Best Practices
• Sub-Agent Task Management