FAQ

Frequently asked questions

Do I copy this repository into my project? No. The per-machine install keeps the package in its own clone under your Claude config directory, and the per-repository install writes into your repository only what a project needs, in one commit.

Does it change my global Claude Code settings? Once, after a backup (settings.json.bak-<date>). It adds its hooks and statusline and turns the Task tools off, and only where you have set nothing yourself it adds longer bash timeouts, turns auto-compact and commit attribution off, and turns notifications and Remote Control on. It never touches model or modelSettings. Restoring the backup undoes all of it.

Does it commit or push for me? It commits: each coder change whose tests pass, and each task's log and summary, with one-line messages and no AI attribution. It never pushes. Pushing is always yours.

What if the install is interrupted? Run it again. Both installs are idempotent: a second run completes what is missing and writes nothing else. The settings merge checks that the merged file parses before writing it, and restores the backup if anything fails.

Is my code sent anywhere unusual? No. PA3 is local scripts around Claude Code. The ledger lives in ~/.claude/usage-ledger/ and reads Claude Code's transcripts in place; nothing is uploaded. The only network traffic PA3 adds is git fetches of its own clone (for updates and the public bench series) and a read of your plan's usage from Anthropic's usage endpoint, with the login Claude Code already holds.

Will it cope with a large, messy project? It was proven on three: a stock 2.0 repository (2,645 files), a 1.x-shaped one (58,115 files, 164 PhaseEnds) and an overlay one inside WSL (15,721 files and a 3.66 MB cookbook). Each migrated in one commit, in 5 to 78 seconds, and the proof was run twice. In daily work a size guard stops any agent from reading a big file whole: it gets an outline with line numbers and reads the range it needs, and long material goes to a retriever so the expert receives only the answer.

What does it cost, and where do I see it? Every request of every agent is priced in the ledger from the transcripts at API list prices and converted into the share of your five-hour and seven-day allowance it used. The statusline shows it for this session, this project and your account; pa_ledger.py report prints the detail.

Why does PA3 ask which day my plan renews? The month figures count weeks of allowance from the day your plan renews, and PA3 never guesses that day. It asks once per account (the Claude app shows the date under Settings → Billing); until you answer, the month figures show —. To change it later: python ~/.claude/pa3/pa_ledger.py accounts renewal <email> <day>.

What do "N% fewer tokens than vanilla" and "lasts Mx longer" mean, and why trust them? Over your current seven-day window, "paid" is your ledger cost and "saved" is the carry model's saving. "Fewer" is saved over paid plus saved; "lasts longer" is paid plus saved over paid. Everything beneath them is counted from the API's own usage figures; the one modeled step states its assumption and shows how the result moves with it; and the replay checks it from the other side. See the statusline and the savings.

Which models does it use, and how do I change them? Each agent's model and effort are pinned in its own file (How it works). Six follow your plan's preset; to move one, set a ladder override in .claude/pa.json. For any other agent, edit its model: line and mark its version: line as yours (3.10.1+u1); updates keep your edit.

Do I ever use /effort, /model or plan mode? No. Agents never switch their own model or effort, and the router does not use plan mode: the plan is a file you approve. If a request runs on a model other than the pinned one, the ledger records the fallback and the statusline's alert line shows it.

Can I talk to it in the middle of a phase? Yes. Type /discuss to open a thinking partner: it works through the question with you and, when you say proceed, hands its decisions back as plan edits. Type NOTE: for the running task, or type into a running expert's own view to steer it directly. And for anything that can wait, write a line in phase-ends/current/INBOX.md: the router reads it at its next step and routes it now, to the phase you name, or later.

What happens when a session dies? Nothing that matters is lost. The plan, every task's log and summary, and an expert's progress file are on disk and committed per task. Open claude again and the router picks up at the task that was running. An expert that fills its context writes its progress file and hands the task to a fresh expert on its own.

Why does an agent sometimes get a message that is just a dot? That is the warmer. While an agent waits on a helper, a background timer pings it with . just before its prompt cache would expire, so the cache is kept instead of rewritten; the agent replies with a dot and nothing else. Experts keep their cache for an hour, so an expert is pinged only when a wait passes 55 minutes, at most three times per wait. An agent on the 5-minute cache is pinged at 4:45, but only as many times as cost less than one rewrite of its cache, counting the router's relay; when a single ping would cost more, none is sent. A ping the router never relays is noticed, and the router is told to arm its relay. warmer: off in .claude/pa.json turns it off.

What is the line "PA3 repaired the usage ledger"? After an update, PA3 checks your usage ledger once for damage a fixed bug left behind and repairs it in the background: it copies the ledger to ~/.claude/usage-ledger/backups/ first, applies the fix, and records that it ran, so it never runs twice. The line at your next session start says what it changed and where the copy is; it is shown to you only, never to the agents. A repair it cannot be sure of is left alone, and doctor names the command to run instead.

How do I switch it off or remove it? PA_HOOKS_OFF=1 makes every hook return at once and PA_LEDGER_OFF=1 stops ledger writes, for as long as the variable is set. claude --agent plain opens a design session without the router. To remove it, see Install.

Two machines, or Windows and WSL? Install once per machine, and once per Claude config directory if you keep two accounts apart. Each machine keeps its own ledger; at install you can name another machine's ledger (WSL's, seen from Windows, for example) and reports combine the two.

Where do memories and transcripts go? Transcripts stay where Claude Code writes them and are only read in place; PA3 raises their retention to ten years so the ledger can always be rebuilt. Claude Code's memory folder for the project is linked into the repository (.claude-state/memory/), so it is versioned with the code. PA3's own agents never write memories: standing facts go to HOW_WE_WORK.md, rules to rules/, techniques to cookbook/.

Which Claude Code version and which plan do I need? The latest Claude Code, kept up to date, and any of Max 20x, Max 5x or Pro.