DEV Community: Gabriel Anhaia

Claude Code Told the Model 'File Unchanged' to Save Tokens. 2.1.317 Removed the Stub

Gabriel Anhaia — Sat, 07 Nov 2026 17:01:22 +0000

Book: AI Agents Pocket Guide
The series: Pocket Guides for Developers — 8 short books on agents, RAG, prompts, observability, events, databases and system design — the whole series
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You delete a few lines in your editor and save. You tell the agent the file changed and ask it to look again. It calls Read and gets back one line: Unchanged since last read.

That is the repro in issue #69876, filed against Claude Code 2.1.185 on June 21, 2026. A Read of the whole file a moment later returned 33 lines, so the edit was on disk. The tool had answered from its own memory of the file. The thread has no reply from a maintainer. A bot labeled it stale on July 19 and closed it as "not planned" on August 2.

On November 3, Claude Code 2.1.317 shipped this line:

Removed the Read tool's "file unchanged since your last Read" stub: reading an unchanged file again returns its content

No reason is given, and no issue is linked.

The stub is gone, but the design question behind it applies to any agent harness that caches tool results. A read cache has to answer two questions, and the reports show it answering only one.

What the stub was and why it existed

The feature arrived in 2.1.86, released March 27: "Read tool now uses compact line-number format and deduplicates unchanged re-reads, reducing token usage". Agents re-read files a lot. They read, edit, then read again to check. Each full read puts the whole file back into the context window, so skipping a repeat read of an unchanged file saves real tokens.

Instead of the file, the model got a short note. Its wording changed across versions. Issue #55042, on 2.1.123, quotes: "File unchanged since last read. The content from the earlier Read tool_result in this conversation is still current — refer to that instead of re-reading." Issue #60722, on 2.1.140, quotes a blunter one: "Wasted call — file unchanged since your last Read. Refer to that earlier tool_result instead." In the terminal you saw the short form, Unchanged since last read.

Read the second wording again. It makes two claims. The file has not changed, and the earlier tool result is still there for the model to look at. Either claim can be false on its own.

Question one: did the file change on disk?

A dedup cache keys each entry by path and keeps something cheap to compare: the modification time, the size, or a hash of the content. On the next read it compares again and returns the stub if nothing moved.

The bug reports show the first claim failing when something other than the agent touched the file. Issue #60684 (2.1.144) got the stub after the user saved a notebook in their editor, then got the real content through a shell cat. Its author's theory is that the check tracked only the agent's own Edit and Write calls; no maintainer confirmed that. A bot closed it for inactivity, as it did #69876. Neither got a fix.

Mtime is a weak signal, because content can change while it stays put. Claude Code's own Edit check hit exactly that: the 2.1.295 release includes "Fixed Edit treating a file as fully read when its contents changed without its modification time advancing". A content hash avoids that, and it is cheap here. Hashing means reading the bytes from disk, which costs almost nothing. The expensive part is sending those bytes to the model, and a hash lets you skip only that part.

A hash has its own blind spot. Issue #45748 (2.1.96) got the stub after switching branches away and back with git checkout, which rewrote the file twice and landed on the same bytes. The reporter says the cache compared content hashes, so it saw nothing change. That issue was also closed by a bot. After an A-to-B-to-A round trip, "unchanged" is only safe if the model can still see A. That is the second question.

The cache stamps "unchanged" from memory. The disk already says otherwise.

Question two: can the model still see the earlier result?

This is the part a disk check can never answer. The stub tells the model to go back to an earlier tool result. That only works if the result is still in the context window.

Two things remove it. A rewind (Esc twice, or /rewind) rolls the conversation back to before the read. Issue #55042 did exactly that, then read five files in parallel: four came back as stubs pointing at results the rewind had just removed. Issue #46749 reported the same after compaction. When the context fills up, Claude Code compacts the conversation into a summary that "keeps your requests and key code snippets". A full file listing is not guaranteed to be one of them.

The workarounds in those threads were Read with an explicit offset and limit, which skipped the dedup, or reading through the shell instead. Both depend on the model noticing that it has been handed a pointer to nothing.

A community hook called read-once hit the same wall from outside. It blocks repeat reads too, and expires its entries after 20 minutes because, in its author's words, "There's no way to detect compaction events from a hook".

Inside the harness you can detect it. Here is a minimal cache that asks both questions. It is an illustration, not Claude Code's code:

import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";

type Seen = { hash: string; epoch: number };
const seen = new Map<string, Seen>();
let epoch = 0;

// Call this whenever compaction or a rewind
// removes earlier tool results from context.
export function contextDropped(): void {
  epoch++;
}

export function read(path: string): string {
  const text = readFileSync(path, "utf8");
  const hash = createHash("sha256")
    .update(text)
    .digest("hex");
  const prev = seen.get(path);
  seen.set(path, { hash, epoch });
  const same = prev !== undefined
    && prev.hash === hash
    && prev.epoch === epoch;
  return same ? "File unchanged since last read." : text;
}

The hash answers question one. The epoch answers question two: any event that drops tool results from context invalidates every entry at once. It is still not complete. A partial read with a different range, a subagent with its own context, or a forked session each need their own answer, and every one you miss sends the model back to a result it no longer has.

Compaction keeps a summary. The full tool result the stub points at is gone.

What the removal costs

The cost is context. Issue #100265 measured it on 2.1.292: a second Read of a 26 KB file returned the full 27,807 characters again, and context went from 70,281 to 83,274 tokens. That is about 13,000 tokens for a file the model had already seen. A long session that re-reads big files fills its window sooner and compacts more often.

That issue also suggests many users stopped getting the stub before 2.1.317 shipped. Its author found no "file unchanged" result in 753 local sessions from 2.1.209 to 2.1.292. A commenter on 2.1.310 found "tengu_read_dedup_killswitch": true in the cached remote config inside their ~/.claude.json, with the stub last appearing in their transcripts under 2.1.286. That is one user's reading of their own config, not an official explanation. The 2.1.317 entry makes the behavior official for everyone.

Run claude --version, and claude update (CLI reference) if you are behind. If you still want fewer repeat reads, ask for line ranges on large files rather than the whole thing. A stale answer cost more than the tokens did: a model working from an old copy of a file writes code against lines that are no longer there.

Review the diff from disk

The model's picture of your repository is whatever came back in its tool results, filtered through compaction. When you review an agent's work, read the diff from git, which comes from the files.

I build Hermes IDE, so weigh this part with that in mind. Hermes runs Claude Code, Codex and other agent CLIs in real terminals, and its review side works from disk. Per the README, every agent turn is saved, so you can diff or restore any single turn, with undo, and the Review Desk (⌘G) shows changes by turn or by file. The same README says Hermes observes "what agents report on purpose and what git shows".

The Review Desk (⌘G) in By turn view for a Claude Code task in orders-api: two turns, turn 1's diff of src/db.ts, the changed-files list and a commit message drafted from the turns.

So if an agent works from a stale copy and writes the old lines back over your edit, the turn's diff in the Review Desk is where you would see your lines being removed, whatever the model believes it read. Clicking that turn in the strip of agent replies shows its changes or restores your files to that point. Hermes does not change what Claude Code's Read tool returns, so it cannot fix the agent's view. In a task with extra folders, that strip tracks changes in the main project only.

If this was useful

The stub was a tool-calling design choice: a tool result that pointed at another tool result and trusted it to still be there. The AI Agents Pocket Guide covers tool design, agent loops and the guardrails around them, which is where bugs like this one come from. It is one of 8 short books in Pocket Guides for Developers, on agents, RAG, prompts, observability, events, databases and system design. Hermes IDE is free, source-available under BSL 1.1, on macOS, Windows and Linux, and not affiliated with Anthropic: download it or read the source.

Find Dead Code With knip, Then Let a Coding Agent Delete It One Package per Worktree

Gabriel Anhaia — Sat, 07 Nov 2026 16:01:55 +0000

Book: Ship It — the pragmatic startup tech stack
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

On August 1, 2012, Knight Capital's order router still held a function that, in the SEC's words, "was not meant to be used." The router misbehaved for the first 45 minutes of trading, and the firm eventually lost more than $460 million.

Your repo's dead code will probably never cost that much. It still gets read, type-checked and shipped, and an agent that finds an old helper may copy it.

Deleting it is the safest job you can hand a coding agent, on one condition: a tool picks the targets and the agent doesn't guess. Most wrong deletions fail the type checker or the tests. The rest are dynamic imports and files loaded by path, and the prompt below tells the agent to leave those alone. The agent adds no behaviour of its own; it removes code a static analyser reports as unused.

Here is the whole loop: knip finds the unused code, jq cuts the report into one slice per package, each slice goes to its own agent on its own branch, and nothing lands until tsc --noEmit and the tests pass.

Step 1: get the list from knip, as JSON

Run knip once by hand first. It reads your package.json, finds entry files through its plugins, and reports unused files, exports, types and dependencies. Knip's handling-issues guide says "a surprising result is usually a real finding or a configuration gap, not a false positive to silence." Fix the gaps before any agent sees the list. Two common ones: "Dynamic import specifiers aren't resolved," and, per the same guide, generated files have to exist before knip can follow them.

When the plain report looks right, ask for JSON:

npx knip --reporter json --no-exit-code \
  --include files,exports,types \
  > knip.json

--include limits the report to the issue types you name. --no-exit-code exits 0 even when there are findings, while config and internal errors still exit 2 (CLI reference). Dependencies are left out on purpose: removing them rewrites the shared lockfile, so they go last, as one task.

The reporter docs describe the shape: one object with an issues array, one entry per file, and a key per enabled issue type. This is their example, trimmed:

{
  "issues": [
    {
      "file": "src/legacy.ts",
      "files": [{ "name": "src/legacy.ts" }]
    },
    {
      "file": "src/math.ts",
      "exports": [
        { "name": "factorial", "line": 12, "col": 14 }
      ]
    }
  ]
}

file is relative to where you ran knip, so in a monorepo every path starts with its package folder. That is what makes slicing by package easy.

Step 2: slice it per package with jq

First, see where the dead code lives. This counts files with at least one finding, per package, assuming a packages/<name>/ layout:

jq -r '.issues[]
  | select(del(.file, .owners)
      | [.[] | length] | add > 0)
  | .file | split("/") | .[:2] | join("/")' \
  knip.json | sort | uniq -c | sort -rn

del(.file, .owners) leaves only the issue arrays (owners shows up when you have a CODEOWNERS file). Summing their lengths drops entries with nothing in them. Files at the repo root show up under their own names.

Now one small script that prints the slice for one package. Commit it to main before you start, because a new git worktree only holds tracked files:

#!/usr/bin/env bash
# scripts/knip-slice.sh packages/api
set -euo pipefail
npx knip --reporter json --no-exit-code \
  --include files,exports,types \
| jq --arg p "$1/" '[.issues[]
    | select(.file | startswith($p))
    | select(del(.file, .owners)
        | [.[] | length] | add > 0)]'

pipefail matters here. Without it, a knip crash would hand jq an empty input, and the pipeline would still report success. The script reruns knip each time instead of reading a saved file, so the agent always sees the current state of its own branch.

The script also gives you a done check. jq -e exits 1 when the last value is false and 4 when there was no valid input at all (jq manual), so this line passes only on an empty slice:

scripts/knip-slice.sh packages/api | jq -e 'length == 0'

One slice per package, one pair of scissors per slice.

Step 3: one package, one agent, one branch

The task prompt does most of the safety work. It names the source of truth, forbids the two shortcuts an agent might take, and says what done means:

Delete dead code in packages/api and nothing else.

Targets: the output of
  scripts/knip-slice.sh packages/api

Rules:
- Delete only what that list names. For an unused
  export, remove it if nothing in its file uses it,
  otherwise drop the export keyword.
- Do not edit any other package.
- Do not add ignore entries to the knip config. If
  a finding looks wrong (dynamic import, public API,
  a file loaded by path), leave it and tell me which
  one and why.
- After each round, run the script again. Deleting
  a file can leave more code unused.

Done when the script prints [] and both
`npx tsc --noEmit` and `npm test` pass.

The "run it again" rule follows knip's own advice: "Findings come in chains, so reducing unused files also reduces unused exports and dependencies." If the deletion is purely mechanical, knip can do it without an agent: knip --fix removes the export keyword from unused exports, and --allow-remove-files lets it delete unused files. The agent earns its place on the chain that follows: the local function nobody calls after its export went away, the test file for a module that no longer exists, the finding that turns out to be a dynamic import.

By hand, each slice gets a worktree and a branch:

git worktree add -b dead-code/api ../app-dead-api
cd ../app-dead-api && npm ci

Then you start your agent in that folder and paste the prompt. Repeat per package.

I build Hermes IDE, so weigh this part with that in mind. In Hermes, ⌘N (Ctrl+Shift+N on Windows and Linux) opens the task sheet. You type the prompt and pick the agent (Claude Code, Codex or another CLI), and the task starts on its own hermes/ branch in its own worktree, with the prompt as the agent's first message. Press ⌘N again for the next package, with the same agent or a different one.

The ⌘N New task sheet in Hermes 2.3.4: agent, project, a new hermes/ worktree, approval mode, model and effort, and the "Hermes will run" preview of the agent command.

Per the Hermes README, new worktrees get their dependencies in seconds, and your own checks can decide when a task is done, so npx tsc --noEmit and npm test can be those checks. The per-repository setup is described in the worktree recipes doc. The package-specific knip check stays in the prompt, because that setup is shared by every task in the repo. If your monorepo uses TypeScript project references, put your own type-check script in place of npx tsc --noEmit.

Step 4: read every deletion, then land

A dead-code branch should mostly remove lines. This lists every file on the branch that gained lines, which is where to look first:

git diff --numstat main...dead-code/api | awk '$1 > 0'

