DEV Community: day

Claude Code can't use your Max plan's free API credit. OpenCode can.

day — Mon, 12 Oct 2026 12:13:17 +0000

TL;DR

Claude's Max and Team plans include a monthly API credit at no extra cost. Claude Code can't spend it, but OpenCode can, once you register an API key. The official pages don't mention third-party clients, but on my machine the credit went down when I used OpenCode.
The credit is $100 a month on Max 5x and $200 on Max 20x. Team gets a per-seat pool, capped at $500. It resets every month and doesn't roll over. Pro isn't eligible.
It isn't added automatically. You get it by linking a Console organization in claude.ai.
In OpenCode you register a Console API key. Anthropic doesn't allow signing in to OpenCode with a Pro/Max account.
The second half is a paste-ready prompt, plus the pitfalls, for moving your Claude Code setup (CLAUDE.md, subagents, skills, MCP, hooks) to OpenCode.

The whole thing in three steps:

# 1. In claude.ai, link a Console organization under Settings > Billing, then create an API key in the Console
# 2. Register the key in OpenCode (you paste it at the prompt)
opencode auth login anthropic --method key
# 3. Check that it works
opencode run --model anthropic/claude-haiku-5-5 "Reply with exactly one word: pong"

Tested on macOS 27.0.1, OpenCode v2.0.27 and Claude Code 2.1.296. The quotes from official pages and my own runs are both as of Oct 12, 2026.

Why I moved to OpenCode

On the night of Oct 11, 2026, in the last push on a hackathon project, Claude Code hit its weekly limit. I logged in again with a Console account, and this time it said Credit balance is too low. Since the next day, Oct 12, I've been on OpenCode v2.0.27 with an API key.

Monthly API credits for Max and Team plans are rolling out from Oct 7, 2026 (Platform release notes). Interactive Claude Code can't use them; the API can. This post covers how to connect OpenCode, and the pitfalls I hit moving my Claude Code setup to V2.

Connect OpenCode to the credit

What the credit covers

The table below is what the Help Center and the Platform docs say.

How you use it	Credit
Interactive Claude Code (terminal, IDE, desktop, web)	Not eligible
`claude -p` or the Agent SDK, run by you with an API key from the linked organization	Eligible
Claude API, Console Playground	Eligible
Bedrock, Vertex AI, Foundry	Not eligible
Third-party clients such as OpenCode (with a Console API key)	Not mentioned (it went down on my machine)

The monthly amount is $100 on Max 5x and $200 on Max 20x; Team gets a per-seat pool (capped at $500). It renews every month with no carry-over. A plan can link only one Console organization, and you can't change it yourself later (it goes through support).

Logging in to Claude Code with a Console account doesn't get you this credit either. The docs say that if an organization holds only this credit, you get Credit balance too low · Add funds: ….

1. Link a Console organization

Open Settings > Billing in claude.ai (Team owners: Organization settings > Billing).
Under API credits, click "Link organization" and pick an organization or create a new one.
Read the Supplemental Credit Terms and link.