A new // @ts-ignore, or a test rewritten to keep passing, usually shows up in that list. The three dots compare against the point where the branch split off, so work that landed on main in the meantime stays out of the diff.

In Hermes, ⌘G (Ctrl+Shift+G on Windows and Linux) opens the Review Desk. Every agent turn is saved, so you read the deletions turn by turn or file by file, and you can restore any single turn, with undo. A line comment goes back to the agent that wrote that line. The desk also shows risk flags on the changes.

The Review Desk (⌘G) in By turn view: two turns listed, turn 1's diff, the changed-files list, and a commit message drafted from the turns.

Land then commits, opens a pull request or merges locally into the branch the task started from, and if a landing was a mistake, it can be undone.

Leave unused dependencies for last, as one task across the whole repo. In an npm workspace there is one lockfile at the root, so two branches that each remove a dependency both rewrite package-lock.json, and a lockfile conflict is a miserable thing to resolve by hand. After the file and export slices land, run knip with --include dependencies, give that list to one agent, and read its lockfile change line by line in review.

Keep it from coming back

Once the slices are empty, make knip a CI step so new dead code fails the build. Knip exits 1 when it finds at least one issue (CLI reference), so in a GitHub Actions job, after actions/checkout and actions/setup-node, two steps are enough:

- run: npm ci
- run: npx knip

If you can't reach zero yet, --max-issues sets how many issues are allowed before the exit code turns non-zero. Lower it as the slices land.

Hermes is free, source-available under BSL 1.1, and runs on macOS, Windows and Linux. It isn't affiliated with Nous Research, Anthropic, OpenAI or any agent vendor. Everything above except the Hermes steps is plain knip, jq and git, and works with any agent in any terminal.

If this was useful

A knip step in CI is the kind of guardrail that keeps a small team's codebase from filling up with code nobody calls. Ship It is my book about the rest of the road between localhost and production for a small team: hosting, payments, auth, CI/CD and monitoring. If you want to try the agent half of this post, download Hermes IDE, and if it saves you a cleanup, star it on GitHub.

RabbitMQ's Default Prefetch Is Unlimited. One Slow Worker Can Hoard the Whole Queue

Gabriel Anhaia — Sat, 07 Nov 2026 15:01:25 +0000

Book: Event-Driven Architecture Pocket Guide
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Your deploy stops all ten workers, ships, and starts them again. While they were down, 8,000 jobs piled up in a classic queue. The first worker back opens a channel, starts consuming, and the broker pushes it the whole backlog. The other nine come up a few seconds later and find nothing to take. That first worker happens to sit on a busy node and runs at 300 ms a job, so it will need 40 minutes to get through what it holds.

The management UI shows 0 ready and 8,000 unacked. Nothing is stuck in the queue; everything is stuck in one process. On RabbitMQ 4.3 or later, no consumer timeout will take those messages back either, because classic queues no longer evaluate consumer timeouts.

The cause is one missing basic.qos call.

Unlimited is the default

RabbitMQ caps how many unacknowledged deliveries a consumer can hold through the prefetch count set by basic.qos. The consumer prefetch guide says: "A value of 0 is treated as infinite, allowing any number of unacknowledged messages." If your client never sends basic.qos, the broker applies default_consumer_prefetch, and in the RabbitMQ server source that default is {false, 0}: per-consumer, zero, unlimited.

Combine that with how dispatch works. Active consumers on a queue receive messages round-robin, but only consumers with spare capacity are eligible, and an unlimited consumer always has spare capacity. When a backlog exists and one consumer attaches, it is the only eligible consumer, so it gets everything. Even when every worker is connected before the jobs arrive, round-robin hands the slow one its full share up front, and the fast ones go idle once theirs is done.

There is a memory cost too. The acknowledgements guide warns that "automatic acknowledgement mode or manual acknowledgement mode with unlimited prefetch should be used with care," because consumers that take in many messages without acking them grow memory on the node they are connected to. Quorum queues cap consumer prefetch at 2,000 to limit Raft log growth, per the same guide, and 2,000 is still a lot of messages to park behind one slow handler.

With no prefetch limit, the consumer that attaches first takes the backlog with it.

The demo: one slow worker, one fast one

You need Docker Compose and nothing else. The broker is the official RabbitMQ 4.4 image and the client is amqplib running on Node.js 24 (amqplib needs Node 18 or newer, per its package metadata).

# docker-compose.yml
services:
  rabbitmq:
    image: rabbitmq:4.4-management
    environment:
      RABBITMQ_DEFAULT_USER: demo
      RABBITMQ_DEFAULT_PASS: demo
    ports:
      - "15672:15672"
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "-q",
             "check_port_connectivity"]
      interval: 5s
      retries: 20
  demo:
    image: node:24-alpine
    working_dir: /app
    volumes:
      - ./:/app
    environment:
      AMQP_URL: amqp://demo:demo@rabbitmq:5672
    depends_on:
      rabbitmq:
        condition: service_healthy

The script fills a quorum queue with 1,000 jobs, starts a worker that spends 100 ms per job, waits half a second, then starts a worker that spends 10 ms per job. Each worker processes one job at a time, like a handler doing real work would.

// demo.mjs
import amqp from "amqplib";

const URL = process.env.AMQP_URL;
const QUEUE = "jobs";
const TOTAL = 1000;
const PREFETCH = Number(process.argv[2] ?? 0);
const TIMEOUT_MS = Number(process.env.TIMEOUT_MS ?? 0);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
let t0 = 0;

async function fill() {
  const conn = await amqp.connect(URL);
  const ch = await conn.createConfirmChannel();
  await ch.assertQueue(QUEUE, {
    durable: true,
    arguments: { "x-queue-type": "quorum" },
  });
  await ch.purgeQueue(QUEUE);
  for (let i = 0; i < TOTAL; i++) {
    ch.sendToQueue(QUEUE, Buffer.from(String(i)), {
      messageId: `job-${i}`,
    });
  }
  await ch.waitForConfirms();
  await conn.close();
}

async function worker(workMs, s, args = {}) {
  const conn = await amqp.connect(URL);
  const ch = await conn.createChannel();
  ch.on("error", (e) => console.error(e.message));
  await ch.prefetch(PREFETCH);
  let chain = Promise.resolve();
  const onMessage = (msg) => {
    if (msg === null) {
      s.cancelled = true; // the broker cancelled us
      return;
    }
    if (msg.fields.redelivered) s.redelivered++;
    s.held++;
    s.peak = Math.max(s.peak, s.held);
    chain = chain.then(async () => {
      if (s.cancelled) return;
      await sleep(workMs);
      if (s.cancelled) return;
      ch.ack(msg);
      s.held--;
      s.done++;
      s.lastAckAt = (Date.now() - t0) / 1000;
    });
  };
  await ch.consume(QUEUE, onMessage, {
    noAck: false,
    arguments: args,
  });
  return conn;
}

function stats() {
  return {
    done: 0, held: 0, peak: 0, redelivered: 0,
    lastAckAt: 0, cancelled: false,
  };
}

await fill();
const slow = stats();
const fast = stats();
const slowArgs = TIMEOUT_MS
  ? { "x-consumer-timeout": TIMEOUT_MS }
  : {};

t0 = Date.now();
const conns = [await worker(100, slow, slowArgs)];
await sleep(500); // the fast worker comes up late
conns.push(await worker(10, fast));

while (slow.done + fast.done < TOTAL) await sleep(50);
const secs = ((Date.now() - t0) / 1000).toFixed(1);
console.log(`prefetch=${PREFETCH}, all acked after ${secs}s`);
console.table({ slow, fast });
for (const c of conns) await c.close();

Run it once per setting:

docker compose up -d rabbitmq
docker compose run --rm demo npm install amqplib@2.2.1
docker compose run --rm demo node demo.mjs 0
docker compose run --rm demo node demo.mjs 1
docker compose run --rm demo node demo.mjs 10
docker compose run --rm demo node demo.mjs 50

ch.prefetch(0) sends the same "no limit" the broker would assume anyway; amqplib documents that a falsey count means no limit. The peak column is the number to watch: it is how many unacked messages the worker held at its worst.

One Node-specific trap is visible in the code. Delete the chain and call the handler directly, and prefetch stops being a buffer size and becomes your concurrency limit. At prefetch 0, that is 1,000 handlers running at once, which in a real service means 1,000 open database queries.

What the numbers should look like

I haven't run this demo, so here is the arithmetic for what it should print, rounded. The slow worker clears 10 jobs a second and the fast one clears 100. The queue empties once the slow worker's acks plus its buffer plus the fast worker's acks reach 1,000. After that, the fast worker sits idle while the slow one works through whatever it still holds.

Prefetch	Slow handles	Fast handles	Slow peak unacked	Last ack
0	~1,000	~0	~1,000	~100 s
1	~95	~905	1	~9.5 s
10	~105	~895	10	~10.5 s
50	~140	~860	50	~14 s

Your run will move around these with connection setup time and timer jitter. At 0, the slow worker takes the whole backlog before its sibling has finished connecting, and the run takes ten times longer than it needs to. At 50, the last five seconds are the fast worker idling while 50 jobs wait behind a 100 ms handler.

Prefetch 1 looks like the winner here, and that is the demo flattering it. Both containers sit on one Docker network, so the round trip between an ack and the next delivery costs almost nothing. Over a real network, a worker at prefetch 1 waits a full round trip after every ack before it gets its next job, and the RabbitMQ docs say prefetch 1 "will significantly reduce throughput" (acknowledgements guide).

Picking the number

The docs give a starting range, "Values in the 100 through 300 range usually offer optimal throughput and do not run significant risk of overwhelming consumers," and add that finding the right value "is a matter of trial and error" (acknowledgements guide). That range fits fast handlers. For slower ones, reason from two sides.

The floor is keeping the worker busy. You want enough messages buffered to cover one network round trip. A rough rule: divide the round trip by the handler time and add one. A 2 ms handler 20 ms away from the broker wants about 11. A 500 ms handler wants 1 or 2, because the round trip is noise next to the work.

The ceiling is how much work you are willing to strand. Multiply prefetch by the handler time. That product is how long a message can wait behind a slow or dying worker while its siblings sit idle, and it is how long that worker needs to drain on a graceful shutdown. If the answer is longer than your latency budget, the number is too high.

Then check that product against your consumer timeout, which the next section covers. The timeout counts how long a consumer holds a delivery, and a message sitting in your client's buffer counts as held, even if no code has touched it yet.

consumer_timeout only guards quorum queues now

RabbitMQ's consumer timeout limits how long a consumer can keep a delivery unacknowledged. The default consumer_timeout is 1,800,000 ms, which is 30 minutes, and you can override it per queue with the consumer-timeout policy key or the x-consumer-timeout queue argument.

RabbitMQ 4.3, released April 23, 2026, changed where this lives. Timeout handling moved into quorum queues (and the new JMS queues), and classic queues and streams stopped evaluating consumer timeouts. On a 4.3+ broker, a classic-queue consumer with unlimited prefetch and a stuck handler can hold its messages until its connection dies. Before 4.3, a timeout closed the whole AMQP 0-9-1 channel, taking down every consumer on it. Now, if the client supports consumer cancel notifications, the broker cancels only the timed-out consumer and returns its messages to the queue; clients without that support still get the channel closed with PRECONDITION_FAILED (consumers guide).

amqplib advertises consumer_cancel_notify in its connection capabilities, and its docs say a server-side cancel invokes your consume callback with null. That is the msg === null branch in the demo. To try it, give the slow worker a per-consumer timeout, which the quorum queue guide documents as the x-consumer-timeout consumer argument:

docker compose run --rm -e TIMEOUT_MS=10000 demo \
  node demo.mjs 0

By the docs, the slow worker should get cancelled around the 10-second mark, with roughly 100 jobs done, and the fast worker should pick up the rest. Any job the slow worker had started is now in someone else's hands too. Your handler keeps running after the cancel. The broker has just stopped waiting for its ack. The 4.3 release post adds one more detail: a consumer timeout increments a message's acquired-count, not its delivery-count, so timeouts do not eat into the quorum queue delivery limit, which defaults to 20 since RabbitMQ 4.0.

After a timeout, the queue gets the messages back while the old handler is still working.

Redelivery means the handler must be idempotent

When a channel or connection closes with manual acks, "any delivery (message) that was not acked is automatically requeued," and those redeliveries have the redeliver flag set to true (acknowledgements guide), which amqplib exposes as msg.fields.redelivered. The same guide spells out the consequence: "consumers must be prepared to handle redeliveries and otherwise be implemented with idempotence in mind," and "a consumer can receive a message that was previously delivered to another consumer."

Prefetch decides how many messages a crash or a timeout throws back at once. It does not decide whether duplicates happen. A worker can finish the side effect and die before its ack reaches the broker, and the next worker will run the same job again. So key every job and record the key in the same transaction as the side effect. With node-postgres and a processed (id text primary key) table, the insert's rowCount tells you whether this is the first time:

async function handle(msg, client, applyJob) {
  const id = msg.properties.messageId;
  await client.query("BEGIN");
  try {
    const { rowCount } = await client.query(
      "INSERT INTO processed (id) VALUES ($1) " +
        "ON CONFLICT DO NOTHING",
      [id],
    );
    if (rowCount === 1) await applyJob(client, msg);
    await client.query("COMMIT");
  } catch (err) {
    await client.query("ROLLBACK");
    throw err;
  }
}

Ack only after COMMIT returns. A duplicate then inserts nothing, skips the side effect, commits, and gets acked. Don't use the redelivered flag as your dedupe check. It tells you the broker has handed this message out before, not whether your side effect ran.

Before the next deploy, find every consume( call in your codebase and check that a prefetch( call runs on the same channel before it.

If this was useful

Prefetch, acks and redelivery are where a queue-based design meets the real world, and most of the pain shows up as duplicates, stranded work or one consumer doing everything. The Event-Driven Architecture Pocket Guide covers the patterns around that boundary (sagas, CQRS, the outbox) and the traps that come with them, in a format you can read before the next incident review.

Agentjacking: A Fake Sentry Error Became a 'Fix' That Claude Code and Cursor Ran

Gabriel Anhaia — Sat, 07 Nov 2026 14:01:51 +0000

Book: Prompt Engineering Pocket Guide
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You open your coding agent and type the most ordinary request of the week: fix the unresolved Sentry issues. The agent calls Sentry, reads the top issue, and finds a tidy section headed Resolution with one command in a code block. It runs the command. The person who wrote that command has never had access to your code, your Sentry account or your laptop.

That is agentjacking, the attack Tenet Security published in June 2026 and The Hacker News reported on June 12. Tenet found 2,388 organizations with Sentry DSNs it could inject into. In a controlled test against more than 100 organizations, it reports an 85% success rate, with Claude Code, Cursor and Codex all acting on planted errors.

No step in the chain broke a rule. Tenet's phrase is that "every step is authorized."

The key that is meant to be public

Sentry is an error tracker. Your app reports crashes to it using a DSN, a URL with a key in it, and the browser SDK needs that DSN in your frontend JavaScript to work at all. Sentry's own DSN explainer says "DSNs are safe to keep public" because they "only allow submission of new events and related event data" and "do not allow read access to any information."

That's true, and it's the whole problem. Write-only access to your error feed was harmless while only humans read the feed. The same page admits "there is a risk of abusing a DSN," calls it "a rare occurrence," and points to IP blocking and key rotation.

Then the reader changed. The Sentry MCP server connects Claude Code, Cursor, VS Code and any other MCP client to your Sentry account for "searching errors, analyzing performance, triaging issues." Whatever anyone wrote into your error feed is now text your agent reads while it holds a shell.

The chain, hop by hop

Here is the attack as Tenet describes it, with the reason each hop was allowed.

Find a DSN. Tenet lists website JavaScript, Censys searches for Sentry's ingest host, and GitHub code search. Allowed, because the DSN is designed to ship to every browser.
POST one error event. The attacker sends a crafted event to Sentry's ingest endpoint. No authentication beyond the DSN, and Sentry answers HTTP 200. Allowed, because accepting events from strangers is what a frontend DSN is for.
Dress it as Sentry. The payload sits in the event's message field and in the names of its context keys. It is markdown: headings, code blocks, and a fake ## Resolution section with an npx command, laid out to look like the template Sentry's MCP output already uses. Allowed, because an error message is user input and can say anything.
Wait for triage. A developer asks the agent to fix unresolved Sentry issues. Tenet calls it "a plain triage request." Allowed, because the developer set up the MCP server and asked for exactly this.
The MCP server hands it over. The server signs in to your Sentry account over OAuth and returns real Sentry data, which happens to contain the attacker's markdown. Per Tenet, the agent can't tell a planted event from a real crash. Allowed, because the tool call did what it was asked.
The agent runs the "fix." It runs npx on an npm package the attacker controls, with the developer's privileges. In Tenet's tests the package was its own validation package. It checked environment variables, probed the file sizes of ~/.aws/config, ~/.npmrc and ~/.docker/config.json, looked for a VPN, and sent two POSTs to a beacon. Tenet says it did not keep the probe data.

Six hops, each one permitted on its own. The forged one sits in the middle and looks like the rest.

Tenet says the attack "bypasses EDR, WAF, IAM, VPN, Cloudflare, and firewalls" (The Hacker News). There's no malware to scan for. There's an HTTPS request to Sentry, a tool call, and an npx command that looks like a thousand others.

The instinctive fix is a line in your agent's instructions: don't trust what you read in tool output. Tenet tested that. Agents ran the payload "even when explicitly instructed" to ignore untrusted data, and its conclusion is blunt: "You cannot fix this with a better prompt."

Tenet's write-up doesn't say which permission mode the agents ran in, or whether a developer clicked through an approval prompt. It does say sandboxed, CI-based and internal-network agents were also reached, so a sandbox helps only as far as what it denies.

Sentry's answer was one string

Tenet disclosed to Sentry on June 3, 2026, and Sentry replied the same day. It acknowledged the issue and declined to fix the root cause, calling it "technically not defensible" (Tenet). The Cloud Security Alliance's research note names the two root fixes Sentry turned down: authenticated ingestion, and sanitizing event content before the MCP server returns it. What Sentry did ship was a global content filter that blocks one specific payload string.

Be fair to Sentry on the first one. A browser can't keep a secret, so authenticated ingestion from frontend code isn't really on the table. Sanitizing is harder to wave away. A draft pull request in Sentry's MCP repository wraps the attacker-writable parts of get_issue_details (description, culprit, event details) in an <untrusted_event_telemetry> section. As of November 7 it is still an open draft. Even merged, the model still reads everything inside the tag, and nothing stops it following an instruction there.

Tenet picked Sentry, but any MCP tool that returns text an outsider can write works the same way: issue trackers, support inboxes, log search. The CSA note frames the injection pathway as architectural, and that matches the chain above.

Defenses that hold at the last hop

Hops 1 through 5 happen on systems you don't control. Hop 6 happens on your machine, so that's where the controls go: one rule, and two settings that enforce it without depending on the model behaving.

Treat MCP output as data, and enforce it at execution. A Sentry event can tell the agent where a bug is. It should never be the source of a command. Since instructions alone failed in Tenet's tests, that rule has to live in the approval step, where you read the command before it runs.

Keep approvals on for shell commands. In Claude Code's Manual mode, every Bash command asks first, except a built-in read-only set like ls, cat and grep (permissions docs). npx isn't on that list. Rules are checked in the order deny, ask, allow, and a matching ask rule prompts even when an allow rule also matches. So ask rules for package runners keep prompting even after someone saved a broad allow. And don't run triage in bypassPermissions: the docs say to use it only "in isolated environments like containers or VMs." The CSA note makes the same call: if the integration stays on, require human approval before the agent runs commands or installs packages from MCP-retrieved content.

Take the credentials away from the shell. Claude Code's sandbox is off by default, and even when on, its default read access covers "credential files such as ~/.ssh and ~/.aws/credentials." The sandbox.credentials setting denies files and environment variables to sandboxed commands. The network allowlist starts empty, so the first connection to a new host, like a beacon, stops and asks you in Manual or Accept edits mode instead of going out silently (strictAllowlist refuses it outright). It runs on macOS, Linux and WSL2. A project .claude/settings.json with the ask rules, the sandbox and the credential denies:

{
  "permissions": {
    "ask": [
      "Bash(npx *)",
      "Bash(npm exec *)",
      "Bash(pnpm dlx *)",
      "Bash(bunx *)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "credentials": {
      "files": [
        { "path": "~/.aws", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" },
        { "path": "~/.npmrc", "mode": "deny" },
        { "path": "~/.docker/config.json", "mode": "deny" }
      ],
      "envVars": [
        { "name": "AWS_SECRET_ACCESS_KEY", "mode": "deny" },
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

Turning the sandbox on changes the prompting. With autoAllowBashIfSandboxed at its default of true, Claude Code runs other sandboxed Bash commands without asking. Content-scoped ask rules like these npx ones still force a prompt.

Two limits. The docs say "there is no built-in credential deny list," so only what you list is protected. And a Bash rule "isn't a security boundary": Bash(curl *) doesn't stop sh -c 'curl ...'. The ask rules catch the usual form. For the rest, the sandbox limits what the command can read and where it can connect. Cursor and Codex have their own approval and sandbox settings, so ask the same of them: what prompts, what runs sandboxed, and what's denied.

On the Sentry side, the CSA note recommends disabling the MCP integration if you don't need it and rotating exposed DSNs (from the project's Client Keys settings, per Sentry's docs). It also suggests evaluating a server-side relay so the DSN stays out of client code. Scoping the MCP connection to one organization or project hides discovery tools you don't use (Sentry MCP).

Where Hermes fits, and where it doesn't

I build Hermes IDE, so weigh this section with that in mind. Hermes runs every agent in a real terminal, exactly as it would anywhere else. That cuts both ways. The permission rules and sandbox you set in Claude Code apply unchanged, and the agent has the same reach it has in your own shell. A worktree is a folder, not a sandbox: ~/.aws is the same file from every worktree. Hermes alone doesn't stop this attack. The settings above do the credential work.

What it adds is around the approval step. ⌘N (Ctrl+Shift+N on Windows and Linux) starts the triage task on its own hermes/ branch and worktree, and the sheet shows the approval mode (Accept edits in the screenshot below) and a "Hermes will run" preview of the claude command. So you can see you're starting Claude Code in Accept edits, which auto-accepts file edits and common filesystem commands like mkdir and mv, not npx.

The ⌘N New task sheet: Claude Code, the orders-api project, a new hermes/ worktree, Accept edits, model and effort, and the "Hermes will run" preview of the claude command.

When the agent stops to ask about an npx command, the session shows "needs approval," the attention inbox counts it, and ⌘I (Ctrl+Shift+I) jumps to it. You answer in the agent's own terminal. Hermes never answers a permission prompt for you and never types into a terminal on its own.

If a planted "fix" did change files, every agent turn is saved. The Review Desk (⌘G, or Ctrl+Shift+G) shows changes by turn with risk flags, and you can diff or restore a single turn with undo.

The Review Desk (⌘G) by turn: two Claude Code turns, turn 1's diff of src/db.ts, the changed files, and a commit message drafted from the turns.

Hermes is free, source-available under BSL 1.1, and runs on macOS, Windows and Linux (download, GitHub). It isn't affiliated with Sentry, Anthropic, Cursor, OpenAI or Nous Research.

Your error feed is now an inbox

Count the MCP servers your agents use that return text a stranger can write. For each one, check what happens at the moment a command from that text reaches your shell: who reads it, and what it can reach once it runs.

How does your team run Sentry triage with an agent today: approvals on, sandboxed, or MCP off? Tell me in the comments.

If this was useful

Agentjacking works because the model can't tell an instruction it was given from text that only looks like one. If you write the prompts and instruction files your agents run on, the Prompt Engineering Pocket Guide is my short book on how models take instructions, which helps you see where a fake Resolution section gets its pull. And if you want one place to watch which agent is waiting on an approval, Hermes IDE is free.

An Agent That Clicks Your Screen Leaves No Diff. Keep Coding Agents Where Git Can See

Gabriel Anhaia — Sat, 07 Nov 2026 13:01:24 +0000

Book: LLM Observability Pocket Guide
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Your coding agent finishes a task. You open the pull request and read 40 changed lines. You leave a comment on line 12, ask for a fix, and approve the second round. If it breaks next week, you revert one commit. Now picture the same agent finishing a task by clicking through a settings window for six minutes. What do you open to review it?

On October 23, Runtime Wire reported that Cursor's coding agents can now click and type in desktop applications, including Apple's iOS Simulator, and that the agent can pick the tool on its own when a task needs it. Cursor's own docs describe computer use for self-hosted agents. OpenAI documents computer use for Codex and ChatGPT's desktop app on macOS and Windows, through a Computer Use plugin. Anthropic ships a computer use tool in its API with members such as screenshot, left_click and type.

A coding agent's work is reviewable and reversible for one reason: it lands as file changes that git can diff, bisect and revert. A click lands nowhere. Let GUI-driving agents look at the screen and report what they saw. Anything that changes state goes through files on a branch.

What computer use is actually for

The vendors pitch it sensibly. Cursor's headline example is an agent driving the iOS Simulator to test the feature it just built (Runtime Wire). OpenAI's docs list testing desktop or simulator flows, reproducing GUI-only bugs, and "changing app settings that require clicking through a UI" (OpenAI docs).

Two of those three only read the screen. The third writes state. That split is the whole argument.

Testing a flow is a check. The agent taps through signup, sees the button render off-screen, and goes back to the code to fix it. The fix is a file change. The click-through was evidence, and you can throw it away after reading it.

Changing a setting through a UI is a mutation. The result lives in some app's preferences, a cloud console, or a database row behind an admin panel. Unless that app writes it to a file in your repo, git never hears about it.

OpenAI's own docs are honest about this. Computer use actions can affect "app and system state outside your project workspace," so the docs recommend scoped tasks. They also note that desktop app changes "may not appear in the review pane until they're saved to disk and tracked by the project" (OpenAI docs). The review pane only sees what reaches disk.

A diff stays on the page after the work is done. A click doesn't.

Git is the review system you already trust

Look at what you get for free when an agent's work is a set of commits on a branch.

You get a diff. Every changed line is visible, in order, next to the line it replaced. On GitHub you can "hover over the line of code where you'd like to add a comment" and leave feedback on exactly that line (GitHub Docs). That comment is something the agent can act on.

You get undo per step. git revert takes an existing commit and records a new one that reverses it. If the agent made five commits and the third was wrong, you revert the third and keep the rest.

You get search through history. git bisect uses binary search to find the commit that introduced a bug, and git bisect run automates it with any script that exits 0 for good and 1 to 127 (except 125) for bad.

On an agent branch the whole loop is a handful of commands:

git switch -c agent/signup-fix
# the agent works here, one commit per step

git log --oneline main..agent/signup-fix
git diff main...agent/signup-fix

# step three was wrong: undo just that one
git revert <sha-of-step-three>

# something broke and you don't know where
git bisect start agent/signup-fix main
git bisect run npm test
git bisect reset

Try each of those on a GUI session. Clicks have no log you can comment on line by line, a toggled setting in a vendor console has no revert, and six minutes of mouse movement can't be bisected. You might get screenshots in the chat. Cursor's self-hosted docs describe screenshots as the way you confirm the setup works (Cursor docs). A screenshot shows the end state, not the steps that produced it.

The vendors already tell you to fence it

None of this is a secret the vendors are hiding. Their docs say it in plain words.

Anthropic recommends "a dedicated virtual machine or container with minimal privileges," keeping the model away from login details, and "asking a human to confirm decisions that might result in meaningful real-world consequences" (Anthropic docs). It also warns that instructions on webpages or inside images can override yours.

OpenAI says ChatGPT asks before it uses an app, "may also ask for permission before taking sensitive or disruptive actions," and that file edits and shell commands "still follow the sandbox and approval settings" (OpenAI docs). The docs also suggest a dedicated plugin or MCP server when one exists.

Cursor's self-hosted docs say that on macOS the agent "clicks, types, and captures the screen of the desktop session the worker runs in" (Cursor docs). If the worker runs on your own machine, that is your live session, with your apps and your logins.

Approval prompts are the GUI's answer to review. They help. But an approval happens once, before the action, with no reviewable artifact afterwards. A diff happens after the action, stays around, and can be read by someone who wasn't there.

A rule you can paste into your agent instructions

Split the work by what it touches.

Screen-only tasks are fine. Tap through the flow. Reproduce the bug. Check that the dark-mode toggle renders. Ask the agent to write what it saw to a file in the repo, say qa/signup-check.md with the steps and screenshots, so the evidence lands in the diff too.

State-changing tasks go through files on a branch. If the setting can live in a config file, an infrastructure template or a migration, make the agent change the file and let your normal deploy apply it. If the only path is a vendor's admin UI, a human does that click, after reading the PR that explains why.

When in doubt, ask "can I revert this tomorrow?" If the answer is no, it does not belong in an unattended GUI session.

This costs you a little speed on the rare task that really is GUI-only. It buys you the same review loop for every other change your agents make, and that is most of them.

Where Hermes fits

I build Hermes IDE, so weigh this section with that in mind. Hermes is built around the same bet as this post: what an agent did should show up as something git can see.

Hermes observes what agents report on purpose and what git shows. It never answers a permission prompt for you and never types into a terminal on its own (README). Each task can get its own branch and worktree. Every agent turn is saved, so you can diff or restore any single turn, with undo. The Review Desk (⌘G) shows changes by turn or by file, and sends a line comment back to the agent that wrote it. Land commits, opens a pull request or merges locally in one step, into the branch the task started from, and it can be undone.

The Review Desk in By turn view: two turns of a Claude Code task in orders-api, turn 1's diff of src/db.ts, and a commit message drafted from the turns.

It runs several CLI coding agents side by side. It is free to download, source-available under BSL 1.1, on macOS, Windows and Linux, and it is not affiliated with Anthropic, OpenAI or any agent vendor. It can't review a click either. That is the point: keep the agent's changes in files, and the tools you already have will do the rest.

Would you let a coding agent change state through a GUI with no diff behind it? Or does every change in your team go through a branch first? Tell me in the comments.

If this was useful

The question under this whole post is "how do I know what the agent did?" The LLM Observability Pocket Guide answers it for the rest of your LLM stack: traces, evals, cost and the tools that record them, so an agent's run leaves evidence you can read later. It's one of eight short books in Pocket Guides for Developers, covering agents, RAG, prompts, observability, events, databases and system design.

If you run several coding agents on one repo, Hermes IDE keeps each one's work on its own branch, turn by turn (GitHub).

The 2017 S3 Outage Was One Wrong Input. AWS Fixed the Tool, Not the Engineer

Gabriel Anhaia — Sat, 07 Nov 2026 12:01:27 +0000

Book: System Design Pocket Guide: Fundamentals
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

At 9:37 AM Pacific on February 28, 2017, an authorized member of the Amazon S3 team ran a command from an established playbook. It was meant to take a small number of servers out of one subsystem in us-east-1. AWS's own summary of the event says what went wrong next: "one of the inputs to the command was entered incorrectly and a larger set of servers was removed than intended."

S3 in that region was not back to normal until 1:54 PM, per the same summary. That is more than four hours, from one input.

AWS's fix went into the tool. If you let a coding agent run shell commands, that fix applies to you, because an agent enters inputs faster than any engineer does.

What AWS says happened

The S3 team was debugging the S3 billing system, which was running slower than expected. The command was supposed to remove a few servers from a subsystem the billing process used. The bad input removed far more, and some of those servers supported two other subsystems, AWS wrote:

The index subsystem, which manages the metadata and location of every S3 object in the region. GET, LIST, PUT and DELETE requests all need it.
The placement subsystem, which allocates storage for new objects and needs the index to work.

Both needed a full restart. AWS was candid that it had "not completely restarted the index subsystem or the placement subsystem in our larger regions for many years," and after years of growth, the restart and the safety checks on the metadata took longer than expected. The index could serve GET, LIST and DELETE again by 12:26 PM and was fully recovered at 1:18 PM. Placement finished at 1:54 PM, which brought PUT back (AWS).

The damage reached past S3. The summary lists the S3 console, new EC2 instance launches, EBS volumes that needed data from an S3 snapshot, and AWS Lambda among the affected services. Even the AWS Service Health Dashboard could not show individual service status until 11:37 AM, because its admin console depended on S3.

The 2017 fix in one picture: the tool itself refuses to go below the floor.

The fix went into the tool

"While removal of capacity is a key operational practice, in this instance, the tool used allowed too much capacity to be removed too quickly," AWS wrote. Then the change: the tool now removes capacity more slowly, and it refuses when a removal would take any subsystem below its minimum required capacity. AWS's reason, in its own words: "This will prevent an incorrect input from triggering a similar event in the future." It also said it was "auditing our other operational tools to ensure we have similar safety checks."

None of the changes AWS listed is about the person who entered the input. The tool was changed so the same mistake fails safely the next time anyone makes it.

The rest of the list was about recovering faster. AWS moved up its work to split the index subsystem into smaller cells, and it moved the Health Dashboard's admin console to run across multiple regions.

Read as a design rule, it fits in one line: a destructive tool should cap how much it does per run and refuse to cross a floor, whatever input it gets.

Your agent types faster than you do

A coding agent runs commands you didn't type, built from inputs it worked out on its own. Usually that is fine. But the S3 failure mode is one an agent can reproduce well. An agent that passes 20 where the runbook meant 2, or acts on whatever cluster your kubeconfig currently points at, is the S3 scenario again: an authorized operator, a known command, one bad argument, and no pause before it runs.

The approval prompt helps only while you read it. By the fortieth prompt of an afternoon, approving on reflex is easy. So the first guard should not depend on your attention. Put it in the script.

Put the floor inside the script

Here is the AWS fix as a small wrapper around kubectl scale. It refuses to remove more than MAX_STEP replicas per run, refuses to go below MIN_REPLICAS, won't start without an explicit cluster context, and only prints the command unless you pass --apply:

#!/usr/bin/env bash
# scripts/scale-down.sh DEPLOYMENT COUNT [--apply]
set -euo pipefail

deploy="${1:?deployment name}"
remove="${2:?replicas to remove}"
mode="${3:-}"

ctx="${KUBE_CONTEXT:?set KUBE_CONTEXT}"
MIN_REPLICAS="${MIN_REPLICAS:-3}"
MAX_STEP="${MAX_STEP:-2}"

case "$remove" in
  ''|*[!0-9]*) echo "COUNT must be a number" >&2; exit 2 ;;
esac

current=$(kubectl --context "$ctx" get deployment "$deploy" \
  -o jsonpath='{.spec.replicas}')
target=$(( current - remove ))

if (( remove > MAX_STEP )); then
  echo "refusing: $remove is more than MAX_STEP=$MAX_STEP" >&2
  exit 1
fi
if (( target < MIN_REPLICAS )); then
  echo "refusing: $current -> $target is below" \
       "MIN_REPLICAS=$MIN_REPLICAS" >&2
  exit 1
fi

cmd=(kubectl --context "$ctx" scale deployment "$deploy"
  --current-replicas="$current" --replicas="$target")

if [[ "$mode" != "--apply" ]]; then
  echo "dry run: ${cmd[*]}"
  exit 0
fi
"${cmd[@]}"

Both AWS changes are here. MAX_STEP is "remove capacity more slowly": a 20 typed where 2 was meant gets refused instead of applied. MIN_REPLICAS is the floor. KUBE_CONTEXT has no default, and both kubectl calls pass it as --context, so the script never acts on whatever cluster your kubeconfig happens to point at. Export it in the shell you start the agent from, so the agent's command stays a plain ./scripts/scale-down.sh api 2. --current-replicas is a precondition from kubectl itself. The scale only goes through if the deployment still has the replica count the script just read, so a change made in between makes it fail rather than land on a stale number. The dry run is the default, so an agent's first attempt shows you the exact kubectl line it would run. I haven't run this script against a cluster myself, so set the floor for your own deployment and try it on a staging one first.

The same shape fits most destructive commands an agent might reach for: a database reset that refuses when the connection string points anywhere but localhost, a cleanup job that caps deletions per run, a migration runner that won't drop a table without --apply. The input can be wrong, so the tool checks it.

Deny rules are the second layer

Next, steer the agent to the wrapper and away from the raw command. In Claude Code, permission rules go in .claude/settings.json, and the docs say "Rules are evaluated in order: deny, then ask, then allow":

{
  "permissions": {
    "allow": ["Bash(./scripts/scale-down.sh *)"],
    "ask": ["Bash(./scripts/scale-down.sh * --apply)"],
    "deny": [
      "Bash(kubectl scale *)",
      "Bash(kubectl delete *)"
    ]
  }
}

Dry runs go through without a prompt. Anything ending in --apply matches the ask rule and prompts, even though it also matches the allow rule, because ask is checked first. Raw kubectl scale and kubectl delete are refused.

Codex has the same idea in rules files, for example ~/.codex/rules/default.rules. When several rules match, the most restrictive decision wins: forbidden, then prompt, then allow. OpenAI marks rules as experimental.

prefix_rule(
    pattern = ["kubectl", "scale"],
    decision = "forbidden",
    justification = "Use scripts/scale-down.sh",
)

To see how Codex classifies a command before you trust the rule, the docs give a checker. Here it is pointed at the rule above:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- kubectl scale deployment api --replicas=0

The caveat comes from Anthropic's own page: a deny rule "covers the invocation Claude usually produces and isn't a security boundary around the program." Its example is that Bash(rm *) stops rm -rf build/ but not /bin/rm -rf build/ or bash -c 'rm -rf build/'. For enforcement that doesn't depend on the command text, the same docs point to sandboxing.

So neither layer is complete alone. The rule steers the agent to the script. The script refuses a bad number when it is used. If an agent should never be able to scale production at all, give it credentials that can't. That puts the floor outside the agent entirely.

Read what the agent ran

I build Hermes IDE, so weigh this section with that in mind. Hermes runs each agent (Claude Code, Codex and others) in its own real terminal, so the agent's own permission prompts and rules still apply; Hermes doesn't replace them. It never answers a permission prompt for you and never types into a terminal on its own.

In the ⌘N sheet (Ctrl+Shift+N on Windows and Linux) you pick the agent, model, effort and account per task, and the task starts on its own hermes/ branch and worktree, with the task as the agent's first prompt.

The ⌘N New task sheet in Hermes 2.3.4: agent, project, a new hermes/ worktree, the Accept edits approval mode, model and effort, and a preview of the claude command Hermes will run.

When an agent stops on an approval prompt, it counts in the attention inbox, and ⌘I (Ctrl+Shift+I) jumps to the agent that has waited longest. You answer in that agent's terminal, where its prompt shows the command it wants to run. For a prompted command, that is your last look at the input before it runs.

After the fact, the Review Desk (⌘G, or Ctrl+Shift+G) shows what changed by turn or by file, with risk flags. Every agent turn is saved, so you can diff or restore a single turn, with undo.

The Review Desk (⌘G) by turn in Hermes 2.3.4: two turns of a Claude Code task, turn 1's diff of src/db.ts, the changed files and a commit message drafted from the turns.

Be clear about the limits. Hermes observes what agents report and what git shows. It doesn't block commands, so the deny rule and the floor in your script are still the guards. Restoring a turn puts files back in your worktree; it won't bring back replicas an agent scaled away. Hermes is free, source-available under BSL 1.1, and runs on macOS, Windows and Linux. It is not affiliated with Nous Research, Anthropic, OpenAI or any other agent vendor. Download it or read the code on GitHub.

Which destructive script in your repo would an agent find first, and does it have a floor? Tell me in the comments.

If this was useful

The S3 summary is really a capacity story: two subsystems had a minimum below which a whole region stopped serving, and the tool that removed servers didn't know where that line was. My System Design Pocket Guide: Fundamentals covers those core building blocks for scalable systems, so you can see where the floors in your own system sit before a script, or an agent, finds them. If you run several agents at once, Hermes IDE is where I keep an eye on which of them is waiting on me.

Exhale: A Breathing Guide That Reads Your Breath While Claude Code Works

Gabriel Anhaia — Sat, 07 Nov 2026 11:27:26 +0000

This is a submission for the Presage SmartSpectra SDK Challenge.

You hand Claude Code a task. It says "Elucidating…" and the spinner starts. For the next two minutes you watch it. Shoulders up, jaw set, breath shallow, eyes locked on a terminal that isn't asking you for anything.

That waiting time is the most common moment in AI-assisted coding, and it's dead time. Exhale turns it into a minute of slow breathing, with a twist: the horizon on screen is your own breathing, read live from an ordinary webcam by the Presage SmartSpectra SDK. No wearable, no chest strap.

What I Built

Exhale is a small desktop app that listens for your coding agent. It's built on Electron and tested on macOS; the SDK also ships Windows and Linux runtimes.

You send Claude Code a prompt.
If the run lasts longer than 10 seconds, a small card rises in the corner of your screen. It's a sky at dusk.
A sun climbs while you breathe in and sinks while you breathe out: 4 seconds in, 6 out, six breaths a minute.
The horizon the sun sinks behind is your own breathing, from the SDK's chest waveform.
When the agent finishes, the camera turns off and the card shows a short recap.

Short runs never turn the camera on. In daily use you don't click anything; the first time, the card asks before it uses the camera. It also works with any long command through exhale run -- npm test.

Demo

Every reading in the video comes from one live session with the real SDK. In that run Claude worked for 87 seconds, the guide ran for 77, my breathing settled at 6 to 7.4 breaths a minute, and I was in sync with the guide for 30 of the 51 seconds Exhale could score (59%; scoring starts once the breathing waveform arrives). The narrator voice is AI-generated; the footage and the numbers are not.

Code

github.com/gabrielanhaia/exhale: setup in the README, plus a Docker setup with a simulated sensor so you can try the whole flow without a camera or an API key. The repo has 34 unit and integration tests and 8 Playwright tests that drive the real Electron app.

How It Responds to Human Signals

Exhale requests four metrics from the SDK and nothing else:

Signal	What Exhale does with it
`CHEST_BREATHING` waveform	Draws the horizon, and scores how closely you follow the guide
`BREATHING_RATE`	Breaths per minute in the recap
`BLINKING`	Suggests a 20-second look-away when you stop blinking
`TALKING`	Pauses the guide while you speak

Following the guide. Every second, Exhale takes the last 20 seconds of your chest waveform, resamples it to 10 Hz and compares its shape with the guide curve. The score is the best Pearson correlation over a lag of 0 to 2 seconds, because people follow a visual cue a little late. It uses the absolute value, since the SDK's trace is in arbitrary units and Exhale doesn't assume whether an inhale goes up or down. At 60% or above, the card's text turns gold and the sun's glow widens.

Blinks. Rising edges in the blink stream give a rolling blinks-per-minute over 60 seconds. Below 8 a minute, after at least 45 seconds of face time, the card suggests looking at something far away. At most once every five minutes.

Talking. The guide pauses only when most of the last 1.5 seconds of talking detections are confident ones, so a flicker of the mouth doesn't stop it.

The plumbing.

Claude Code hooks (UserPromptSubmit, Stop, SessionEnd) POST to a local server on 127.0.0.1. The hook skips runs where Claude Code reports the session as unattended (CLAUDE_CODE_SESSION_ATTENDED=0). I checked that a headless claude -p run sets it, so scheduled jobs don't turn the camera on.
Each run gets a fresh child process that owns the SDK, with useCamera() and explicit capture settings (720p at 30 fps).
The child streams small frames over IPC to a session state machine (idle → pending → active → summary). The UI renders from Server-Sent Events.

The SDK hands over protobuf packets. This is the function in src/engine/sdk-engine.js that turns each one into the small frame the rest of the app understands:

function toFrame(m) {
  const b = m.breathing || {};
  const f = m.face || {};
  const sec = (x) => tsToSec(x.timestamp);
  return {
    trace: (b.upperTrace || []).map((x) => ({
      t: sec(x), v: x.value,
    })),
    rate: (b.rate || []).map((x) => ({
      t: sec(x), value: x.value, stable: !!x.stable,
      confidence: x.confidence,
    })),
    blinks: (f.blinking || []).map((x) => ({
      t: sec(x), detected: !!x.detected,
    })),
    talking: (f.talking || []).map((x) => ({
      t: sec(x), detected: !!x.detected, stable: !!x.stable,
    })),
  };
}

Four things the SDK taught me

These came up while testing on real hardware (Node SDK 3.4.0, macOS on Apple Silicon).

A second sdk.on('metrics') replaced the first. I added a debug logger as another metrics listener, and the handler that fed the UI went quiet. No error, just a flat horizon. Keep one handler per event and do everything in it. There's now a regression test for this.
The metric streams start at different times. In my logs, blink detections arrived from the first packet and the breathing waveform about 20 seconds later; the breathing rate needs a 30-second window on top of that. The card says "Reading your breathing…" until the waveform shows up. toFrame keeps the SDK's timestamps; the session then lines each batch up by when it arrived, keeping the spacing between samples, instead of assuming every stream shares one clock.
Frame rate matters more than resolution. My 4K webcam, in a fairly dim room, kept falling under the frame rate the SDK needs, and the SDK said so through its validation status. During one of those sessions the native pipeline also stopped with an OpenCV assertion about mismatched image sizes, and the whole app went down with it. Now each run's SDK lives in its own process: a crash ends that run with a clear message, and the app stays up. An iPhone through Continuity Camera, in the same room, gave no frame-rate warnings.
The talking detector is sensitive. During my sessions the guide kept pausing while I wasn't speaking; small mouth movements were enough to trigger it. That's why the rule above needs a sustained, confident signal.

Prize Categories

Best Thoughtful Real-World Use: it fits a moment developers already have dozens of times a day, asks before it uses the camera, runs only during that moment, stores nothing by default, and never pretends to be a medical tool.
Most Creative or Delightful Use: the breathing signal isn't shown as a number on a chart. It becomes the landscape the guide's sun sets behind.

Consent and Data Handling

Consent. The first time a long run starts, the card explains what will happen and asks before the camera is used. Until you click "Turn on camera", it stays off. You can withdraw consent from the Exhale window at any time, which turns the camera off immediately. On macOS the system camera prompt appears once as well.
When the camera is on. Only while an agent run is in progress and the card is showing. The card says "camera on" and the menu-bar item shows a dot. "Turn off camera" stops it at once. When the run ends, the camera is released. Unattended runs never trigger it.
Where video goes. Frames go from the camera into the SmartSpectra SDK inside a process Exhale starts for that run. Presage's README says the SDK computes the vitals on the device. Exhale never writes video or images to disk and never sends them anywhere.
What leaves the computer. In my SDK logs, the SDK contacts Presage to check the API key, verify usage and fetch its models. Its optional aggregate telemetry is described in Presage's telemetry docs. Exhale switches it off (enableTelemetry: false). Exhale has no analytics of its own and doesn't use the SDK's optional LLM Insights.
What is stored, and for how long. By default one file, ~/.exhale/settings.json: when you gave consent, your history preference and your chosen camera. History is opt-in. When it's on, each run adds one summary line to ~/.exhale/history.jsonl (duration, percent with the guide, start and end breathing rate, look-away reminders). No waveforms, no video. Both files are readable only by your user. They stay until you delete them: "Delete all Exhale data" removes both, and switching history off deletes the history file.
Sharing. None. The local server listens on 127.0.0.1 only and rejects requests from web pages (custom header plus Origin check) and from non-loopback host names (DNS-rebinding guard).
Not medical. Exhale is a breathing exercise and a screen-break reminder. It doesn't diagnose, treat or monitor any condition, and it isn't meant for health decisions. It never runs covertly: the camera works only after consent, only during your own agent runs, with a visible indicator.

Agent Session

I built Exhale with Claude Code, in one long session inside Hermes IDE. I'm not embedding the transcript: it contains local machine paths and personal details that I won't publish. The repo history shows how it came together.

If you spend your days waiting on agents too, try it for a week and tell me what your recap says. If you build with agents and want the patterns behind long-running tool loops, my AI Agents Pocket Guide covers them.

Book: AI Agents Pocket Guide: Patterns for Building Autonomous Systems with LLMs
Also by me: Thinking in Go (2-book series): Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub, an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Anthropic's Agent Memory Study: Rules on What to Save Cost Claude Much of the Gain

Gabriel Anhaia — Sat, 07 Nov 2026 11:01:24 +0000

Book: RAG Pocket Guide
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Give Claude Opus 4.7 a folder it can keep notes in between sessions, and its score on a database question task rises from 0.383 to 0.700. Tell it to record only its failures, and it loses much of that boost. Both results are in The components of agent memory, a post Anthropic's engineering team published on November 6, 2026.

The post is research, not a launch: it announces no new model or API feature (Anthropic). It does link two recipes, a dreaming cookbook and a knowledge-wiki quickstart, and it builds on the Dreams endpoint, which is in research preview for Claude Managed Agents. If you run long-lived agents, or let Claude Code keep a MEMORY.md, the findings map onto choices you already make.

What Anthropic measured

The main benchmark is the database task from CL-Bench 1.0. In Anthropic's words, the task "asks Claude to answer a series of questions by looking up information in a database." Each question arrives in a fresh session, and the only thing that carries over is a memory directory that persists between sessions (Anthropic).

Mean reward, stateless baseline against a memory store, as reported in Anthropic's post:

Model	No memory	Memory store
Opus 5.5	0.655	0.838
Sonnet 5.5	0.644	0.833
Opus 5	0.564	0.828
Opus 4.7	0.383	0.700
Sonnet 5	0.306	0.610
Sonnet 4.6	0.330	0.364

Sonnet 4.6 is the outlier. The post says it "often didn't read files from its memory directory and failed to test its theories." Prompting it to read its memory files before answering, and then to test its theories, "nearly doubled its benchmark score," to 0.641 (Anthropic; ai-tldr summary).

A memory directory the model never opens is just disk usage. If an older model seems not to benefit from memory, check that it reads its notes before you drop the idea.

Four layers, and the top one stays small

The post describes memory as a hierarchy (Anthropic):

Transcripts: "a searchable event log" of the agent's sessions.
Memory notes: "salient observations written by Claude."
Representations: structures such as wikis, "a collection of pages written and maintained by Claude."
Injected context: material "loaded into every session."

Four layers of agent memory, as Anthropic describes them. Only the small top layer loads into every session.

The cost sits at the top. "Injected memories use up valuable tokens, and an incorrect note can be carried into every session," the post warns, adding that "Loading a note also doesn't guarantee that Claude acts on it." Its conclusion: "the top layer of the memory hierarchy has to stay relatively small" (Anthropic).

Claude Code already caps that layer. Its memory docs put auto memory in ~/.claude/projects/<project>/memory/, with a MEMORY.md index, and state: "The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation." Claude moves detail into separate topic files and reads them when it needs them (Claude Code docs).

Say what memory is for, not how to use it

The finding that cuts against instinct is about steering. A rule like "only record what went wrong" looks like good engineering. In Anthropic's runs it backfired: told to record only failures, "both Opus 5 and Opus 4.7 lost much of the performance boost that memory gave them" (Anthropic).

The post sums it up as "it helps to tell Claude what memory is for, but not how to use it," and adds: "For stronger models, giving them freedom to judge salience was more effective than setting fixed rules in advance." With frontier models, Anthropic says it typically gives "simple guidance to create memory notes" when a person asks for one or when something is clearly worth remembering, and leaves that call to Claude (Anthropic).

The Pokémon Red runs in the same post show the shift across generations. Sonnet 3.7 wrote 413 memory files across 225 folders and earned one badge. Fable 5 wrote nine files in two folders plus a global.md, and earned four (Anthropic). In that comparison, fewer notes went with more progress.

The catch is that the right amount of steering depends on the model: Sonnet 4.6 needed explicit instructions just to read its memory. Test your own memory prompt on your own tasks instead of copying anyone else's.

Dreaming: an offline pass that fixes the notes

Notes go wrong. The post says "Claude can make incorrect predictions or write rules to memory that are wrong from the start." Anthropic's answer is dreaming, "reflecting on logs to fix mistakes or produce new notes and representations," and "Dreaming gives Claude a way to test its notes against the original transcripts" (Anthropic).

In the Pokémon run, dreaming corrected a wrong location note, and the agent reached Cerulean City at action 1,935. The runs with uncorrected memory and with no memory never got there (Anthropic).

The wiki experiment is the one closest to retrieval work. Claude built a wiki over a Stainless corpus of "about 350,000 files, roughly 420M tokens" and answered 25 graded questions. Wiki alone rose from 13% to 48% of graded criteria as dreaming went from 2 to 128 sessions. With search, "Claude's aggregate score rose from 54% to 61% as that wiki grew," against 53% for search alone, and the pair "saved about 20,000 tokens per question." The costs are in the post too. On a separate legal-brief task, "the wiki grew larger than the documents themselves," and dreaming in general "requires compute" (Anthropic).

Dreaming, in Anthropic's sense: an idle-time pass that checks notes against transcripts and rewrites the wrong ones.

On Managed Agents, dreaming is an API call. The Dreams docs describe an asynchronous job that reads a memory store plus 1 to 100 past sessions and writes a new, reorganized store: "The input store is never modified, so you can review the output and discard it if you don't like the result." Dreams need the dreaming-2026-04-21 beta header (the SDK sets it), "typically take minutes to a few hours," and bill at standard token rates for the model you pick (Dreams docs).

This is the Python call from those docs, reflowed to fit. store_id and the session IDs come from your own Managed Agents runs:

import anthropic

client = anthropic.Anthropic()

dream = client.beta.dreams.create(
    inputs=[
        {"type": "memory_store",
         "memory_store_id": store_id},
        {"type": "sessions",
         "session_ids": [session_a, session_b]},
    ],
    model="claude-opus-5-5",
    instructions=(
        "Focus on coding-style preferences; "
        "ignore one-off debugging notes."
    ),
)
print(dream.id)

I haven't run the Dreams API or the cookbooks myself.

What to change in your own agent setup

Keep what loads into every session short. In Claude Code that is the top of MEMORY.md plus your CLAUDE.md files, and the docs say to "target under 200 lines per CLAUDE.md file" (Claude Code docs).
Tell the agent what its memory is for, drop rules about what to save, and compare scores on your own tasks.
Check that the model reads its notes. In Claude Code, messages like "Recalled 2 memories" mean Claude is reading from the memory directory, and /memory opens the auto memory folder so you can see what is in it (Claude Code docs).
Audit notes against what happened. Auto memory files "are plain markdown you can edit or delete at any time" (Claude Code docs), and a wrong one reaches every session until someone fixes it.
If you dream, aim it at what changes. The post suggests to "focus dreaming on information that's likely to change" and to "carefully tune the cadence of dreaming" (Anthropic).

I build Hermes IDE, so weigh this with that in mind. Hermes has a top layer of its own: per its README, "facts and pinned files saved for a project reach every later session's agent, also after a restart." Anthropic's rule applies there too. Keep pins few and correct, because each later session's agent gets them.

How much does your agent write to memory today, and when did you last open MEMORY.md and read it?

If this was useful

I build Hermes IDE: free, source-available (BSL 1.1), on macOS, Windows and Linux, for running Claude Code, Codex and other agents side by side, each on its own branch. It's on GitHub, and it isn't affiliated with Nous Research, Anthropic or OpenAI.

The wiki result is a retrieval result: a structured layer on top of search beat search alone and spent fewer tokens per question. The RAG Pocket Guide covers the search half of that, from chunking to reranking, so the pages your agent pulls are the right ones.

Import a 1M-Row CSV Through One Use Case: a Generator Adapter, No Eloquent in the Loop

Gabriel Anhaia — Sat, 07 Nov 2026 10:01:35 +0000

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Call file() on a 1M-row CSV and PHP builds a million strings before the first email check runs. In plenty of Laravel apps, that email check lives inside an Artisan command's handle(), and so does every other business rule for the import, including the "skip rows with no name" patch someone added after a bad Monday. Then product asks for the same import from an upload form, and the rules can't leave the command without copy-paste.

The command usually looks like this:

public function handle(): int
{
    $lines = file($this->argument('path'));
    foreach (array_slice($lines, 1) as $line) {
        [$email, $name, $country] = str_getcsv($line, ',', '"', '');
        if (! filter_var($email, FILTER_VALIDATE_EMAIL)) {
            continue;
        }
        Customer::create(compact('email', 'name', 'country'));
    }
    return self::SUCCESS;
}

The problems are all visible. file() reads the entire file into an array, so the whole CSV sits in memory before any row is checked. create() inserts one record per call and returns a model instance, and every call goes through the model lifecycle events. And the validation rules belong to an Artisan command, which is the one place no other caller can reach them.

The fix below moves the rules into a plain ImportCustomers use case. A generator feeds it rows, and a batch-insert port does the writing. The code targets PHP 8.3+, because it uses typed class constants. The snippets skip namespace, use and declare(strict_types=1) lines to stay short; put each class in its own PSR-4 file.

One row in flight at a time. The port writes in batches of 500.

The use case: plain PHP, typed results

Start with the inside. The use case knows nothing about files, HTTP or Eloquent. It takes an iterable of rows keyed by record number and returns a summary.

final readonly class NewCustomer
{
    public function __construct(
        public string $email,
        public string $name,
        public string $country,
    ) {}
}

enum RowStatus
{
    case Accepted;
    case Rejected;
}

Each row produces a RowResult. The constructor is private, so the only ways to build one are the two named constructors, and a rejected row can't carry a customer:

final readonly class RowResult
{
    private function __construct(
        public int $line,
        public RowStatus $status,
        public ?NewCustomer $customer = null,
        public ?string $reason = null,
    ) {}

    public static function accepted(int $line, NewCustomer $c): self
    {
        return new self($line, RowStatus::Accepted, $c);
    }

    public static function rejected(int $line, string $why): self
    {
        return new self($line, RowStatus::Rejected, reason: $why);
    }
}

The port is one method. It speaks in domain objects. Nothing in it knows the table's column names:

interface CustomerRepository
{
    /** @param list<NewCustomer> $customers */
    public function insertBatch(array $customers): void;
}

The summary counts everything but keeps only a sample of rejections, so a file full of garbage can't grow it without bound:

final class ImportSummary
{
    public int $accepted = 0;
    public int $rejected = 0;
    /** @var list<RowResult> */
    public array $samples = [];

    public function reject(RowResult $r, int $keep): void
    {
        $this->rejected++;
        if (count($this->samples) < $keep) {
            $this->samples[] = $r;
        }
    }
}

The use case batches accepted rows and flushes them whenever the batch fills. The batch size is a constructor argument with a default of 500, because the right number depends on the database behind the port:

final class ImportCustomers
{
    private const int SAMPLES = 50;

    public function __construct(
        private readonly CustomerRepository $customers,
        private readonly int $batchSize = 500,
    ) {}

    /** @param iterable<int, list<?string>> $rows */
    public function handle(iterable $rows): ImportSummary
    {
        $summary = new ImportSummary();
        $batch = [];

        foreach ($rows as $line => $fields) {
            $result = $this->check($line, $fields);
            if ($result->status === RowStatus::Rejected) {
                $summary->reject($result, self::SAMPLES);
                continue;
            }
            $batch[] = $result->customer;
            if (count($batch) === $this->batchSize) {
                $this->flush($batch, $summary);
                $batch = [];
            }
        }
        if ($batch !== []) {
            $this->flush($batch, $summary);
        }

        return $summary;
    }

    private function flush(array $batch, ImportSummary $s): void
    {
        $this->customers->insertBatch($batch);
        $s->accepted += count($batch);
    }
}

The rules live in one private method on the same class:

/** @param list<?string> $fields */
private function check(int $line, array $fields): RowResult
{
    if (count($fields) !== 3) {
        return RowResult::rejected($line, 'expected 3 columns');
    }
    [$email, $name, $country] = array_map(
        fn (?string $v): string => trim((string) $v),
        $fields,
    );
    if (filter_var($email, FILTER_VALIDATE_EMAIL) === false) {
        return RowResult::rejected($line, 'invalid email');
    }
    if ($name === '') {
        return RowResult::rejected($line, 'missing name');
    }
    if (preg_match('/^[A-Z]{2}$/', $country) !== 1) {
        return RowResult::rejected($line, 'bad country code');
    }
    $customer = new NewCustomer(
        strtolower($email), $name, $country,
    );
    return RowResult::accepted($line, $customer);
}

Every row comes back as a RowResult, accepted with a NewCustomer or rejected with a reason. The only state that lives across rows is two counters, at most 50 samples and at most one batch of pending customers. That ceiling is what the memory test further down checks.

The driving adapter: a generator over fgetcsv

The PHP manual describes generators as a way to feed a foreach "without having to build an array in memory ahead of time". That is the whole job of the CSV side: hand over one record before reading the next.

Most streaming-CSV examples reach for SplFileObject. Check the calendar first. The Deprecations for PHP 8.6 RFC deprecates SplFileObject::fgetcsv(), fputcsv(), setCsvControl() and getCsvControl(), and that poll closed 25 yes, 5 no, 15 abstain. The SplFileObject::fgetcsv manual page already lists "8.6.0: This method has been deprecated", and PHP 8.6.0 RC5 went out for testing on 5 November 2026. The global fgetcsv() carries no such entry, so the adapter uses a plain stream:

/** @implements IteratorAggregate<int, list<?string>> */
final readonly class CsvRows implements IteratorAggregate
{
    public function __construct(private string $path) {}

    public function getIterator(): Generator
    {
        $h = fopen($this->path, 'rb');
        if ($h === false) {
            throw new RuntimeException("Cannot open {$this->path}");
        }
        try {
            $n = 0;
            while (($row = $this->read($h)) !== false) {
                $n++;
                if ($n === 1 || $row === [null]) {
                    continue; // header, or a blank line
                }
                yield $n => $row;
            }
        } finally {
            fclose($h);
        }
    }

    /** @param resource $h */
    private function read($h): array|false
    {
        // escape '' = no proprietary escape, no 8.4 deprecation
        return fgetcsv($h, null, ',', '"', '');
    }
}

Two details come straight from the manual. Since PHP 8.4, relying on the default $escape value is deprecated, so the call passes '' explicitly, which also disables PHP's non-standard escape mechanism. And a blank line comes back as an array holding a single null, not as an error, which is why the loop skips [null].

The key $n is the record number, header included, so a rejection that says "line 48211" points at the 48,211th record. It drifts from the physical line number only when a quoted field contains a newline.

Testing without a database

The port has one method, so the fake is a dozen lines:

final class InMemoryCustomerRepository implements CustomerRepository
{
    /** @var list<NewCustomer> */
    public array $saved = [];
    public int $batches = 0;

    public function insertBatch(array $customers): void
    {
        $this->batches++;
        array_push($this->saved, ...$customers);
    }
}

The PHPUnit tests pass plain arrays and inline generators, so there is no CSV fixture and no RefreshDatabase:

final class ImportCustomersTest extends TestCase
{
    public function test_it_reports_why_rows_fail(): void
    {
        $repo = new InMemoryCustomerRepository();
        $rows = [
            2 => ['alice@example.com', 'Alice', 'DE'],
            3 => ['not-an-email', 'Bob', 'US'],
            4 => ['carol@example.com', '', 'FR'],
            5 => ['dave@example.com', 'Dave', 'Germany'],
        ];

        $s = (new ImportCustomers($repo))->handle($rows);

        self::assertSame(1, $s->accepted);
        self::assertSame(3, $s->rejected);
        $first = $repo->saved[0];
        self::assertSame('alice@example.com', $first->email);
        self::assertSame(
            ['invalid email', 'missing name', 'bad country code'],
            array_map(fn (RowResult $r) => $r->reason, $s->samples),
        );
    }
}

The second test goes in the same class and pins the batch boundary: 1,001 rows must become 500, 500 and a final flush of 1. That trailing flush is an easy one to forget in a hand-rolled batch loop, and here a unit test with no database catches it.

public function test_it_flushes_in_batches_of_500(): void
{
    $repo = new InMemoryCustomerRepository();
    $rows = (function () {
        for ($i = 2; $i <= 1002; $i++) {
            yield $i => ["u$i@example.com", "User $i", 'PT'];
        }
    })();

    $s = (new ImportCustomers($repo))->handle($rows);

    self::assertSame(1001, $s->accepted);
    self::assertSame(3, $repo->batches);
}

Measure the memory instead of claiming it

To check the streaming claim, generate a big file and run the use case against a repository that only counts. Storing a million objects in the fake would only tell you how big the fake got.

<?php
// php bin/gen.php 1000000 > customers.csv
$n = (int) ($argv[1] ?? 1_000_000);
$out = fopen('php://stdout', 'wb');
fputcsv($out, ['email', 'name', 'country'], ',', '"', '');
for ($i = 1; $i <= $n; $i++) {
    $email = $i % 50 === 0 ? 'broken' : "user$i@example.com";
    fputcsv($out, [$email, "User $i", 'DE'], ',', '"', '');
}

<?php
// php bin/import.php customers.csv
declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

final class CountingCustomerRepository implements CustomerRepository
{
    public int $rows = 0;

    public function insertBatch(array $customers): void
    {
        $this->rows += count($customers);
    }
}

$import = new ImportCustomers(new CountingCustomerRepository());
$summary = $import->handle(new CsvRows($argv[1]));

printf(
    "accepted=%d rejected=%d peak=%.1f MiB\n",
    $summary->accepted,
    $summary->rejected,
    memory_get_peak_usage(true) / 1048576,
);

The counts follow from the generator: every 50th row is broken, so a million rows gives accepted=980000 rejected=20000. The peak figure depends on your PHP build, and I haven't run this myself, so read it off your own run. memory_get_peak_usage(true) reports the real memory allocated from the system; without true you get only what PHP's own emalloc() handed out.

The number to watch is the difference between runs. Generate 100,000 rows, then 1,000,000, and compare the two peaks. With the ceilings above, nothing in the pipeline grows per row, so the figure should barely move. If it climbs with the row count, something is accumulating, and the counting repository rules out the storage layer as the culprit.

Three callers, one use case. The rules live in the middle; each door only translates.

Same use case, three doors

Inside Laravel, the driven adapter uses the query builder, which can insert several records at once from an array of arrays. Eloquent never hydrates a model in the loop:

final class DbCustomerRepository implements CustomerRepository
{
    public function insertBatch(array $customers): void
    {
        DB::table('customers')->insert(array_map(
            fn (NewCustomer $c) => [
                'email' => $c->email,
                'name' => $c->name,
                'country' => $c->country,
            ],
            $customers,
        ));
    }
}

A batch of 500 with three columns binds 1,500 parameters in one statement. Check that against your driver's limit: SQLite's default host-parameter cap is 32,766 since 3.32.0, and was 999 before it, so on an old SQLite construct the use case with batchSize: 300. Duplicate emails are a job for a unique index. If you'd rather skip them than fail the batch, insertOrIgnore exists, but the docs warn it can ignore other errors too, depending on the engine.

Bind the port once in a service provider:

$this->app->bind(
    CustomerRepository::class,
    DbCustomerRepository::class,
);

The Artisan command, renamed so it doesn't clash with the use case class, shrinks to translation:

final class ImportCustomersCommand extends Command
{
    protected $signature = 'customers:import {path}';

    public function handle(ImportCustomers $import): int
    {
        $path = $this->argument('path');
        $s = $import->handle(new CsvRows($path));
        $this->info(sprintf(
            'accepted=%d rejected=%d', $s->accepted, $s->rejected,
        ));
        return self::SUCCESS;
    }
}

The upload endpoint calls the same use case on the uploaded file's path. The mimes rule inspects the file's contents, not only its name:

final class CustomerImportController
{
    public function __invoke(
        Request $request,
        ImportCustomers $import,
    ): JsonResponse {
        $request->validate([
            'file' => ['required', 'file', 'mimes:csv,txt'],
        ]);

        $path = $request->file('file')->path();
        $s = $import->handle(new CsvRows($path));

        return response()->json([
            'accepted' => $s->accepted,
            'rejected' => $s->rejected,
            'samples' => array_map(
                fn (RowResult $r) => [$r->line, $r->reason],
                $s->samples,
            ),
        ]);
    }
}

The third door is the test suite, which never boots the framework at all. The rule about country codes now exists in exactly one place. If a million-row upload outlives your request timeout, store the file and hand its path to a queued job; the job's handle() is one more three-line door into the same ImportCustomers.

If this was useful

This post is one use case behind a port, with doors that only translate. Decoupled PHP is the book-length version of that move: clean and hexagonal architecture for PHP applications, with Laravel or Symfony kept at the edge so the code that holds your rules outlives the framework version it started on. The runnable examples are public on GitHub if you want to read code before prose.

Available on Kindle, Paperback, and Hardcover. English, German, and Japanese editions out now — Portuguese and Spanish coming soon.

Record Your Coding Agent's Session With asciinema, Then Replay Where It Went Wrong

Gabriel Anhaia — Sat, 07 Nov 2026 09:01:33 +0000

Book: AI Agents Pocket Guide
The series: Pocket Guides for Developers — 8 short books on agents, RAG, prompts, observability, events, databases and system design — the whole series
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

The agent says the flaky test is fixed, and the suite agrees. Somewhere in the few hundred lines it printed while you were in another tab, it wrote one sentence about why. You scroll up to find it. The interface has redrawn itself a dozen times since, and the line you want is either gone or buried between two diffs.

You can ask the agent what it did, but you get its summary, not what it printed at the time.

A terminal recording fixes this. asciinema saves everything the terminal displayed, with timing, into a small text file you can replay and search. It works the same for a Claude Code session as for a Codex one. The catch is that the file holds every byte the agent printed, secrets included, so it stays on your machine.

Step 1: record the agent, not a shell

This uses asciinema 3.x. Version 3.0 was a Rust rewrite released on 15 September 2025, and its release notes add the convert command and the asciicast v3 file format. A 2.x install has no convert and writes the older file format, so step 4 won't work on it. That matters on Linux: Debian and Ubuntu still package 2.4, so apt install gets you the old one. Homebrew ships 3.2.1. On Debian or Ubuntu, take the static binary from the releases page or build the development version with Cargo, as the quick start shows:

brew install asciinema        # macOS, 3.x

# Debian, Ubuntu: apt has 2.4, so build from git
cargo install --locked \
  --git https://github.com/asciinema/asciinema

asciinema --version           # needs 3.x

Then start the agent through it. -c runs one command instead of your shell, so the recording ends when the agent exits (asciinema rec man page):

mkdir -p ~/casts
asciinema rec -i 2 -t "fix flaky login test" \
  -c claude ~/casts/fix-login.cast

asciinema rec -i 2 -c codex ~/casts/tidy-auth.cast

-i 2 caps every pause at two seconds. The man page says the original timing is kept in the file and the limit is applied when you play it back, so an agent that thought for 40 seconds replays as a two-second gap. -t stores a title in the file's header.

The casts go in ~/casts, outside the repository, for reasons that come up in step 5. And since 3.0, rec needs a file name and no longer uploads anything on its own (release notes). Keep it that way.

The recording keeps every frame the agent printed, in order, with timing.

Step 2: drop a marker when something looks off

You will often notice a bad moment while it happens: the agent says "I'll skip this test for now" and keeps going. asciinema can add a marker at that instant, but there is no default key for it (markers docs). Set one in the 3.x config file, under [session] (configuration docs):

# ~/.config/asciinema/config.toml
[session]
idle_time_limit = 2
add_marker_key = "^]"

The docs' example key is ^x. Don't use that one with Claude Code, which starts several shortcuts with Ctrl+X, such as Ctrl+X Ctrl+K to stop background subagents (Claude Code shortcuts). Ctrl+] isn't in that list. Pick whatever key your agent leaves free.

Adding a marker shows a desktop notification, so you know it landed. The other recording key is Ctrl+\, which pauses and resumes capture (shortcuts). Press it before you paste anything you don't want on file, and again after.

Step 3: replay at 4x and stop on the markers

Play the cast back in a terminal at least as large as the one you recorded in, because asciinema doesn't adapt control sequences to a smaller window (quick start):

asciinema play -s 4 -i 1 ~/casts/fix-login.cast
asciinema play -s 4 -i 1 -m ~/casts/fix-login.cast

-s 4 is four times speed. -i 1 on play overrides the limit stored in the recording, so you can squeeze idle time harder than you recorded it. -m pauses at every marker (asciinema play man page).

While it plays, Space pauses and resumes. While paused, . steps forward one event and ] skips to the next marker. Ctrl+C stops. Stepping one event at a time through the stretch around a marker is how you read a line that flashed past at full speed.

Step 4: turn the cast into text you can grep

Watching works when you know roughly where to look. When you don't, search. asciinema convert exports plain text when the output file ends in .txt (asciinema convert man page):

asciinema convert ~/casts/fix-login.cast ~/casts/fix-login.txt
grep -n -i -E "skip|fail|todo" ~/casts/fix-login.txt

# or straight to stdout
asciinema convert -f txt ~/casts/fix-login.cast - | grep -n -i skip

The text export runs the output through a virtual terminal and drops colours, control sequences and timing. It tells you what was left on screen and in scrollback. It doesn't tell you when. Lines the agent's interface redrew over may not survive the export; the raw cast still has them.

For when, search the cast itself. In asciicast v3 each line after the header is [interval, code, data], where the interval is the time since the previous event and code o is output, m is a marker (asciicast v3 spec). A marker with an interval of 0.0 sits at the same moment as the event before it and shifts nothing after it. So you can insert one in front of the first line that mentions your word:

awk 'NR > 1 && !done && /skip/ {
       print "[0.0, \"m\", \"first skip\"]"; done = 1 }
     { print }' ~/casts/fix-login.cast \
  > ~/casts/fix-login-marked.cast

asciinema play -s 4 -m ~/casts/fix-login-marked.cast

Playback now pauses just before the agent prints that word. Two limits: an agent's interface can split one word across two writes or wrap it in colour codes, so search for something short, and expect the raw cast to be noisier than the .txt export. If the first match is the wrong one, change /skip/ to a longer phrase you saw in the text export.

Step 5: keep the .cast local

A cast is a plain text file with every byte your terminal displayed. For an agent session that includes:

your prompts, because the agent's interface echoes what you type
file contents the agent printed while reading your code
output of every command it ran, including an env, a cat .env or a curl -v that prints an Authorization header

That is without input capture. With -I / --capture-input, asciinema also records your keystrokes, and the man page warns that passwords and other sensitive input are recorded too. The CLI leaves input capture off by default (asciicast v3 spec). Leave it off. Environment variables are safer by default: only SHELL goes into the header unless you pass --capture-env.

A cast is a full copy of the screen. Treat it like a log file with secrets in it.

Record into ~/casts, not into the repo. If you ever record inside a project, add *.cast to .gitignore first. Before you send a cast to anyone, grep for the shapes your secrets take. Search the cast as well as the text export, since a key that was printed and then redrawn over can be missing from the .txt and still sit in the cast:

grep -nE "sk-|ghp_|AKIA|PRIVATE KEY" \
  ~/casts/fix-login.cast ~/casts/fix-login.txt

An empty result means none of those patterns matched, which is not the same as clean. Read the part you plan to share. asciinema upload sends the file to asciinema.org or your own server and prints a secret link (quick start). For agent sessions on real code, share a trimmed text excerpt instead, and delete the casts you no longer need.

Step 6: pair the recording with what each reply changed

The cast has every line the agent printed, but nothing about the state of your files after each reply. Claude Code has its own transcript viewer on Ctrl+O, with tool usage and a timestamp on each assistant message (docs), and that is worth opening first for a Claude session. The file side is where Hermes IDE comes in. I build it, so weigh this with that in mind.

Hermes saves every agent turn, so you can diff or restore any single one (README). Under each session, a strip labelled "Agent replies" shows one chip per reply with the lines it changed (+added −removed). Click a chip to see that reply's changes or to restore your files to that point (2.3.1 release notes). ⌘G (Ctrl+Shift+G on Windows and Linux) opens the Review Desk, where the By turn view lists each turn with its diff.

The Review Desk (⌘G) in By turn view for a Claude Code task in orders-api: two turns listed (T1: 3 files +69 −1, T2: 1 file +1 −0), turn 1's diff of src/db.ts adding a refunded status, the changed-files list, and a commit message drafted from the turns.

Used together: the marker in the cast tells you which reply went wrong ("the third one, where it said it would skip the test"), and that reply's chip shows exactly which lines it touched, with a restore if you want them back. I haven't tested running asciinema inside a Hermes session, so I won't promise how the two interact. Record in a terminal of your own if you want both.

A last difference. Hermes removes turn snapshots from worktree tasks 14 days after the session closes (2.2.9 release notes). Your casts stay until you delete them, which is one more reason to keep them in one folder and clean it out.

If this was useful

Hermes IDE is free, source-available under BSL 1.1, and runs on macOS, Windows and Linux: download it or read the source on GitHub.

A recording is how you find the bad turn. The AI Agents Pocket Guide is about the loop that got it there: how agents plan, call tools, decide they're done, and where you put the guardrails so a skipped test gets caught before you replay anything. It is one of 8 short books in the Pocket Guides for Developers series, on agents, RAG, prompts, observability, events, databases and system design — the whole series is here.

Your Agent's Command Printed Nothing for 2 Minutes. stdout Wasn't a Terminal

Gabriel Anhaia — Sat, 07 Nov 2026 08:02:16 +0000

Book: AI That Acts
The series: AI in TypeScript — 5 books, from your first LLM call to agents in production — all five here
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Command did not complete within its 120s timeout and was moved to the background. That is what Claude Code hands back after two minutes, the Bash tool's default timeout, along with the path of the file the output is going to. The command was an import script that prints a line every second when you run it by hand: step 1, step 2, step 3.

Claude reads that file and finds it empty. The script wasn't stuck. It called print for every line, and those lines are sitting in a buffer inside the process.

The C library and Python each pick a buffering mode for stdout from one check, isatty(), and under an agent that check fails.

Line-buffered on a terminal, block-buffered everywhere else

The rule is old and written down. From glibc's setvbuf(3): "Normally, all files are block buffered. If a stream refers to a terminal (as stdout normally does), it is line buffered. The standard error stream stderr is always unbuffered by default." The FreeBSD page says the same thing in nearly the same words.

Line-buffered means every \n sends the line out. Block-buffered means output collects in memory until the buffer fills, the program calls fflush, or the program exits normally. exit(3) is where "all open stdio(3) streams are flushed and closed."

Python makes the same choice in its own I/O layer. The sys docs: "When interactive, the stdout stream is line-buffered. Otherwise, it is block-buffered like regular text files." Since 3.9, stderr is line-buffered either way.

Node doesn't follow this rule. Its note on process I/O says writes to pipes are asynchronous on POSIX and synchronous on Windows. The Node trap is a different one: call process.exit() while a write is still pending and that output can be lost.

An agent's shell tool captures what your command prints so it can hand the text to the model. Whether the capture is a pipe or a file, it isn't a terminal. An open feature request asks for PTY support in Claude Code's Bash tool because interactive commands hang there, and the thread confirms the tool runs commands without a controlling terminal. So the moment an agent runs your script, it switches to block buffering.

Reproduce it in a minute

Ten lines of C:

#include <stdio.h>
#include <unistd.h>

int main(void) {
    for (int i = 1; i <= 5; i++) {
        printf("step %d\n", i);
        sleep(1);
    }
    return 0;
}

Build it with cc -o tick tick.c. Run ./tick and the five lines come out one second apart. Run ./tick | cat and nothing shows for five seconds, then all five lines land at once when the program exits and flushes, because cat took the terminal away from its stdout.

Same program, same lines. On a terminal they leave one at a time; on a pipe they wait for the buffer.

The Python version behaves the same way:

import time

for i in range(1, 6):
    print(f"step {i}")
    time.sleep(1)

python3 tick.py streams. python3 tick.py | cat waits, then dumps.

The case closest to a tool timeout uses timeout(1), which on Linux sends SIGTERM when time runs out:

timeout 3 python3 tick.py | cat

You get no lines at all, even though print ran three times. They were in the buffer when SIGTERM arrived. Python's signal docs list only SIGPIPE and SIGINT among the handlers it installs by default, so SIGTERM ends the process without the flush a normal exit would do. The C program loses its lines the same way.

To see what your agent gives a command, ask it to run this, then run it in your own terminal and compare:

[ -t 1 ] && echo "tty" || echo "not a tty"

-t 1 is true when file descriptor 1, stdout, "is opened on a terminal" (test(1)).

What Claude Code does with a quiet command

Claude Code's tools reference lays out the path. The Bash tool runs each command in a separate process and "streams a command's output to a working file as the command runs." When the command finishes, Claude Code reads that file back. The foreground timeout is two minutes by default (BASH_DEFAULT_TIMEOUT_MS). Claude can ask for more on a call, up to a ten-minute ceiling (BASH_MAX_TIMEOUT_MS), per the environment variables reference.

When a foreground command hits its timeout, Claude Code doesn't stop it. It moves the command to the background (unless it starts with sleep) and returns that "moved to the background" message with a task ID and the output file's path. If the command block-buffers, the file holds only what has been flushed so far, which can be nothing. The model ends up reading a progress log the program hasn't written yet.

The output file the agent reads, and the buffer the lines are actually in.

It bites in two more places:

With CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 or in bare mode, a command that reaches its timeout "stops instead." If that stop ends the process with a signal, the buffered lines go with it, exactly like the timeout 3 demo.
The Monitor tool runs a script in the background and "receives each output line as it arrives," with a five-minute default deadline. A block-buffering watcher hands it lines in bursts, or only at exit, so Claude reacts late, or not before the deadline.

The fixes, cheapest first

Python: turn the buffer off. Run python3 -u script.py, or set PYTHONUNBUFFERED=1, which "is equivalent to specifying the -u option" (command-line docs). For one call site, print(..., flush=True) forces the flush (print()).

Make it stick for the agent. Claude Code's settings have an env key that sets variables "for every session and its subprocesses" (settings reference). Put it in the project's .claude/settings.json. Most committed env values, PYTHONUNBUFFERED among them, apply once each teammate trusts the folder.

{
  "env": {
    "PYTHONUNBUFFERED": "1"
  }
}

Your own C code: say what you want. Call setvbuf(stdout, NULL, _IOLBF, 0); at the top of main and stdout is line-buffered wherever it points. Or call fflush(stdout) after each progress line.

On Linux, someone else's binary that uses C stdio: stdbuf -oL. Stock macOS doesn't ship it. From GNU coreutils' stdbuf(1): "If MODE is 'L' the corresponding stream will be line buffered." stdbuf -oL ./tick | cat streams again. The same page names the limits: a command that sets its own buffering (tee, for one) overrides it, and filters like dd and cat "don't use streams for I/O." Python buffers in its own I/O layer, so use -u there.

Last resort: hand it a terminal with script. With util-linux, script -q -c "./tick" /dev/null. The BSD script(1), as on macOS, takes the file first: script -q /dev/null ./tick. The command now sees a pseudo-terminal and line-buffers. It may also switch on colors, progress bars and prompts. The util-linux man page says "It is not recommended to run script in non-interactive shells" and warns against using it in pipes, so save it for one stubborn binary.

If you build the shell tool yourself

A homemade run_command tool builds the same pipe. Node's child_process.spawn defaults stdio to ['pipe', 'pipe', 'pipe'] (docs), so every child sees a stdout that isn't a terminal. Set the environment in the tool and read output as it arrives:

import { spawn } from "node:child_process";

export function runCommand(cmd: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const child = spawn("sh", ["-c", cmd], {
      env: { ...process.env, PYTHONUNBUFFERED: "1" },
    });
    let out = "";
    child.stdout.on("data", (d) => (out += d));
    child.stderr.on("data", (d) => (out += d));
    child.on("error", reject);
    child.on("close", () => resolve(out));
  });
}

PYTHONUNBUFFERED covers Python children. For C programs on Linux, prefix the command with stdbuf -oL. The data handlers fire when the child writes, and that's the reason to care: a tool that wants to report partial output, or tell the model "still running, last line was X", needs the child to write as it goes.

Hermes gives the agent a terminal. Its commands still don't get one

I build Hermes IDE, so weigh this section with that in mind. Hermes runs every agent "in a real terminal by default, running the agent's own interface" (README). Claude Code's own stdout there is a terminal, which is why its screen, colors and prompts look the way they do anywhere else.

The commands Claude Code runs are its child processes, and the Bash tool decides where their output goes: the working file from the docs above. Launching the agent in Hermes or in any other terminal app doesn't change that, because the agent's terminal belongs to the agent. Given those docs, expect the [ -t 1 ] check to come back not a tty from the Bash tool wherever you started claude.

Hermes 2.3.4: Codex on orders-types and Claude Code on orders-api side by side, each in its own hermes/ worktree, with the sessions sidebar (status, context use, cost, branch) on the left.

What Hermes helps with is the comparison. Split panes put sessions side by side, and a plain shell opens in a real terminal just like an agent does. Run the slow command yourself in a shell next to the agent. If it streams there and stays silent under the agent, you're looking at buffering, not a hang, and you know before you spend a turn asking the agent to debug a script that works. Add PYTHONUNBUFFERED to the project settings and let the agent run it again.

Hermes is free, source-available under BSL 1.1, and runs on macOS, Windows and Linux. Download it or read the code on GitHub. It isn't affiliated with Nous Research, Anthropic, OpenAI or any agent vendor.

If this was useful

The shell tool is usually the first tool an agent gets, and those details decide whether the model has anything to reason about. My book AI That Acts covers the tool layer in TypeScript: tool calling, functions, and a first working agent.

It is book 3 of AI in TypeScript, a five-book series that runs from your first LLM call to agents in production.

9 Timeouts in Claude Code, Codex and Gemini CLI That Cut Long Test Runs Short

Gabriel Anhaia — Sat, 07 Nov 2026 07:01:18 +0000

Book: System Design Pocket Guide: Fundamentals
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Your integration suite takes 14 minutes on a clean run. You ask Claude Code to run it. Two minutes in, the Bash tool stops waiting, and the result Claude gets back reads Command did not complete within its 120s timeout and was moved to the background (tools reference).

In your terminal, the suite keeps going in the background. Run the same job in CI with claude -p and a text prompt, and a moved command gets 10 more minutes before Claude Code stops it (same page). If Claude didn't ask for a longer timeout, that is 2 minutes in the foreground plus 10 in the background: 12 minutes for a 14-minute suite.

That is one of nine limits that Claude Code, Codex and Gemini CLI put on long work. Each item gives the setting's name, its default, where it goes and the symptom, from each vendor's docs as of November 6, 2026. I haven't measured any of them myself.

Claude Code's Bash tool: three clocks

1. `BASH_DEFAULT_TIMEOUT_MS`: 2 minutes

This is the timeout for a foreground Bash or PowerShell command when Claude passes no timeout of its own: 120000 ms (env vars). Claude can pass a longer timeout on any call. You can't set one per command yourself.

At the limit, Claude Code doesn't kill the command. It moves it to the background and says so, with the task ID and the output file. The exception: with CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 or in bare mode, a command that hits its timeout stops instead (tools reference). Set that variable to keep sessions tidy, and a long test run can stop at the 2-minute mark.

2. `BASH_MAX_TIMEOUT_MS`: 10 minutes

This is the ceiling on what Claude may request: 600000 ms by default. The effective ceiling is the larger of this value and BASH_DEFAULT_TIMEOUT_MS (env vars). So even when Claude knows your suite is slow and asks for 20 minutes, it gets 10.

3. The background time limit: 30 minutes, or 10 in `claude -p`

This applies only to unattended sessions (v2.1.285 or later): -p runs, Agent SDK apps, CI jobs and cloud sessions. A local terminal, desktop or VS Code session has no limit on background commands (tools reference).

A command Claude starts in the background gets 30 minutes, or the timeout Claude passes, up to 2 hours. A command moved there at its timeout gets 30 minutes from the move. In a -p run whose prompt you pass as text, both defaults are 10 minutes. At the limit, the notice reads Background command "<description>" was stopped after reaching its background time limit, and Claude can start it again with a longer timeout.

The same two variables fix all three. BASH_DEFAULT_TIMEOUT_MS above 1800000 replaces the 30-minute background default (above 600000 replaces the 10-minute one in a text-prompt -p run), and BASH_MAX_TIMEOUT_MS above 7200000 raises the 2-hour maximum. Neither can shorten a limit. A settings file's env block applies however claude was launched (env vars):

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "1200000",
    "BASH_MAX_TIMEOUT_MS": "2400000"
  }
}