On the plan side you need to be the subscriber (Max) or an Owner or Primary Owner (Team). On the Console side you need one of the Owner, Admin or Billing roles. A new subscription can link only after 7 days. If you're eligible but "API credits" doesn't show up, the rollout may not have reached you yet (the Help Center says it's rolling out over several days). Once linked, the Console's Settings > Billing shows the amount and expiry under Promotional credits. Pick the organization you actually work in.

2. Create an API key

In the Console's Settings → API keys, press Create key, choose a name and an expiry, and set Linked account to yourself. The key starts with sk-ant- and is shown only once, when you create it. Keys in the linked organization draw from the same balance, even across different workspaces.

3. Register it in OpenCode

curl -fsSL https://opencode.ai/v2/install | bash   # if you're on V1: opencode upgrade --major
opencode auth login anthropic --method key

Paste the key at the prompt (this needs an interactive terminal). In the TUI, use /connect and pick Anthropic. Each time you register a key, another saved account is added, and the newest one becomes active. If you already had a different key registered, check with opencode auth list and switch to the linked organization's key with opencode auth switch anthropic <label> (Providers).

Warning: Don't sign in to OpenCode with a Pro/Max subscription. Anthropic's legal page doesn't allow third-party developers to route users' requests through Free, Pro or Max plan credentials. OpenCode's own V1 docs say of using Pro/Max models in OpenCode: "Anthropic explicitly prohibits this". They also say the plugin for it was removed in 1.3.0. An old step that says to pick "Claude Pro/Max" is still on the same page, but it doesn't work.

Using a Console API key that you set up in your own development environment, on the other hand, is not restricted, according to the legal page. I couldn't find a sentence saying it works with any client, though.

Warning: Don't put ANTHROPIC_API_KEY in ~/.zshrc either. If you approve a key found in the environment, Claude Code runs on that key instead of your subscription. Interactive mode isn't eligible for this credit, so you can end up with Credit balance is too low. With claude -p, a key in the environment is always used, with no approval step (Authentication, error reference).

If you'd rather pass the key as an environment variable, you can set it for OpenCode's background server only (opencode service set env ANTHROPIC_API_KEY sk-ant-...). I don't use this.

4. Check that it works

$ opencode auth list
Anthropic  Anthropic                   stored

$ opencode run --model anthropic/claude-haiku-5-5 "Reply with exactly one word: pong"
> build · claude-haiku-5-5
pong

With opencode auth list --format json, you'll see "method": "key".

To see whether the credit is being used, look at Promotional credits under Settings > Billing in the Console and at the Cost page, before and after a request. On my machine, Promotional credits went down after I used OpenCode. Consumption through third-party clients isn't described officially, so it's worth confirming once on your own account. If it doesn't go down, first suspect that the key isn't from the linked organization. When the balance runs out, requests draw on any purchased credits or auto-reload you have; if there are none, API requests stop (your Claude plan isn't billed).

Move your Claude Code setup to OpenCode V2

Start with a prompt

I put the pitfalls from this section into a prompt for OpenCode. Start OpenCode and paste it as is.

Migrate my Claude Code setup to OpenCode V2.

- The source of truth is the OpenCode V2 docs (https://opencode.ai/v2/docs/). Don't use V1 syntax (`permission`, `bash`, `task`, `mcp.<name>`)
- Read: `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, `~/.claude/agents/`, `~/.claude/skills/`, the enabled plugins (`enabledPlugins` in `settings.json`; their contents are under `~/.claude/plugins/cache/`), and the output of `claude mcp list`
- Treat `~/.claude` as read-only and don't change it. If `~/.config/opencode` already has files, back them up first
- Create:
  1. `~/.config/opencode/AGENTS.md`: the contents of `CLAUDE.md`, plus one sentence saying "if a repository has a `CLAUDE.md`, read it before working"
  2. `~/.config/opencode/agents/*.md`: give each agent `mode: subagent` and `model: provider/model#variant`, and rewrite `disallowedTools` as `permissions` deny rules. Don't write `name`
  3. `~/.config/opencode/opencode.jsonc`: `model` (the variant goes in `agents.build.model`); in `skills`, list the plugins' skill folders first and `~/.claude/skills` after them (so personal skills win when IDs collide); MCP servers under `mcp.servers`; hooks only where they can be replaced by `permissions`
  4. For each skill that takes arguments through `$ARGUMENTS`, a command in `~/.config/opencode/commands/` that does nothing but make the model load that skill
- Don't write API keys or tokens in config files (use `{env:NAME}` if needed). Tell me if skill IDs collide
- At the end, check with `opencode debug agents` and `opencode mcp list`, and report in a table what you migrated and what you couldn't (hooks, etc.)

If you'd rather not have it rewrite files right away, switch the agent to plan first (Shift+Tab or /agents) and have it produce only a plan. The plan agent doesn't edit ordinary files.

I tried this prompt as a dry run. In the plan agent on Sonnet 5.5, on my machine, it came back with a plan that covered rewriting 10 agents, the plugins' skill folders, the context7 MCP server and replacing the hooks, plus a table of what can't be moved (the statusLine, and the notification and usage-guard hooks). I did my own migration by hand, following the steps below, before this prompt existed. After a migration, compare the result against the sections below.

What maps to what

Copy a V1 config example and some names will be wrong. In V2, permission is permissions, bash is shell, task is subagent, and MCP servers live under mcp.servers.<name>, not mcp.<name> (Permissions, MCP servers).

Item	Claude Code	OpenCode V2
Instructions	`CLAUDE.md`	`AGENTS.md` only
Subagents	`~/.claude/agents/*.md`	`~/.config/opencode/agents/*.md` (different frontmatter)
Skills	`~/.claude/skills`, plugins	`~/.claude/skills` is picked up automatically; plugin ones go in `skills`
MCP	plugin (context7, in my case)	`mcp.servers.<name>`
Hooks and permissions	`hooks`, `permissions` in `settings.json`	`permissions`; hooks are plugins
Slash commands	skills, `commands/`	`commands/*.md` (`$ARGUMENTS` is expanded here)

`CLAUDE.md` isn't read

V2 reads only AGENTS.md; it doesn't fall back to CLAUDE.md (Instructions). In a throwaway git repository, I asked Haiku 5.5 to answer with a secret word from the instructions alone, without using tools. The word in CLAUDE.md didn't come back, and after I added an AGENTS.md, its word did.

# CLAUDE.md only (PINEAPPLE)
NONE

# AGENTS.md added too (MANGO)
MANGO

Putting CLAUDE.md in the instructions setting doesn't help: V2 accepts the entry but doesn't load it (Config). So I added one line to my global AGENTS.md. It's the model that reads it, so whether it follows the line is up to the model.

<!-- ~/.config/opencode/AGENTS.md -->
- Most of my repos were set up for Claude Code. When a repo has a `CLAUDE.md` and no `AGENTS.md` says otherwise, read that `CLAUDE.md` before working: it is the project's instructions, and its rules apply here.

You can also put an AGENTS.md in each repository that says only Read CLAUDE.md in this repository before working.

Subagents use different frontmatter

Compare the two using coder.

---
# ~/.claude/agents/coder.md
name: coder
description: Use for coding tasks delegated to a subagent: ...
model: sonnet
effort: max
---

---
# ~/.config/opencode/agents/coder.md
description: "Use for coding tasks delegated to a subagent: ..."
mode: subagent
model: "anthropic/claude-sonnet-5-5#max"
permissions:
  - action: question
    resource: "*"
    effect: deny
---

Don't write name; the file name becomes the ID
Without mode: subagent, the agent becomes primary (Agents)
model is provider/model#variant. sonnet and effort: max collapse into it. For model: inherit, delete the line and the agent inherits the parent's model
I deny question because the built-in general agent has the same setting

Copying a Claude Code agent as it is doesn't raise an error. I copied coder, reviewer, review-lead and Plan from ~/.claude/agents/ into .opencode/agents/ in a throwaway git repository, prefixing them with cc- so they wouldn't mix with global agents of the same name, and looked at them with opencode debug agents.

cc-coder        primary  (none)
cc-Plan         primary  (none)
cc-review-lead  primary  (none)
cc-reviewer     primary  (none)

All four are primary, and the model is empty. name, model and effort weren't applied. On top of that, cc-Plan has no edit deny at all, so an agent you meant to make read-only with disallowedTools can edit files. Rewrite disallowedTools as permissions denies.

# Claude Code (Plan.md)
disallowedTools: Edit, Write, NotebookEdit, Agent, ExitPlanMode, Artifact

# OpenCode (planner.md)
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: subagent
    resource: "*"
    effect: deny

The main session's effort can't go in the root model. The root model keeps only the provider and model, and #variant doesn't survive (Models). Put it in agents.build.model.

// ~/.config/opencode/opencode.jsonc
"model": "anthropic/claude-opus-5-5",
"agents": {
  "build": { "model": "anthropic/claude-opus-5-5#max" }
}

Check the agents you migrated by hand with opencode debug agents.

# Piping straight into `| jq` cut the JSON off partway (5 out of 5 times here), so go through a file
opencode debug agents > /tmp/agents.json
jq -r '.[] | select(.id | IN("build","coder","planner","review-lead")) | [.id, .mode, (.model | if . then "\(.providerID)/\(.id)#\(.variant // "")" else "(inherit)" end)] | @tsv' /tmp/agents.json | column -t -s$'\t'

build        primary   anthropic/claude-opus-5-5#max
coder        subagent  anthropic/claude-sonnet-5-5#max
planner      subagent  anthropic/claude-opus-5-5#max
review-lead  subagent  (inherit)

Skills: add only the plugin ones

~/.claude/skills and .claude/skills are read as they are (Skills). What isn't read is plugin skills. Add the skills directory inside the plugin's cache to the skills setting. The path contains the version, so rewrite it when the plugin updates.

// ~/.config/opencode/opencode.jsonc
"skills": [
  "~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/skills",
  "~/.claude/skills",          // on duplicate IDs the later entry wins, so put personal skills after plugins
  "~/.config/opencode/skills"  // skills rewritten for OpenCode go last (mine: delegate and implement-orchestrated)
]

A skill's ID comes from its path, without the plugin namespace (the name in frontmatter is a display name). On my machine, my personal code-review collided with the code-review from the mattpocock-skills plugin. Since the later entry wins, I kept the plugin's version under another name, as a directory containing only a symlink to its SKILL.md.

SRC=~/.claude/plugins/cache/claude-plugins-official/mattpocock-skills/1.2.3/skills/engineering/code-review/SKILL.md
mkdir -p ~/.config/opencode/skills/mattpocock-code-review
ln -s "$SRC" ~/.config/opencode/skills/mattpocock-code-review/SKILL.md

~/.claude/skills and the plugin cache are outside the working directory, so allow external_directory for them. Then skills can read their supporting files.

{ "action": "external_directory", "resource": "~/.claude/skills/*", "effect": "allow" },
{ "action": "external_directory", "resource": "~/.claude/plugins/cache/*", "effect": "allow" }

MCP goes under `servers`

// ~/.config/opencode/opencode.jsonc
"mcp": {
  "servers": {
    "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "oauth": false }
  }
}

Remote MCP servers use OAuth by default. context7 works without an account, so I set oauth: false. If opencode mcp list shows ✓ context7 connected, it's connected. Tool names are <server>_<tool>, not Claude Code's mcp__plugin_context7_context7__…. In the default Code Mode, tools are called through execute (set codemode: false to expose them as regular tools).

Hooks split into permissions and plugins

In Claude Code I had a PreToolUse hook (subagent-irreversible-guard.sh) that stopped only subagents from running git push and deploys. The main session was exempt.

In OpenCode V2 I replaced it with permissions. Rules are evaluated from the top, and the last match wins. Top-level rules apply to every agent, and a subagent doesn't inherit its parent's permissions but runs only on its own (Permissions). So I deny at the top level and re-open it only for the main build agent.

// ~/.config/opencode/opencode.jsonc
{
  "permissions": [
    // a deny that applies to every agent, subagents included
    { "action": "shell", "resource": "git push*", "effect": "deny" },
    { "action": "shell", "resource": "git -C * push", "effect": "deny" },
    { "action": "shell", "resource": "npm publish*", "effect": "deny" },
    { "action": "shell", "resource": "npm run *deploy*", "effect": "deny" }
  ],
  "agents": {
    "build": {
      "permissions": [
        // the last match wins: allow everything first, then set the commands that go outward back to ask
        { "action": "shell", "resource": "*", "effect": "allow" },
        { "action": "shell", "resource": "git push*", "effect": "ask" },
        { "action": "shell", "resource": "git -C * push", "effect": "ask" },
        { "action": "shell", "resource": "npm publish*", "effect": "ask" },
        { "action": "shell", "resource": "npm run *deploy*", "effect": "ask" }
      ]
    }
  }
}

The default is allow-all. A V2 agent starts from an allow on *; only reading .env and anything outside the working directory asks. So you add denies and asks rather than adding allows
A pattern is matched against the whole command string. * matches anything, including spaces and quotes, so a broad pattern like git * push* would even stop git commit -m "fix push bug". I kept mine narrow: git push* and git -C * push
The docs also say it's better to narrow down the commands you allow than to try to catch every dangerous command with patterns. This deny is a fence against accidents, not a sandbox

There's no setting that corresponds to the hooks I ran after edits and on stop (PostToolUse, Stop), so I rewrote them as plugins (~/.config/opencode/plugins/*.js, Plugins). I didn't migrate the usage-guard hooks, because an API key has no 5-hour or weekly plan window.

Slash commands are thin wrappers around skills

A skill is loaded through the skill tool, or by writing @skill-id in a prompt. It's the command that expands $ARGUMENTS (Commands). My delegate skill took its arguments by ending with ARGUMENTS: $ARGUMENTS. I checked how that behaves with opencode run --format json, using a throwaway skill called argtest: the input to the skill tool was only {"id": "argtest"}, and the body that reached the model still contained $ARGUMENTS as is. The model guesses the arguments from the conversation and fills them in, so it can look like it works.

So I add a thin command that only makes the model load the skill.

---
# ~/.config/opencode/commands/delegate.md
description: Hand a task to one background worker subagent (OpenCode version of /delegate)
---

Load the `delegate` skill and follow it. The task to hand off:

$ARGUMENTS

Claude Code-only frontmatter (context: fork, agent:, background:, and so on) isn't in the V2 docs. My /code-review skill had context: fork and agent: review-lead. I replaced them with the command's own agent and subagent: true (it runs in a background child session).

---
# ~/.config/opencode/commands/code-review.md
description: "Bug-hunting review in a background review-lead: [low|medium|high|xhigh|max] [--comment] [<pr#>|<branch>|<path>|<base>...<head>]"
agent: review-lead
subagent: true
---

Load the `code-review` skill and follow it. You are the review lead it describes; ...

Arguments:

$ARGUMENTS

Claude Code's own tools need translating

OpenCode has no Agent tool, SendMessage or isolation: worktree. So that skills written for Claude Code can be read as they are, I keep a translation table in my global AGENTS.md.

Claude Code	OpenCode
`subagent_type: X` in the Agent tool	`agent: X` in the `subagent` tool
`run_in_background: true`	`background: true`
`SendMessage`	call `subagent` again with the same `sessionID`
`isolation: worktree`	run `git worktree add` yourself and put the path in the instructions
`fork`	none (hand over a self-contained brief)

git worktree add doesn't bring over .gitignored files. The .worktreeinclude copying that Claude Code did automatically is also yours to do.

What I checked, and what I didn't

Credit consumption: I confirmed in the Console's Billing that Promotional credits went down after I used OpenCode. The official pages say nothing about third-party clients, so the treatment may change.
On-screen wording: the claude.ai and Console steps follow what the official pages describe.
Permission patterns: that git * push* would even stop a commit message containing push follows from the docs' matching rules. I didn't run it for this post.
Aliased skill links: I link only SKILL.md, so I haven't checked whether relative paths resolve for a skill that has supporting files.
Slash commands: $ARGUMENTS expansion is from reading the docs only (opencode run didn't expand /name).
Not tested: other operating systems, the Desktop app, the Team plan.

Wrap-up

The monthly API credit is for Max 5x, Max 20x and Team only. You get it by linking a Console organization, and interactive Claude Code can't spend it. In OpenCode, register a Console API key, not a Pro/Max login. Keep ANTHROPIC_API_KEY out of ~/.zshrc: Claude Code can pick it up and answer with Credit balance is too low. On my machine, OpenCode usage did draw from Promotional credits, but the official pages don't say so, so check your own balance.

To move your Claude Code setup, paste the prompt into OpenCode and check the result with opencode debug agents: agents and CLAUDE.md files copied over as they are get ignored. Split hooks between permissions (deny at the top level, re-open for build) and plugins.

It's one option for when Claude Code's limit stops you.

References

This post is also on Zenn, in Japanese: zenn.dev/daydreamer/articles/opencode-claude-max-api-credits

Claude Code's usage-limit auto-continue doesn't run in Remote Control sessions. Hooks resume them.

day — Sun, 04 Oct 2026 08:06:40 +0000

TL;DR

Claude Code's built-in auto-continue (autoContinueAtUsageLimit, on by default: it waits for the usage limit to reset, then carries on) doesn't start in Remote Control sessions. As far as I found, only the interactive-mode docs page says so, and nothing on screen tells you. In my transcripts, 0 of 10 limit hits started the wait with Remote Control connected, and 8 of 8 did without it.
The fix is a pair of hooks, Stop and StopFailure, with asyncRewake. They wait for the 5-hour reset and wake the session with exit 2, unless the built-in already resumed it.
The same script keeps a weekly reserve (at 85% it blocks the built-in continuation and asks before dispatching) and adds usage numbers to every prompt.
Checked with two real probe sessions and 35 unit tests. Not tested live: a real 5-hour reset, the 85% paths and a real rate_limit StopFailure payload. Those ran only in unit tests, against fake data.

Tested on Claude Code 2.1.289, claude.ai Max plan, macOS.

Install in one step

Everything in this post is packaged at ryoshumei/claude-code-usage-guard. Paste this into Claude Code; it shows you a dry run and waits for your OK:

Install usage-guard from https://github.com/ryoshumei/claude-code-usage-guard

1. Clone it into a new temp dir (git clone --depth 1, target from mktemp -d) and cd into it.
2. Run ./install.sh --dry-run, show me the plan, and wait for my OK. Do not go on until I say yes.
3. After my OK, run ./install.sh. Add --stop N only if I asked for a weekly stop line other than 85.
4. Show me its full output, then run ~/.claude/usage-guard/usage and show that too.

Do not edit any other file. If a step fails, stop and tell me what happened.

Or run it yourself:

git clone https://github.com/ryoshumei/claude-code-usage-guard ~/.claude/usage-guard-src && ~/.claude/usage-guard-src/install.sh

It backs up every file it touches, keeps your statusline (wrapped, same output; no jq needed), and ~/.claude/usage-guard/install.sh --uninstall undoes it. The rest of this post explains what it does and why, using my original hand-made setup.

The symptom

I run Claude Code in conductor mode: one Opus session dispatching Sonnet subagents in parallel (setup). On Oct 3, in an 86-ticket hackathon run with /remote-control on, the session limit hit, no automatic continue started, and I typed "continue" by hand at the reset.

You've hit your session limit · resets 11:40pm (Asia/Tokyo)

It used to continue on its own, so I suspected the subagents. I want every session to resume after the 5-hour reset and to stop autonomous work at 85% of the weekly limit, because I keep the rest for daily life.

The cause

The docs (interactive mode) list the cases where the built-in wait doesn't start:

Claude Code doesn't start the wait on its own in these cases:

Remote Control and agent team teammate sessions: a person at that terminal can still start one.

The Remote Control page doesn't say it. My transcripts agree. Counting limit hits within 10 minutes of each other as one episode, I have 29. With Remote Control connected (2.1.263–2.1.288) the wait started in 0 of 10; without it (2.1.278–2.1.288), in 8 of 8. Six of the ten have a /remote-control is active line; four older ones (Sep 8–12) have bridge-session records instead. The other 11 aren't counted: five claude -p runs, one Desktop session, three monthly spend limits, one per-model limit, and one hit from before the feature arrived in 2.1.234.

One session flipped by itself: the wait started at 9/25 02:51, 9/25 07:01 and 9/26 08:55; I turned on /remote-control at 9/26 10:33, and none of the next three hits (12:57, 16:23, 19:06) started it. So the switch was Remote Control, not the subagents. The 2.1.289 bundle agrees: the function that arms the wait returns early when Remote Control is connected (an internal, so it can change).

Remote Control can also auto-connect for every session (Enable Remote Control for all sessions in /config, docs), so you may be using it without typing /remote-control.

The fix

I keep the built-in auto-continue on (autoContinueAtUsageLimit: true in my user settings; without it, a project file that has the key switches the feature off, docs) and add four hooks backed by one script, ~/.claude/hooks/usage-guard/usage_guard.py:

Hook	Command	What it does
`Stop`	`resume`	The turn ended with the 5-hour window at 100%: wait for the reset, then wake the session
`StopFailure` (`rate_limit`)	`resume`	The limit cut the turn off: same
`UserPromptSubmit`	`prompt`	Adds a usage line to every prompt. At weekly 85% or more, blocks the built-in continuation prompt
`PreToolUse` (Agent, Task, Workflow, SendMessage)	`gate`	At weekly 85% or more, asks before dispatching an agent or continuing an existing one

resume waits until 4 minutes after the reset, then reads the transcript. It does nothing if the built-in (or I) already resumed the session, or if I cancelled the built-in countdown with Esc, and it gives a built-in wait up to 20 minutes. Otherwise it checks that weekly usage is under 85%, writes a message to stderr and exits 2. With asyncRewake: true, exit 2 wakes the session with that message, even an idle one (hooks docs). It's on both events because a turn that hits the limit ends as StopFailure if it's cut off and as a normal Stop if it finishes first; a per-session, per-reset marker keeps the second one from waiting too.

My ~/.claude/settings.json, with the other hooks left out:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 $HOME/.claude/hooks/usage-guard/usage_guard.py resume",
            "asyncRewake": true,
            "timeout": 86400
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Agent|Task|Workflow|SendMessage",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 $HOME/.claude/hooks/usage-guard/usage_guard.py gate || true",
            "timeout": 5
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 $HOME/.claude/hooks/usage-guard/usage_guard.py prompt || true",
            "timeout": 5
          }
        ]
      }
    ],
    "StopFailure": [
      {
        "matcher": "rate_limit",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 $HOME/.claude/hooks/usage-guard/usage_guard.py resume",
            "asyncRewake": true,
            "timeout": 86400
          }
        ]
      }
    ]
  },
  "autoContinueAtUsageLimit": true
}

The commands call /usr/bin/python3 (on macOS that needs the Xcode Command Line Tools); the script and tests need Python 3.9 or later. resume has timeout 86400 (24 hours) because asyncRewake hooks do get the timeout. The || true on prompt and gate is a safety net: if the script file goes missing, Python exits 2, and per the docs exit 2 on UserPromptSubmit rejects the prompt, so every prompt would be blocked. resume can't have it, because exit 2 is its wake signal.

The numbers come from rate_limits in the JSON Claude Code feeds your statusline script (Pro and Max only). You need jq and a statusLine command in settings.json (docs). These are the first lines of my ~/.claude/statusline-command.sh; if yours already has input=$(cat), add the rest right after it and don't read stdin twice, because the second read is empty and blanks the statusline.

input=$(cat)

# Cache the plan's rate limits (weekly %, 5-hour %) so a long-running session
# can pause itself at a threshold. Account-wide, so any session's value will do.
rl_cache="$HOME/.claude/rate-limits.json"
echo "$input" | jq -c 'select(.rate_limits != null) | {rate_limits, at: (now | floor)}' > "$rl_cache.$$" 2>/dev/null \
  && [ -s "$rl_cache.$$" ] && mv "$rl_cache.$$" "$rl_cache" || rm -f "$rl_cache.$$"

They're account-wide, so any session's refresh writes the same values. My ~/.claude/CLAUDE.md tells the model to end each final reply (main session only) with a usage line and to stop autonomous work at weekly 85%.

To install it, save the script below as ~/.claude/hooks/usage-guard/usage_guard.py and add the two pieces above.

Full usage_guard.py (383 lines)

#!/usr/bin/env python3
"""usage-guard: keep a weekly reserve, and resume sessions after the 5-hour limit resets.

Reads ~/.claude/rate-limits.json, which ~/.claude/statusline-command.sh writes from the
statusline's `rate_limits` field (claude.ai plans only). Subcommands:

  usage   print the current numbers, for you or the model
  prompt  UserPromptSubmit hook: add the numbers as context; block the built-in
          auto-continue prompt when weekly usage is at or above the stop line
  gate    PreToolUse hook (Agent|Task|Workflow|SendMessage): ask before dispatching
          or continuing an agent at or above it
  resume  Stop and StopFailure(rate_limit) hook, run with asyncRewake: wait for the
          5-hour reset, then exit 2 to wake the session, unless it already resumed,
          the built-in wait was cancelled, or weekly usage is at or above the stop line

The built-in autoContinueAtUsageLimit never starts its wait while Remote Control is
active (documented; checked in 2.1.288/2.1.289); `resume` covers those sessions. In
other sessions the built-in usually resumes first and `resume` stands down.
"""
import datetime
import json
import os
import re
import shutil
import subprocess
import sys
import time

STOP = float(os.environ.get("USAGE_GUARD_WEEKLY_STOP", "85"))
CACHE = os.path.expanduser(os.environ.get("USAGE_GUARD_CACHE", "~/.claude/rate-limits.json"))
STATE = os.path.expanduser(os.environ.get("USAGE_GUARD_STATE", "~/.claude/usage-guard"))
# Wake this long after the reset. The built-in auto-continue resumes about 1-2 min
# after it, so by then a session it resumed has already written to its transcript.
DELAY = int(os.environ.get("USAGE_GUARD_RESUME_DELAY", "240"))
# Sleep in short steps and re-check the wall clock, so a Mac that slept through the
# reset still resumes within one step of waking.
POLL = int(os.environ.get("USAGE_GUARD_POLL", "30"))
# When the built-in started its own wait, give it this long after the reset before
# waking the session ourselves (its jitter is server-tunable).
BUILTIN_GRACE = int(os.environ.get("USAGE_GUARD_BUILTIN_GRACE", "1200"))
MAX_WAIT = 5.5 * 3600  # how far out a reset may be; the hook's timeout in settings.json is 24 h
MAX_WAKES_PER_DAY = 6
AUTO_CONTINUE = ("Your claude.ai usage limit has reset", "Your claude.ai usage is available again")
CONTINUATION = "Continue the task you were working on when the limit was reached"


def to_epoch(value):
    if isinstance(value, (int, float)):
        return float(value)
    if isinstance(value, str):
        try:
            return float(value)
        except ValueError:
            pass
        try:
            return datetime.datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
        except ValueError:
            return None
    return None


def load(now=None):
    """Current usage, or None without a cache. A window whose reset has passed reads as None."""
    now = time.time() if now is None else now
    try:
        with open(CACHE) as f:
            data = json.load(f)
    except (OSError, ValueError):
        return None
    limits = data.get("rate_limits") or {}

    def window(key):
        w = limits.get(key) or {}
        used, reset = w.get("used_percentage"), to_epoch(w.get("resets_at"))
        if not isinstance(used, (int, float)) or (reset is not None and reset <= now):
            used = None
        return used, reset

    h5, h5_reset = window("five_hour")
    wk, wk_reset = window("seven_day")
    return {"h5": h5, "h5_reset": h5_reset, "wk": wk, "wk_reset": wk_reset, "at": to_epoch(data.get("at"))}


def pct(value):
    return "{:g}".format(round(value, 1))


def clock(ts, with_date=False):
    if ts is None:
        return "?"
    return time.strftime("%m/%d %H:%M" if with_date else "%H:%M", time.localtime(ts))


def summary(u, now=None):
    now = time.time() if now is None else now
    weekly = "weekly {}% (resets {})".format(pct(u["wk"]), clock(u["wk_reset"], True)) if u["wk"] is not None else "weekly ?"
    if u["h5"] is not None:
        five = "5-hour {}% (resets {})".format(pct(u["h5"]), clock(u["h5_reset"]))
    else:
        five = "5-hour: new window, no reading yet"
    age = " · read {} min ago".format(int((now - u["at"]) // 60)) if u["at"] else ""
    return "{} · {}{}".format(weekly, five, age)


def over_stop(u):
    return bool(u) and u["wk"] is not None and u["wk"] >= STOP


def emit(obj):
    sys.stdout.write(json.dumps(obj, ensure_ascii=False) + "\n")


def log(sid, text):
    try:
        os.makedirs(STATE, exist_ok=True)
        path = os.path.join(STATE, "log")
        if os.path.exists(path) and os.path.getsize(path) > 512 * 1024:
            os.replace(path, path + ".1")
        with open(path, "a") as f:
            f.write("{} {} {}\n".format(time.strftime("%Y-%m-%d %H:%M:%S"), (sid or "-")[:8], text))
    except OSError:
        pass


def notify(text):
    if os.environ.get("USAGE_GUARD_NOTIFY", "1") == "0":
        return
    try:
        if shutil.which("terminal-notifier"):
            cmd = ["terminal-notifier", "-title", "Claude Code — usage-guard", "-message", text]
        else:
            cmd = ["osascript", "-e", "display notification {} with title \"Claude Code — usage-guard\"".format(
                json.dumps(text, ensure_ascii=False))]
        subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
    except OSError:
        pass


def cmd_usage():
    u = load()
    if u is None:
        print("usage-guard: no reading yet ({} is written by the statusline)".format(CACHE))
        return 1
    verdict = "STOP autonomous work" if over_stop(u) else "ok"
    print("{} · stop line {}% → {}".format(summary(u), pct(STOP), verdict))
    return 0


def is_continuation(prompt):
    """The built-in's continuation prompt, also if the server rewords its opening. A longer
    message that only quotes the sentence (a report, a question about it) is not one."""
    if prompt.startswith(AUTO_CONTINUE):
        return True
    at = prompt.find(CONTINUATION)
    return 0 <= at < 150 and len(prompt) < 400 and not prompt.startswith("<")


def cmd_prompt(inp):
    u = load()
    if u is None:
        return 0
    prompt = (inp.get("prompt") or "").lstrip()
    if over_stop(u) and is_continuation(prompt):
        log(inp.get("session_id"), "blocked the built-in auto-continue: weekly {}%".format(pct(u["wk"])))
        notify("Weekly usage {}% ≥ {}%: auto-continue skipped, session stays paused.".format(pct(u["wk"]), pct(STOP)))
        emit({"decision": "block", "reason": "usage-guard: weekly usage is {}%, at or above the {}% reserve line, "
              "so the automatic continue was stopped. Send a prompt to continue anyway.".format(pct(u["wk"]), pct(STOP))})
        return 0
    context = "usage-guard: {}. Autonomous work stops at weekly {}%.".format(summary(u), pct(STOP))
    if over_stop(u):
        context += (" Weekly usage is at or above that line: answer this prompt, but start no new"
                    " autonomous or fan-out work without asking.")
    emit({"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": context}})
    return 0


def cmd_gate(inp):
    u = load()
    if not over_stop(u):
        return 0
    target = str((inp.get("tool_input") or {}).get("to") or "").strip()
    if inp.get("tool_name") == "SendMessage" and target == "main":
        return 0  # a background agent reporting to the main session
    emit({"hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "ask",
        "permissionDecisionReason": "usage-guard: weekly usage is {}% (reserve line {}%). Approve to run {} anyway, "
                                    "or deny to keep the reserve.".format(pct(u["wk"]), pct(STOP), inp.get("tool_name") or "it"),
    }})
    return 0


def classify(message, u):
    m = message.lower()
    if "session limit" in m:
        return "five_hour"
    if "weekly" in m:
        return "weekly"
    if u and u["h5"] is not None and u["h5"] >= 100:
        return "five_hour"
    if u and u["wk"] is not None and u["wk"] >= 100:
        return "weekly"
    return "other"  # spend limits, per-model limits, unknown


def parse_reset(message, now):
    """'You've hit your session limit · resets 4:40am (Asia/Tokyo)' -> the next 4:40 in that zone."""
    m = re.search(r"resets\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*([ap]m)\b(?:\s*\(([^)]+)\))?", message, re.I)
    if not m:
        return None
    hour = int(m.group(1)) % 12 + (12 if m.group(3).lower() == "pm" else 0)
    minute = int(m.group(2) or 0)
    zone = None
    if m.group(4):
        try:
            from zoneinfo import ZoneInfo
            zone = ZoneInfo(m.group(4))
        except Exception:
            zone = None
    base = datetime.datetime.fromtimestamp(now, zone) if zone else datetime.datetime.fromtimestamp(now)
    at = base.replace(hour=hour, minute=minute, second=0, microsecond=0)
    if at.timestamp() <= now:
        at += datetime.timedelta(days=1)
    return at.timestamp()


def recent_wakes(sid, now):
    """Count this session's armed resets in the last day, and drop markers older than three days."""
    armed = os.path.join(STATE, "armed")
    count = 0
    try:
        for name in os.listdir(armed):
            path = os.path.join(armed, name)
            age = now - os.path.getmtime(path)
            if age > 3 * 86400:
                shutil.rmtree(path, ignore_errors=True)
            elif name.startswith(sid + "-") and age < 86400:
                count += 1
    except OSError:
        pass
    return count


def sleep_until(ts):
    while True:
        left = ts - time.time()
        if left <= 0:
            return
        time.sleep(min(POLL, left))


def transcript_state(path, reset, armed_at):
    """What the session did since the limit hit, read from the transcript's tail.

    resumed: a turn ran after the reset (a typed prompt, the built-in's continuation, a
    task notification). Only timestamped turn entries count: Claude Code also appends
    untimestamped lines, e.g. when a Remote Control client connects.
    cancelled: the built-in wait was cancelled (Esc, or the session moved elsewhere).
    builtin_armed: the built-in started its own wait for this limit.
    """
    state = {"resumed": False, "cancelled": False, "builtin_armed": False}
    try:
        with open(path, "rb") as f:
            f.seek(0, 2)
            f.seek(max(0, f.tell() - 4 * 1024 * 1024))
            lines = f.read().splitlines()
    except (OSError, TypeError):
        return state
    for raw in lines:
        try:
            entry = json.loads(raw)
        except ValueError:
            continue
        ts = to_epoch(entry.get("timestamp")) if isinstance(entry, dict) else None
        if ts is None:
            continue
        kind = entry.get("type")
        if kind in ("user", "assistant", "queue-operation") and ts > reset:
            state["resumed"] = True
        elif kind == "system" and ts >= armed_at - 120:
            text = str(entry.get("content") or "")
            if text.startswith("Automatic continue cancelled"):
                state["cancelled"] = True
            elif "continuing automatically at" in text:
                state["builtin_armed"] = True
    return state


def cmd_resume(inp):
    # Hold only interactive CLI sessions. In `claude -p` an asyncRewake hook runs in the
    # foreground, so waiting there would hang the run for hours.
    if os.environ.get("CLAUDE_CODE_ENTRYPOINT") != "cli":
        return 0
    event = inp.get("hook_event_name")
    sid = inp.get("session_id") or "unknown"
    message = inp.get("last_assistant_message") or ""
    now = time.time()
    u = load(now)
    if event == "StopFailure":
        if inp.get("error") != "rate_limit":
            return 0
        kind = classify(message, u)
    elif event == "Stop":
        if not u or u["h5"] is None or u["h5"] < 100:
            return 0  # the usual case: a turn ended below the limit
        kind = "five_hour"
    else:
        return 0

    if kind == "weekly":
        log(sid, "weekly limit hit: no auto-resume")
        notify("Weekly limit reached: this session will not resume on its own.")
        return 0
    if kind != "five_hour":
        log(sid, "rate limit is not the 5-hour window ({}): no auto-resume".format(message.splitlines()[0][:80] if message else "?"))
        return 0
    reset = u["h5_reset"] if u and u["h5_reset"] and u["h5_reset"] > now else parse_reset(message, now)
    if reset is None or reset - now > MAX_WAIT:
        log(sid, "no usable 5-hour reset time: no auto-resume")
        return 0
    if over_stop(u):
        log(sid, "weekly {}% >= {}%: staying paused after the reset".format(pct(u["wk"]), pct(STOP)))
        notify("Weekly usage {}% ≥ {}%: session paused, no auto-resume.".format(pct(u["wk"]), pct(STOP)))
        return 0
    if recent_wakes(sid, now) >= MAX_WAKES_PER_DAY:
        log(sid, "{} resumes in the last day: giving up".format(MAX_WAKES_PER_DAY))
        return 0
    try:
        os.makedirs(os.path.join(STATE, "armed", "{}-{}".format(sid, int(reset))))
    except FileExistsError:
        return 0  # another Stop/StopFailure already armed this reset
    except OSError:
        return 0
    armed_at = time.time()
    target = reset + DELAY
    log(sid, "armed via {}: wake at {}".format(event, clock(target, True)))

    transcript = inp.get("transcript_path")
    while True:
        sleep_until(target)
        state = transcript_state(transcript, reset, armed_at)
        if state["resumed"]:
            log(sid, "already resumed (built-in auto-continue or a prompt): not waking")
            return 0
        if state["cancelled"]:
            log(sid, "the built-in wait was cancelled (Esc, or the session moved): not waking")
            return 0
        if state["builtin_armed"] and time.time() < reset + BUILTIN_GRACE:
            target = min(time.time() + 2 * POLL, reset + BUILTIN_GRACE)  # its continuation may still come
            continue
        break
    u = load()
    if over_stop(u):
        log(sid, "weekly {}% >= {}% after the reset: staying paused".format(pct(u["wk"]), pct(STOP)))
        notify("Weekly usage {}% ≥ {}%: session paused, no auto-resume.".format(pct(u["wk"]), pct(STOP)))
        return 0
    weekly = "{}%".format(pct(u["wk"])) if u and u["wk"] is not None else "unknown"
    sys.stderr.write(
        "usage-guard: the 5-hour usage limit reset at {}. Weekly usage is {}; autonomous work stops at {}%. "
        "Continue the task you were working on when the limit was reached, without redoing finished work. "
        "If that task was already done, reply with one short line and stop.\n".format(clock(reset), weekly, pct(STOP)))
    log(sid, "woke the session")
    return 2


def main():
    cmd = sys.argv[1] if len(sys.argv) > 1 else "usage"
    if cmd == "usage":
        return cmd_usage()
    handler = {"prompt": cmd_prompt, "gate": cmd_gate, "resume": cmd_resume}.get(cmd)
    if handler is None:
        sys.stderr.write("usage: usage_guard.py [usage|prompt|gate|resume]\n")
        return 1
    try:
        inp = json.load(sys.stdin)
        return handler(inp if isinstance(inp, dict) else {})
    except Exception as exc:  # a broken guard must never block a prompt, a tool, or a stop
        log("-", "{} failed: {!r}".format(cmd, exc))
        return 0


if __name__ == "__main__":
    sys.exit(main())

Checking that it works

usage prints the cached numbers and a verdict:

python3 ~/.claude/hooks/usage-guard/usage_guard.py usage

weekly 54% (resets 10/08 05:00) · 5-hour 12% (resets 21:10) · read 1 min ago · stop line 85% → ok

read 1 min ago is the cache's age. With no cache it prints no reading yet and exits 1, so the statusline lines aren't working. To see the stop verdict, set the line below your current usage (mine was 54%):

USAGE_GUARD_WEEKLY_STOP=50 python3 ~/.claude/hooks/usage-guard/usage_guard.py usage

The line then ends with stop line 50% → STOP autonomous work.

The log is ~/.claude/usage-guard/log: a timestamp, the first 8 characters of the session id and a message such as armed via … (a reset wait started), woke the session or already resumed …. The first event creates the file; on my machine nothing has happened yet, so it doesn't exist.

The 35 unit tests use a fake cache and a temporary state directory, never your real files:

bash ~/.claude/hooks/usage-guard/usage_guard.test.sh

They end with passed 35, failed 0 (about 38 seconds).

Full usage_guard.test.sh (164 lines)

#!/usr/bin/env bash
# Tests for usage_guard.py. Uses a fake cache and state dir; never touches the real ones.
set -u
G="$(cd "$(dirname "$0")" && pwd)/usage_guard.py"
T=$(mktemp -d); trap 'rm -rf "$T"' EXIT
export USAGE_GUARD_CACHE="$T/rate-limits.json" USAGE_GUARD_STATE="$T/state" USAGE_GUARD_NOTIFY=0
export USAGE_GUARD_RESUME_DELAY=1 USAGE_GUARD_POLL=1
pass=0; fail=0
ok()   { pass=$((pass+1)); }
bad()  { fail=$((fail+1)); echo "FAIL: $1"; }
check() { if eval "$2"; then ok; else bad "$1"; fi; }

cache() { # h5 h5_reset_offset wk [wk_reset_offset]
  local now; now=$(date +%s)
  printf '{"rate_limits":{"five_hour":{"used_percentage":%s,"resets_at":%s},"seven_day":{"used_percentage":%s,"resets_at":%s}},"at":%s}' \
    "$1" $((now + $2)) "$3" $((now + ${4:-300000})) "$now" > "$USAGE_GUARD_CACHE"
}
hook() { # subcommand json -> sets out, rc
  out=$(printf '%s' "$2" | python3 "$G" "$1" 2>"$T/err"); rc=$?; err=$(cat "$T/err")
}

# usage
cache 40 3600 47
out=$(python3 "$G" usage); check "usage prints numbers" '[[ "$out" == *"weekly 47%"* && "$out" == *"5-hour 40%"* && "$out" == *"→ ok"* ]]'
rm -f "$USAGE_GUARD_CACHE"
python3 "$G" usage >/dev/null; check "usage without cache exits 1" '[ $? -eq 1 ]'

# prompt
hook prompt '{"prompt":"hi"}'; check "prompt without cache is silent" '[ $rc -eq 0 ] && [ -z "$out" ]'
cache 40 3600 47
hook prompt '{"prompt":"hi"}'
check "prompt adds context" '[ $rc -eq 0 ] && [[ "$out" == *additionalContext* && "$out" == *"weekly 47%"* ]]'
check "prompt below line has no stop note" '[[ "$out" != *"at or above"* ]]'
hook prompt '{"prompt":"Your claude.ai usage limit has reset. Continue the task you were working on"}'
check "auto-continue passes below the line" '[[ "$out" == *additionalContext* && "$out" != *"\"block\""* ]]'
cache 40 3600 90
hook prompt '{"prompt":"Your claude.ai usage limit has reset. Continue the task you were working on"}'
check "auto-continue blocked at 90%" '[ $rc -eq 0 ] && [[ "$out" == *"\"decision\": \"block\""* ]]'
hook prompt '{"prompt":"Your claude.ai usage is available again before the usage-limit reset."}'
check "early auto-continue blocked at 90%" '[[ "$out" == *"\"block\""* ]]'
hook prompt '{"prompt":"what is 2+2"}'
check "user prompt at 90% passes with a note" '[[ "$out" == *additionalContext* && "$out" == *"at or above"* ]]'
cache 40 3600 90 -10
hook prompt '{"prompt":"Your claude.ai usage limit has reset."}'
check "stale weekly (window over) does not block" '[[ "$out" != *"\"block\""* && "$out" == *"weekly ?"* ]]'

# gate
cache 40 3600 84.9
hook gate '{"tool_name":"Agent"}'; check "gate silent below line" '[ $rc -eq 0 ] && [ -z "$out" ]'
cache 40 3600 85
hook gate '{"tool_name":"Agent"}'; check "gate asks at 85%" '[[ "$out" == *"\"permissionDecision\": \"ask\""* && "$out" == *Agent* ]]'
hook gate '{"tool_name":"SendMessage","tool_input":{"to":"coder-7","message":"fix round 2"}}'
check "gate asks before continuing an agent" '[[ "$out" == *"\"ask\""* ]]'
hook gate '{"tool_name":"SendMessage","tool_input":{"to":"main","message":"done"}}'
check "gate lets an agent report to main" '[ $rc -eq 0 ] && [ -z "$out" ]'
cache 40 3600 90
hook prompt '{"prompt":"[usage] Continue the task you were working on when the limit was reached; do not repeat work."}'
check "reworded continuation still blocked" '[[ "$out" == *"\"block\""* ]]'
long=$(python3 -c 'print("Report: the hook matches \"Continue the task you were working on when the limit was reached\" and " + "x" * 400)')
hook prompt "$(python3 -c 'import json,sys;print(json.dumps({"prompt":sys.argv[1]}))' "$long")"
check "a long report quoting the sentence passes" '[[ "$out" != *"\"block\""* && "$out" == *additionalContext* ]]'
hook prompt '{"prompt":"<task-notification> Continue the task you were working on when the limit was reached </task-notification>"}'
check "a task notification quoting it passes" '[[ "$out" != *"\"block\""* ]]'

# resume: guards
cache 101 3 50
export CLAUDE_CODE_ENTRYPOINT=sdk-cli
hook resume '{"hook_event_name":"Stop","session_id":"s1"}'
check "resume skips non-cli entrypoints" '[ $rc -eq 0 ] && [ ! -d "$USAGE_GUARD_STATE/armed" ]'
export CLAUDE_CODE_ENTRYPOINT=cli
cache 60 3 50
start=$(date +%s); hook resume '{"hook_event_name":"Stop","session_id":"s1"}'
check "Stop below the limit exits at once" '[ $rc -eq 0 ] && [ $(( $(date +%s) - start )) -le 1 ]'
hook resume '{"hook_event_name":"StopFailure","error":"overloaded","session_id":"s1"}'
check "StopFailure other error exits" '[ $rc -eq 0 ] && [ ! -d "$USAGE_GUARD_STATE/armed" ]'
hook resume '{"hook_event_name":"StopFailure","error":"rate_limit","session_id":"s1","last_assistant_message":"You have hit your weekly limit · resets Oct 8, 5am"}'
check "weekly limit is not resumed" '[ $rc -eq 0 ] && grep -q "weekly limit hit" "$USAGE_GUARD_STATE/log"'
cache 60 3 50
hook resume '{"hook_event_name":"StopFailure","error":"rate_limit","session_id":"s1","last_assistant_message":"You have reached your Fable limit."}'
check "per-model limit is not resumed" '[ $rc -eq 0 ] && grep -q "not the 5-hour window" "$USAGE_GUARD_STATE/log"'
cache 101 3 90
hook resume '{"hook_event_name":"Stop","session_id":"s1"}'
check "weekly over the line stays paused" '[ $rc -eq 0 ] && grep -q "staying paused" "$USAGE_GUARD_STATE/log"'

# resume: wakes after the reset
touch "$T/transcript.jsonl"; sleep 1
cache 101 3 50
start=$(date +%s)
hook resume "{\"hook_event_name\":\"Stop\",\"session_id\":\"s2\",\"transcript_path\":\"$T/transcript.jsonl\"}"
took=$(( $(date +%s) - start ))
check "Stop at the limit wakes with exit 2" '[ $rc -eq 2 ] && [[ "$err" == *"5-hour usage limit reset"* && "$err" == *"Weekly usage is 50%"* ]]'
check "it waited for reset + delay" '[ $took -ge 3 ] && [ $took -le 7 ]'

# resume: what the transcript says after the limit hit
entry() { # type [content] -> one timestamped transcript line, like Claude Code writes
  python3 -c 'import json,sys,datetime;print(json.dumps({"type":sys.argv[1],"timestamp":datetime.datetime.utcnow().isoformat(timespec="milliseconds")+"Z","content":sys.argv[2]}))' "$1" "${2:-}"
}
sf() { # session_id transcript -> StopFailure input for a session limit
  printf '{"hook_event_name":"StopFailure","error":"rate_limit","session_id":"%s","transcript_path":"%s","last_assistant_message":"You'"'"'ve hit your session limit · resets 4:40am (Asia/Tokyo)"}' "$1" "$2"
}
: > "$T/t3.jsonl"; cache 101 2 50
( sleep 2.5; entry user "Your claude.ai usage limit has reset. Continue the task" >> "$T/t3.jsonl" ) &
USAGE_GUARD_RESUME_DELAY=2 hook resume "$(sf s3 "$T/t3.jsonl")"
check "no wake when a turn ran after the reset" '[ $rc -eq 0 ] && grep -q "s3 already resumed" "$USAGE_GUARD_STATE/log"'

: > "$T/t6.jsonl"; cache 101 2 50
( sleep 2.5; echo '{"type":"bridge-session","sessionId":"x"}' >> "$T/t6.jsonl" ) &
USAGE_GUARD_RESUME_DELAY=2 hook resume "$(sf s6 "$T/t6.jsonl")"
check "an untimestamped bridge line does not count as resumed" '[ $rc -eq 2 ]'

: > "$T/t7.jsonl"; cache 101 2 50
( sleep 0.5; entry system "Automatic continue cancelled" >> "$T/t7.jsonl" ) &
USAGE_GUARD_RESUME_DELAY=2 hook resume "$(sf s7 "$T/t7.jsonl")"
check "Esc on the built-in countdown is respected" '[ $rc -eq 0 ] && grep -q "s7 the built-in wait was cancelled" "$USAGE_GUARD_STATE/log"'

: > "$T/t8.jsonl"; cache 101 2 50
( sleep 0.5; entry system "Usage limit reached · continuing automatically at 4:40am · esc to cancel" >> "$T/t8.jsonl" ) &
start=$(date +%s)
USAGE_GUARD_RESUME_DELAY=1 USAGE_GUARD_BUILTIN_GRACE=6 hook resume "$(sf s8 "$T/t8.jsonl")"
took=$(( $(date +%s) - start ))
check "a silent built-in gets its grace, then the guard wakes" '[ $rc -eq 2 ] && [ $took -ge 5 ] && [ $took -le 10 ]'

: > "$T/t9.jsonl"; cache 101 2 50
( sleep 0.5; entry system "Usage limit reached · continuing automatically at 4:40am · esc to cancel" >> "$T/t9.jsonl"; sleep 4; entry user "Your claude.ai usage limit has reset." >> "$T/t9.jsonl" ) &
USAGE_GUARD_RESUME_DELAY=1 USAGE_GUARD_BUILTIN_GRACE=30 hook resume "$(sf s9 "$T/t9.jsonl")"
check "a late built-in continuation makes the guard stand down" '[ $rc -eq 0 ] && grep -q "s9 already resumed" "$USAGE_GUARD_STATE/log"'

# resume: Stop and StopFailure for the same reset arm once
cache 101 3 50
printf '%s' "{\"hook_event_name\":\"StopFailure\",\"error\":\"rate_limit\",\"session_id\":\"s4\",\"last_assistant_message\":\"You've hit your session limit\"}" | python3 "$G" resume 2>/dev/null & p1=$!
sleep 0.5
start=$(date +%s); hook resume '{"hook_event_name":"Stop","session_id":"s4"}'
check "second hook for the same reset exits at once" '[ $rc -eq 0 ] && [ $(( $(date +%s) - start )) -le 1 ]'
wait $p1; check "first hook still wakes" '[ $? -eq 2 ]'

# resume: weekly crossed the line during the wait -> no wake
cache 101 2 50
( sleep 1; cache 101 -60 88 ) &
hook resume '{"hook_event_name":"Stop","session_id":"s5"}'
check "weekly crossing during the wait stays paused" '[ $rc -eq 0 ] && grep -q "after the reset: staying paused" "$USAGE_GUARD_STATE/log"'

# reset time parsed from the message when the cache has none
out=$(USAGE_GUARD_CACHE=/nonexistent python3 - "$G" <<'EOF'
import importlib.util, sys, datetime
spec = importlib.util.spec_from_file_location("g", sys.argv[1]); g = importlib.util.module_from_spec(spec); spec.loader.exec_module(g)
from zoneinfo import ZoneInfo
tz = ZoneInfo("Asia/Tokyo")
now = datetime.datetime(2026, 10, 4, 1, 2, tzinfo=tz).timestamp()
r = g.parse_reset("You've hit your session limit · resets 4:40am (Asia/Tokyo)", now)
print(datetime.datetime.fromtimestamp(r, tz).strftime("%m/%d %H:%M"))
r = g.parse_reset("You've hit your session limit · resets 11:40pm (Asia/Tokyo)", datetime.datetime(2026, 10, 3, 22, 43, tzinfo=tz).timestamp())
print(datetime.datetime.fromtimestamp(r, tz).strftime("%m/%d %H:%M"))
r = g.parse_reset("resets 12:10am (Asia/Tokyo)", datetime.datetime(2026, 10, 3, 23, 0, tzinfo=tz).timestamp())
print(datetime.datetime.fromtimestamp(r, tz).strftime("%m/%d %H:%M"))
print(g.parse_reset("no time here", now))
EOF
)
check "parse_reset reads the limit message" '[ "$out" = "$(printf "10/04 04:40\n10/03 23:40\n10/04 00:10\nNone")" ]'

# malformed input never blocks
out=$(echo 'not json' | python3 "$G" prompt); check "malformed input exits 0" '[ $? -eq 0 ]'

echo "passed $pass, failed $fail"
[ $fail -eq 0 ]

I also checked the wake in two real interactive sessions: a hook that sleeps 20 seconds, writes to stderr and exits 2, once on Stop and once on a StopFailure forced with a nonexistent model (model_not_found). Both times a new turn started within a second of the hook exiting, and the reply came 1–2 seconds later. The StopFailure reply was the same error again, since the model is still missing.

Caveats

Not tested live. A real 5-hour reset with the final hooks, the 85% paths (continuation block, gate confirmation, staying paused after the reset) and a real rate_limit StopFailure payload ran only in unit tests, against fake data. The Esc-cancel handling hasn't met a real transcript either (the Automatic continue cancelled text is in the docs and the 2.1.289 bundle).
The 85% brake is partial. By design (untested live) it blocks the continuation prompt and the hook wake, and asks before dispatching or continuing a worker. A short prompt with Continue the task you were working on when the limit was reached near its start counts as the continuation and is blocked; a long report that merely quotes it passes. Other autonomous work, like a long turn that dispatches nothing or a /loop prompt, depends on the model following CLAUDE.md.
Freshness. The cache only changes when some session's statusline refreshes (I haven't set refreshInterval), and read N min ago shows its age. UserPromptSubmit also fires on subagent reports, so the line is added often in conductor mode.
Internals. The code-level check that skips Remote Control sessions (an early return in the 2.1.289 bundle) and asyncRewake hooks running in the foreground under claude -p come from reading that code; they aren't documented and can change. In my logs the built-in resumed about 1–2 minutes after the reset (71–99 s in seven cases). The docs say StopFailure output is ignored, yet an asyncRewake hook still woke the session (observed, not documented).
Small things. The wake is labelled Stop hook feedback in the UI (cosmetic). Quit Claude Code during the wait and nothing resumes. Weekly limits are never auto-resumed.

Versions tested

Claude Code 2.1.289: probes, code reading, unit tests
Limit history: transcripts from 2.1.219 to 2.1.288 (29 episodes)
claude.ai Max plan, macOS, /usr/bin/python3 3.9.6, jq 1.7.1
Not tested: anything but macOS, IDE extensions, the Desktop app

Claude Code deletes clean worktrees on exit without asking. git worktree lock stops it.

day — Fri, 11 Sep 2026 23:12:29 +0000

TL;DR

If you /exit a claude --worktree <name> session with no uncommitted changes and no new commits, Claude Code removes the worktree and its branch without showing the Keep/Remove dialog.
This is documented behavior, not a bug. There is no setting to turn it off.
Claude Code holds its own git worktree lock on the worktree and only ever releases locks whose reason matches its own format. Re-lock the worktree with your own reason and the cleanup backs off.
A SessionStart hook can do the re-lock automatically.
Pre-creating the worktree with git worktree add does not protect it. If its branch is named worktree-<name>, existing unmerged commits get force-deleted too.

Tested on Claude Code 2.1.263, git 2.52.0, macOS.

The symptom

You start an isolated session:

claude --worktree wt-clean

You read some code, maybe run a few commands, and then /exit. You never picked "Remove worktree". But:

$ git worktree list
/path/to/demo  731024a [main]
# .claude/worktrees/wt-clean is gone, and so is branch worktree-wt-clean

If you blink you see Cleaning up worktree (no pending changes)… flash by. That's the only notice you get.

What the exit code actually checks

I pulled the bundled source out of the Claude Code binary to see the decision. On /exit from a worktree session it runs two git commands inside the worktree:

git status --porcelain                                  # changed + untracked files
git rev-list --count <HEAD at session start>..HEAD      # new commits this session

Then it branches like this:

Worktree state	Session named?	What `/exit` does
0 changed files, 0 new commits	no	Removes worktree and branch, no prompt
0 changed files, 0 new commits	yes (`/rename`)	Keep / Remove dialog
Any uncommitted change or any new commit	either	Keep / Remove dialog

The silent path runs:

git worktree unlock <path>
git worktree remove --force <path>
git branch -D worktree-<name>

The "new commits" check is relative to the HEAD at session start. Anything committed before the session doesn't count. Keep that in mind for the pre-created worktree gotcha below.

It's documented

From the official worktrees page:

The worktree is clean: for an unnamed session, Claude removes the worktree and its branch automatically. A named session prompts you first so you can keep the worktree for later

So the design intent is "clean means disposable". Plenty of people disagree. Related issues (all closed):

#27753 Worktree auto-deleted on exit when work is committed
#46444 worktree auto-cleanup permanently deleted 10 days of uncommitted project work without any warning
#58432 WorktreeRemove hook suppresses the /exit keep-or-remove picker

There is no worktree.keepOnExit-style setting. So we lean on git instead.

Why `git worktree lock` works

Claude Code already uses git worktree lock on every worktree it creates. Look at the registry while a session is running:

$ git worktree list --porcelain
worktree /path/to/demo/.claude/worktrees/wt-lock
HEAD 731024acd920b9883ae2f00845fa4ebc8ae0230e
branch refs/heads/worktree-wt-lock
locked claude session wt-lock (pid 72411 start Tue Sep  8 13:50:41 2026)

At exit, the cleanup routine reads the lock reason back and tests it against this regex (from the bundle):

/^claude (?:agent|session) .{1,255} \(pid (\d{1,10})(?: start (.{1,255}))?\)$/

If the reason doesn't match, or it matches but the PID belongs to another live process, the routine keeps the worktree and logs:

cleanupWorktree: kept <path> — locked by another live Claude Code process, or with a reason we did not write

The docs say the same thing about the background stale-lock sweep: "The sweep never releases a lock you set yourself with git worktree lock." A user-set lock is consistently treated as off-limits.

Fix 1: re-lock by hand

During the session, from another terminal (or with the ! prefix inside Claude Code):

git worktree unlock .claude/worktrees/wt-lock
git worktree lock --reason "pinned by ryan" .claude/worktrees/wt-lock

You must unlock first. Claude Code's lock is already there, so a bare lock fails:

$ git worktree lock --reason "keep" .claude/worktrees/wt-lock
fatal: '.claude/worktrees/wt-lock' is already locked, reason: claude session wt-lock (pid 72411 start ...)

Now /exit:

$ git worktree list
/path/to/demo                             731024a [main]
/path/to/demo/.claude/worktrees/wt-lock   731024a [worktree-wt-lock] locked

The reason text doesn't matter. Running git worktree unlock . && git worktree lock . from inside the worktree, with no reason at all, also kept it.

Next time, claude --worktree wt-lock drops you back into the same worktree. Your lock stays, so it survives the next /exit too.

Fix 2: automate it with a SessionStart hook

Save this script:

#!/bin/sh
# .claude/hooks/pin-worktree.sh
# Keep Claude Code from auto-removing this linked worktree on exit.
git_dir=$(git rev-parse --git-dir 2>/dev/null) || exit 0
common_dir=$(git rev-parse --git-common-dir 2>/dev/null) || exit 0
[ "$git_dir" = "$common_dir" ] && exit 0      # main worktree: nothing to pin
wt=$(git rev-parse --show-toplevel)
git worktree unlock "$wt" 2>/dev/null          # drop Claude Code's own lock
git worktree lock --reason "pinned by SessionStart hook" "$wt"

In the main worktree --git-dir and --git-common-dir are the same path, so the script is a no-op there. In a linked worktree it swaps the lock.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "sh \"$CLAUDE_PROJECT_DIR/.claude/hooks/pin-worktree.sh\"" }
        ]
      }
    ]
  }
}

Right after claude --worktree starts:

$ git worktree list --porcelain | grep locked
locked pinned by SessionStart hook

/exit leaves the worktree in place, still locked.

Where the settings file has to live

This tripped me up, so here's what I measured:

Settings location	Hook fires in the worktree session?
`.claude/settings.json` committed to the repo	yes (it's in the worktree checkout)
Untracked `.claude/settings.local.json` only in the main checkout	no (the worktree checkout doesn't have it)
A settings file outside the repo (passed with `--settings`)	yes
`~/.claude/settings.json` (user settings)	yes

The worktree session reads project settings from the worktree's own checkout. If you don't want to commit anything, put the hook in your user settings at ~/.claude/settings.json with an absolute script path. The script has no repo-specific logic, so it's safe globally.

Side note from the docs: $CLAUDE_PROJECT_DIR keeps pointing at the main checkout after Claude enters a worktree, while the hook's cwd follows the worktree. That's why the script derives the path from git rev-parse instead of the env var.

Gotchas

Pre-creating the worktree doesn't help

I assumed a worktree I made myself would be left alone. It wasn't. claude --worktree <name> adopts an existing .claude/worktrees/<name> and applies the same exit logic.

Worse: if the branch is named worktree-<name>, commits made before the session don't count as "new", so an unmerged branch gets force-deleted:

$ git worktree add -b worktree-wt-pre4 .claude/worktrees/wt-pre4
$ cd .claude/worktrees/wt-pre4 && echo precious > precious.txt && git add . && git commit -m "precious"
$ claude --worktree wt-pre4    # do nothing, /exit

$ git branch --list worktree-wt-pre4
# empty. No ref points at that commit any more.

The commit object still exists, so git fsck --lost-found can dig it out, but only if you notice. If you hand a hand-made worktree to Claude Code, lock it first.

One-off alternative: name the session

A named session always gets the dialog, even when clean:

Exiting worktree session
This session was named "keepme". Keep the worktree to resume it later, or remove it to clean up.
❯ 1. Keep worktree
  2. Remove worktree

/rename keepme then /exit is the cheapest way to keep a worktree once. You have to remember it every time, which is why I prefer the hook.

Cleaning up later

Claude Code won't touch a worktree you locked, so removal is on you:

git worktree unlock .claude/worktrees/wt-lock
git worktree remove .claude/worktrees/wt-lock
git branch -D worktree-wt-lock

Wrap-up

Claude Code's worktree cleanup is aggressive by design: clean plus unnamed equals gone. The escape hatch is already built in, just not advertised. Claude Code refuses to release a git worktree lock it didn't write, so a re-lock with your own reason, done by hand or by a SessionStart hook, is enough to keep the worktree across sessions.

Links:

Claude Code docs, worktrees: https://code.claude.com/docs/en/worktrees
Claude Code docs, hooks: https://code.claude.com/docs/en/hooks
git worktree manual: https://git-scm.com/docs/git-worktree

Turning Matt Pocock's /implement into a parallel orchestrator in Claude Code

day — Thu, 10 Sep 2026 09:22:15 +0000

I moved my Claude Code workflow from the superpowers plugin to Matt Pocock's skills. The chain /grill-with-docs → /to-spec → /to-tickets → /implement is great, but /implement is deliberately one ticket per session, with a /clear in between. Matt's own docs say batch dispatch and subagent fan-out are "requested repeatedly, and neither exists."

Meanwhile Claude Code already has everything an orchestrator needs: spawn a subagent, get its report, and send it a follow-up that resumes with its previous context intact. That is the orchestrator-subagent pattern from Anthropic's multi-agent coordination patterns post, and it maps onto Matt's tickets almost one to one.

So I kept the planning half of Matt's flow and replaced only the build half with a skill called /implement-orchestrated. Here is how it fits together.

The shape

	`/implement` (Matt)	`implement-spec` (Matt's unshipped draft)	`/implement-orchestrated`
Unit	one ticket per session	whole spec	whole spec
Parallelism	none	implementer subagents in worktrees	`coder` subagents in worktrees, up to N
Review	`/code-review` at the end	`/code-review` at the end	`reviewer` per ticket, then `code-review` + `final-reviewer`
Fix loop	same session	unspecified	SendMessage to the same coder

Four Claude Code features carry the whole thing:

Agent tool with subagent_type: implement-orchestrated:coder (the namespaced form a plugin install gives you; hand-copied into ~/.claude/agents/ it is the bare coder) and isolation: worktree
SendMessage to a finished subagent by name: it resumes from its transcript
worktree.baseRef: which commit subagent worktrees branch from
.worktreeinclude: copy gitignored files into each worktree

The loop

Read the spec and tickets. Build a state table (ticket, blockers, status, coder, branch, worktree) in a file outside the repo, because it has to survive context compaction.
Create the feature branch, record a test baseline, open a draft PR.
Dispatch the frontier (every ticket whose blockers are closed) to coder subagents, up to N at once, each in its own worktree.
When a coder reports, spawn a reviewer. On "Needs fixes", save the findings to a file and send the same coder the path. It already knows the ticket, the code, and what it did; the pointer is enough. Two failed rounds escalate to the human.
Merge with --no-ff, run the full suite, close the ticket, remove the worktree, recompute the frontier, go to 3.
At the end, three gates: Matt's code-review (Standards + Spec), a max-effort bug hunt, and a final-reviewer pass. Then push and mark the PR ready.

The brief each coder gets is three lines:

Ticket: <ticket pointer>. Spec: <spec pointer>. Notes: <notes>/notes.md (read it if it exists).

You are in your own git worktree on your own branch; every command and edit stays inside it. It holds tracked files plus any local config listed in `.worktreeinclude`, so run the project's install step (for example `npm ci`) before the first test. The glossary is `CONTEXT.md` in your worktree; if it is missing, read <main checkout>/CONTEXT.md and <main checkout>/docs/agents/. Build this ticket.

Everything else, the TDD discipline, the report format, lives in the agent definition, not in the message.

The coder agent

The old coder I had was five generic lines. Rewritten to fit Matt's tdd skill, it now carries the two ideas that skill runs on: pre-agreed seams (decide where tests go before writing any) and reporting by context pointer (branch, SHAs, test command) instead of pasting diffs.

---
name: coder
description: Use for coding tasks delegated to a subagent: implementing a ticket or spec slice, fixing a bug, refactoring, writing tests. Works test-first at pre-agreed seams and reports by context pointers. Runs on the latest Opus with max reasoning effort.
model: opus
effort: max
---

You are an implementer executing one scoped coding task from a brief. The plan was settled upstream: build what the brief says, and raise a design objection in your report rather than redesigning as you go.

## Before writing code

- Read the ticket or brief, then the code at the seams it names. When `CONTEXT.md` or `docs/adr/` exist, read the parts that touch this area: use the glossary's terms in names and tests, and flag any ADR your change would contradict.
- Seams are pre-agreed: the brief or ticket names them. When it names none, test at the public boundary where the acceptance criteria are observable, and name that boundary in your report.

## Building

- Work as one vertical slice, red → green: call the Skill tool with "mattpocock-skills:tdd" and follow its loop, one failing test then the minimal code, seam by seam. When the interface shape itself is in question, call the Skill tool with "mattpocock-skills:codebase-design".
- Typecheck often and run single test files as you go; run the full suite once at the end. Done means every acceptance criterion has a passing test at a seam, or a stated reason it cannot.
- Commit on your current branch with a message that references the ticket. Merging, pushing, and the issue tracker belong to whoever dispatched you, unless the brief says otherwise.

## Report

Your final message is the return value; the caller saw none of your tool calls. Report by context pointer: branch, worktree path, commit SHAs, the test command and its result, the seams you tested at, and anything the ticket left ambiguous. Under 200 words; the diff speaks for itself.

isolation: worktree is deliberately not in the frontmatter. The orchestrator passes it per call, so the same agent still works for a plain bug fix.

Two settings that make it work

Worktree base ref. By default a new subagent worktree branches from the remote default branch (origin/main). The orchestrator merges each finished ticket into the feature branch and then dispatches the tickets that depend on it, so with the default, ticket 03's worktree branches from origin/main and never sees ticket 01's merged code: the coder builds on stale code, or re-implements ticket 01 and conflicts at merge. With head, every worktree branches from the current tip of the feature branch:

{
  "worktree": {
    "baseRef": "head"
  }
}

Letting Claude edit ~/.claude/settings.json for you may get refused by the permission classifier (it was in my run), so run this yourself once, then start a fresh session:

python3 -c "import json;p='$HOME/.claude/settings.json';d=json.load(open(p));d.setdefault('worktree',{})['baseRef']='head';json.dump(d,open(p,'w'),ensure_ascii=False,indent=2)"

Gitignored files. A worktree holds tracked files only. My glossary (CONTEXT.md) and tracker config (docs/agents/) are gitignored, so a .worktreeinclude file (gitignore syntax) tells Claude Code to copy them into every worktree it creates:

CONTEXT.md
docs/agents/
docs/adr/
CLAUDE.local.md

List specific paths. Do not list .claude/ wholesale: .claude/worktrees/ holds your other worktrees and would be copied into every new one, recursively, gigabytes at a time. Name the subfolders you need instead (.claude/hooks/, .claude/skills/, .claude/settings.json). And the Agent tool's worktree isolation does not run your PostToolUse hooks, so .worktreeinclude is the only thing that copies untracked files into a coder's worktree.

Things that bit me

User-invoked skills can't be called by the orchestrator. Skills with disable-model-invocation: true (Matt's /implement, /to-spec) throw when called through the Skill tool. That is why the TDD discipline moved into the coder's prompt.
A plugin's agents array is not loaded. The manifest reference documents "agents": [...] in plugin.json, but on Claude Code 2.1.265 the version that declared it registered nothing (claude plugin details said Agents (0)), and the version that dropped the array and relied on the default agents/ directory registered all three (Agents (3)), namespaced.
CLAUDE_CODE_SUBAGENT_MODEL retargets every agent that does not pin a model. It sets the default model for subagents whose definition declares none, and it applies silently: with the env var set globally to opus[1m], final-reviewer — the one gate I want on the session model — started running on Opus. Any agent that must stay on the conversation's model needs model: inherit written out explicitly. That is what plugin v0.1.3 added.
To put every agent on one model, add CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. CLAUDE_CODE_SUBAGENT_MODEL is only a default: a definition's model: and a model passed to the Agent tool still win. With the force flag set (Claude Code 2.1.257 or newer), every subagent runs on that model, built-in Explore and Plan included, and final-reviewer's model: inherit is ignored as well, so point the variable at the model you want the final gate on. I've since put the conversation and every subagent on the same model, so this is what I run now.
The Workflow tool can't continue an agent. Each agent() call there is fresh. The "same coder, previous context" property needs Agent + SendMessage inside a skill.
Worktree cleanup. Claude Code removes a subagent worktree that finished without changes, but keeps one with unpushed commits. Coders commit, so the fix round lands in the same place.
A bare skill name is not the skill you mean. The skill called Matt's review as "code-review". That name resolves to Claude Code's own bundled code-review — and if you have a personal skill at ~/.claude/skills/code-review/, to that instead. The final gate could quietly run a review with no Spec axis while the README promised Matt's two-axis one. Every call now uses the mattpocock-skills: prefix, which fails loudly when the plugin is missing (fixed in 0.1.5 and 0.1.6).
Don't run parallel /implement sessions in one checkout. Matt's docs have a field report of one session's git commit --amend landing on another session's commit. Worktrees are the insurance.

What happened when I ran it

After publishing I ran /implement-orchestrated screenshot-source 3 on the same spec (2026-09-08, on my Chrome extension ryoshumei/add-to-calendar; the result is PR #14).

All 8 tickets closed, zero escalations. 01, 02 and 07 went out three-wide at 06:17; seven tickets were merged by 08:07. Active orchestration time was about 1h50 for tickets 01 to 07, plus about 50 minutes for the last ticket and the final gate.
The same-coder fix loop works. Ticket 07's first review came back Needs fixes (a new Deno test broke the flagless deno test invocation). One SendMessage with the path to the findings file, and the coder committed the fix (8b2a729) on the same branch in the same worktree; round two was Approved. The cwd question from the first version of this post is answered: it stayed put, three times out of three.
Two surprises. Tickets 04 and 05 touched the same files and conflicted at merge; instead of resolving in the main checkout, the orchestrator resumed 04's coder and had it merge the feature branch first. A flaky test traced back to the signed-in fixture leaving a second Supabase client alive; ticket 04's reviewer found the root cause, ticket 06 fixed it, and a maintenance ticket was logged.
What hurt most was the Claude rate limit. coder and reviewer are pinned to Opus with max effort; the eighth coder died at spawn with a 429 session limit. The orchestrator reported instead of hanging, and once allowed to continue it built that docs-only ticket itself, a logged deviation from "the orchestrator writes no feature code".
Numbers: 30 commits on the branch, +4,373 / −299 lines across 42 files. Playwright tests 27 → 89, Deno 86 → 89, final suite green. Subagent tokens about 3.24M in total (coders 1.61M, per-ticket reviewers 0.68M, final gate 0.96M).
Honest footnote: running Claude Code's built-in /code-review max on the branch afterwards produced 23 more findings, 3 of them flagged as security. They are fixed now (5 commits; the suite went 89 → 103 Playwright and 89 → 91 Deno, each finding verified by a separate reviewer), but the orchestrator's final gate should have caught them. The gap is structural rather than bad luck: every gate asked whether the code does what it was asked to do — acceptance criteria, then standards and spec, then whole-branch consistency — and none asked where it breaks. A bug that satisfies all of those walks through. Plugin 0.1.7 adds the missing gate: a max-effort bug hunt in step 6, placed before final-reviewer so the last gate still sees its fixes.

Get it

The skill, the three agents, and install notes:

https://github.com/ryoshumei/implement-orchestrated

claude plugin marketplace add ryoshumei/implement-orchestrated
claude plugin install implement-orchestrated@ryoshumei

Requires Claude Code 2.1.263 or newer; the current plugin version is 0.1.8. Installed as a plugin the agents are namespaced (implement-orchestrated:coder, implement-orchestrated:reviewer, implement-orchestrated:final-reviewer); copied by hand into ~/.claude/agents/ they are the bare coder / reviewer / final-reviewer, and the orchestrator handles both. claude plugin details implement-orchestrated@ryoshumei should list Agents (3).

You also need Matt's plugin installed and /setup-matt-pocock-skills run once per repo; the orchestrator reads the tracker config that step writes.

Shipping an Expo app to the App Store: the landmines nobody warns you about

day — Fri, 31 Jul 2026 20:14:43 +0000

I recently shipped Add to Calendar: AI Events — an iOS app that turns screenshots and text into calendar events — built with Expo SDK 52 and React Native's new architecture. The code is open source (MIT).

The happy path in the Expo docs is genuinely good. This post is about everything that isn't on the happy path: the things that cost me hours, in the order they'll probably cost you hours too.

1. An iOS Share Extension will dominate your build config

The single hardest feature to ship was also the app's core flow: share a screenshot from any app → extension hands it to the main app → AI extracts the event. I used expo-share-intent, which is excellent, but a share extension is a second binary target, and EAS Build needs to be told about it explicitly.

Three things have to agree with each other or the build dies:

// app.json (abridged)
{
  "plugins": [
    ["expo-share-intent", {
      "disableExperimental": true,           // ← don't let the plugin manage appExtensions
      "iosActivationRules": { "NSExtensionActivationSupportsImageWithMaxCount": 1 },
      "iosAppGroupIdentifier": "group.com.addtocalendar.rn"
    }]
  ],
  "extra": {
    "eas": {
      "build": {
        "experimental": {
          "ios": {
            "appExtensions": [{               // ← you declare the target yourself, once
              "targetName": "AddtoCalendarShare",
              "bundleIdentifier": "com.addtocalendar.rn.share-extension",
              "entitlements": {
                "com.apple.security.application-groups": ["group.com.addtocalendar.rn"]
              }
            }]
          }
        }
      }
    }
  }
}

The landmine: if the plugin also injects an appExtensions entry (the default), EAS sees a duplicate and the build fails at the "Read app config" step — before compiling anything, with an error that says nothing about share extensions. disableExperimental: true plus exactly one hand-written appExtensions block was the stable combination. Once it works, commit it and never touch it.

Also budget a second provisioning profile and bundle ID (.share-extension) — EAS handles the signing, but App Store Connect will show the extension as its own "app" in some screens, which is normal and alarming in that order.

2. `patch-package` is not a code smell on mobile — it's a release valve

Two weeks after launch, users shipped me a bug: sharing a screenshot from the iOS markup editor (the pencil icon after you take a screenshot) crashed the share extension. The fix existed upstream in expo-share-intent v4 — but v4 required Expo SDK 53, and I was on 52 with a working, submitted build.

Upgrading an entire SDK to ship a five-line fix is a bad trade the week after launch. Instead:

# hand-edit node_modules/expo-share-intent/…
npx patch-package expo-share-intent
git add patches/

patch-package re-applies the diff on every npm install (via postinstall). The backported fix shipped as v1.0.2 days later, and the SDK upgrade stayed a calm, separate decision. On web I'd call vendoring a dependency a smell; on mobile, where a "dependency upgrade" can mean re-testing every native module, it's how you ship a bug fix this week instead of next month.

3. Your App Store listing should live in git

App Store Connect's web forms are where listing quality goes to die — you can't diff them, review them, or restore them. EAS Metadata fixes this and almost nobody uses it:

eas metadata:pull    # download the live listing into store.config.json
# edit store.config.json: description, keywords, release notes, screenshot sets
eas metadata:push    # upload — creates the new version's metadata in ASC

My store.config.json and screenshots are committed next to the code. Release notes are written in the same PR as the feature. When I pulled the live listing for the first time, I discovered the description had corrupted line breaks from an earlier copy-paste into the web form — it had been live like that for weeks. Listing-as-code caught what eyeballing the form never did.

Two caveats so you don't over-trust it: metadata:push does not attach a build or press "Submit for Review" — those final clicks are still manual (or fastlane/ASC API if you want to script everything).

4. The review prompt: where you call it matters more than that you call it

expo-store-review wraps SKStoreReviewController. Every guide says "throttle it." Fewer mention the two things that actually bit me:

It silently does nothing on TestFlight. By design, Apple suppresses the dialog there. If you're smoke-testing "does my rating prompt fire?", you must test a release build on a simulator/device outside TestFlight, or you'll ship believing it's broken (or worse, that it's not, when it is).

It will collide with your own dialogs. My prompt fires after a successful "event added" alert. Fire both and iOS will drop one on the floor. The fix is sequencing, not timing hacks — ask only after the user dismisses your alert:

Alert.alert('Added', `"${event.title}" added to your calendar.`, [
  { text: 'OK', onPress: () => void recordSuccessfulAddAndMaybeAskForReview() },
]);

The throttle itself: require ≥2 successful adds (proven value), ask at most once per app version, persist both in AsyncStorage, and never let the review path throw into your core flow. Apple additionally caps the system prompt at ~3 shows per year — treat requestReview() as a suggestion, not a call you own.

5. Multiline `TextInput` + a submit button = a keyboard you can't dismiss

A classic that every RN form eventually hits: a multiline input has no "done" affordance, the keyboard covers your primary button, and iOS users — who expect tap-outside-to-dismiss from native apps — get stuck. Three props, all needed:

<TextInput
  multiline
  returnKeyType="done"        // Return key says Done…
  submitBehavior="blurAndSubmit"  // …and dismisses instead of inserting \n
/>
// on the enclosing ScrollView:
keyboardDismissMode="on-drag"     // scrolling tucks the keyboard away
keyboardShouldPersistTaps="handled"

The trade-off is honest: Return no longer inserts newlines. For a paste-mostly input that's right; pasted text keeps its line breaks anyway.

6. Dark mode will look wrong in exactly one place: your modal sheets

If you build semantic colors (label, separator, grouped backgrounds) into a theme hook from day one, dark mode is nearly free — except for modals. iOS grouped backgrounds are pure black in dark mode, and a modal sheet rendered in pure black on a pure-black screen has no visible edge. Native apps solve this with elevated variants; do the same:

// in the modal screen only
const theme = {
  ...baseTheme,
  groupedBackground: baseTheme.elevatedGroupedBackground,
  card: baseTheme.elevatedCard,
};

One remap at the top of the modal, and the sheet reads as a sheet again.

7. Privacy architecture is an App Store feature, not a legal chore

The app has a bring-your-own-OpenAI-key mode. Two implementation decisions made App Review painless and became the listing's selling point:

The key lives in the iOS Keychain via expo-secure-store, is sent only to api.openai.com, and never touches my server. That sentence goes verbatim into the privacy labels, the reviewer notes, and the description — and it's true, which is what makes Guideline 2.3 (accurate metadata) easy.
Account deletion is in-app (Apple requires it if you have accounts at all — budget for it before your first submission, it's a server-side feature, not a button).

One more pre-flight item that surprises people: ITSAppUsesNonExemptEncryption: false in Info.plist saves you an export-compliance question on every single upload.

The boring meta-lesson

Every one of these was discoverable only by shipping. The gap between "runs in Expo Go" and "approved on the App Store" is real but bounded — roughly: one build-config fight (share extension), one process discovery (metadata as code), and a handful of platform behaviors (review prompt, keyboard, dark mode) that each cost an afternoon.

If you're one eas submit away and hesitating: the reviewer is not your enemy, the checklist is finite, and the second submission takes a tenth the time of the first.

The app: Add to Calendar: AI Events — screenshots/text → calendar events. Source: github.com/ryoshumei/add-to-calendar-rn. Questions about any of these landmines welcome in the comments.

DEV Community: day

Claude Code can't use your Max plan's free API credit. OpenCode can.

TL;DR

Why I moved to OpenCode

Connect OpenCode to the credit

What the credit covers

1. Link a Console organization

2. Create an API key

3. Register it in OpenCode

4. Check that it works

Move your Claude Code setup to OpenCode V2

Start with a prompt

What maps to what

CLAUDE.md isn't read

Subagents use different frontmatter

Skills: add only the plugin ones

MCP goes under servers

Hooks split into permissions and plugins

Slash commands are thin wrappers around skills

Claude Code's own tools need translating

What I checked, and what I didn't

Wrap-up

References

Claude Code's usage-limit auto-continue doesn't run in Remote Control sessions. Hooks resume them.

TL;DR

Install in one step

The symptom

The cause

The fix

Checking that it works

Caveats

Versions tested

Claude Code deletes clean worktrees on exit without asking. git worktree lock stops it.

TL;DR

The symptom

What the exit code actually checks

It's documented

Why git worktree lock works

Fix 1: re-lock by hand

Fix 2: automate it with a SessionStart hook

Where the settings file has to live

Gotchas

Pre-creating the worktree doesn't help

One-off alternative: name the session

Cleaning up later

Wrap-up

Turning Matt Pocock's /implement into a parallel orchestrator in Claude Code

The shape

The loop

The coder agent

Two settings that make it work

Things that bit me

What happened when I ran it

Get it

Shipping an Expo app to the App Store: the landmines nobody warns you about

1. An iOS Share Extension will dominate your build config

2. patch-package is not a code smell on mobile — it's a release valve

3. Your App Store listing should live in git

4. The review prompt: where you call it matters more than that you call it

5. Multiline TextInput + a submit button = a keyboard you can't dismiss

6. Dark mode will look wrong in exactly one place: your modal sheets

7. Privacy architecture is an App Store feature, not a legal chore

The boring meta-lesson

`CLAUDE.md` isn't read

MCP goes under `servers`

Why `git worktree lock` works

2. `patch-package` is not a code smell on mobile — it's a release valve

5. Multiline `TextInput` + a submit button = a keyboard you can't dismiss