That gives commands 20 minutes by default and lets Claude ask for up to 40, so the 14-minute suite finishes in the foreground. Put it in ~/.claude/settings.json, or in the repo's .claude/settings.json for the team, where most env values wait until each teammate trusts the folder (settings).

Three separate clocks sit on one Bash command in Claude Code.

Claude Code: MCP servers, hooks and the API

4. `MCP_TIMEOUT`: 30 seconds to start a server

The startup timeout for an MCP server is 30000 ms (env vars). It bounds each server's connect attempt. A server that downloads itself on first launch, such as an npx package, can miss that window, and its tools won't be in the session. The MCP docs give the shape of the fix:

MCP_TIMEOUT=60000 claude

5. MCP tool calls: 60 seconds per request on remote servers

MCP_TOOL_TIMEOUT defaults to about 28 hours, so it rarely bites. Two quieter limits do. HTTP, SSE and claude.ai connector servers time out each request after 60 seconds unless MCP_TOOL_TIMEOUT or the server's own timeout is above 60000. And CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT aborts a call when the server sends nothing, not even progress, for 5 minutes on network servers or 30 on stdio (env vars).

The symptom is a remote MCP test runner or browser tool that works on short jobs and errors on long ones. Raise it per server in .mcp.json, in milliseconds:

{
  "mcpServers": {
    "test-runner": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "timeout": 1800000
    }
  }
}

That timeout is a hard wall-clock limit that progress notifications don't extend, and it also sets the server's minimum idle window (MCP docs). A stdio server has no 60-second timer. There, the limit you'll hit is the 30-minute idle window, and because a per-server timeout is a hard wall clock, set it above your longest run or leave it out.

6. Hook `timeout`: 10 minutes, less on some events

Hook timeouts are in seconds. The defaults are 600 for command, http and mcp_tool hooks, 30 for prompt hooks and 60 for agent hooks. Claude Code lowers the 600 to 30 on UserPromptSubmit (hooks reference).

A hook that reaches its timeout is canceled and its output thrown away, so on most events it makes no decision. If your Stop hook runs the full suite as a gate and the suite takes 12 minutes, the gate says nothing. For that gate, raise the hook's timeout (in seconds) above the suite's run time, for example "timeout": 1200. On PreToolUse it's worse: a hook that times out doesn't block the tool call; the call goes on through the normal permission flow. To make a stall count as a no on a command or http PreToolUse hook (v2.1.295 or later), set "onFailure": "block". That key has no effect on Stop hooks (hooks reference).

7. `API_TIMEOUT_MS`: 10 minutes for response headers

This one guards the model call. It sets how long each API request attempt has to receive its response headers: 600000 ms by default. It doesn't limit how long a streaming response runs after that. Raise it on slow networks or behind a proxy; 0 removes it from v2.1.305 (env vars).

A per-request limit inside a per-call limit inside a session limit. Raise the outer one and the inner one can still fire.

Codex and Gemini CLI

8. Codex: `startup_timeout_sec` is 10, `tool_timeout_sec` is 60

Codex's MCP keys live in ~/.codex/config.toml, or in .codex/config.toml in a project you trust. A server gets 10 seconds to start and 60 seconds per tool call by default (config reference, MCP docs). That startup window is a third of Claude Code's.

[mcp_servers.test_runner]
command = "node"
args = ["mcp/test-runner.js"]
startup_timeout_sec = 30
tool_timeout_sec = 900

For optional servers, Codex waits mcp_optional_startup_grace_ms (1000 ms by default) while it builds the first tool list; 0 makes it wait for each server's startup_timeout_sec. Set required = true on a server if a slow start should fail the launch. I couldn't find a key for shell command timeouts in the Codex config reference.

9. Gemini CLI: `tools.shell.inactivityTimeout` is 300 seconds

This is "the maximum time in seconds allowed without output from the shell command" (configuration). It counts silence, not total time. A test runner with a quiet reporter, or a build step that buffers its output until the end, can hit it long before it's done.

Units change inside the same file. The shell setting is in seconds. An MCP server's timeout is in milliseconds, with a default of 600000 (MCP server docs). A hook's timeout is also milliseconds, default 60000 (hooks). The shell and MCP settings go in ~/.gemini/settings.json or the project's .gemini/settings.json:

{
  "tools": {
    "shell": { "inactivityTimeout": 900 }
  },
  "mcpServers": {
    "test-runner": {
      "command": "node",
      "args": ["mcp/test-runner.js"],
      "timeout": 900000
    }
  }
}

One status note from the same docs: for unpaid-tier and Google One users, Gemini CLI "was replaced by Antigravity CLI on June 18th, 2026." I haven't checked Antigravity CLI's own timeout keys, so they aren't on this list.

The cheat sheet

#	Setting	Agent	Where	Default
1	`BASH_DEFAULT_TIMEOUT_MS`	Claude Code	env / `env` block	120000 ms
2	`BASH_MAX_TIMEOUT_MS`	Claude Code	env / `env` block	600000 ms
3	Background limit	Claude Code	via 1 and 2	30 min (10 in `-p`)
4	`MCP_TIMEOUT`	Claude Code	env	30000 ms
5	Per-request MCP limit	Claude Code	`.mcp.json` `timeout`	60 s (remote)
6	Hook `timeout`	Claude Code	`settings.json` hooks	600 s (command)
7	`API_TIMEOUT_MS`	Claude Code	env / `env` block	600000 ms
8	`startup_timeout_sec`, `tool_timeout_sec`	Codex	`config.toml`	10 s, 60 s
9	`tools.shell.inactivityTimeout`	Gemini CLI	`settings.json`	300 s

Watch the units. Claude Code hooks take seconds and its env variables take milliseconds. Codex and Gemini CLI each mix both.

Telling a finished run from a cut-off one in Hermes

I build Hermes IDE, so weigh this with that in mind. None of the limits above live in Hermes. It opens each agent in a real terminal by default, running the agent's own interface (README), so you set these limits in each agent's own config, and the agent's timeout notices appear in its own terminal.

Hermes adds one view across agents. Every session shows one status: working, needs approval, asked you, done, error or idle, and Hermes says when a status is a guess. A notification fires when an agent is blocked on you or done. On a long suite, that tells you which session has stopped and which is still working, without opening every terminal.

Codex on orders-types and Claude Code on orders-api, each in its own hermes/ worktree, with status, context use, cost and branch for each session in the sidebar.

"Done" means the agent finished its turn, not that your suite passed. A turn can end right after a timeout notice. Since 2.3.1, the "Agent replies" strip under each session has one chip per reply with the lines it changed, and a click shows that reply's changes. Read the last one before you trust a green-looking summary.

Your own checks can also decide when a task is done: the worktree recipe docs show done_when = ["npm test"] in .hermes/worktree.toml. I haven't timed a 14-minute suite through it. On macOS and Linux, agents keep working while Hermes quits, updates or crashes.

Hermes is free to download, source-available under BSL 1.1, and runs on macOS, Windows and Linux. It isn't affiliated with Nous Research, Anthropic, OpenAI or Google. If a limit caught you that I didn't list, tell me in the comments.

If this was useful

Most of these are limits stacked on limits, like a per-request timeout sitting under a per-call one. That is ordinary timeout design for any distributed system, and the System Design Pocket Guide: Fundamentals covers it, along with the other core building blocks, in a short read. And if you run more than one of these agents a day, Hermes IDE puts their status in one place.