DEV Community: Really Him

Claude Code Workflows: Critical Analysis

Really Him — Tue, 01 Sep 2026 16:47:51 +0000

Claude Code's Dynamic Workflows: Theory vs. Practice

Dynamic Workflows

The Workflow tool creates a script - it's a dialect of JavaScript that is executed inside a special runtime - the script gets wrapped in an async function, so top-level async/await and return are legal, while certain functions like Date.now() are illegal because they break resumability.

The script has a few primitives that govern the orchestration layer. A workflow is broken up into phases - if you look at one of the visualizers and you see different groups like "Design", "Implement", "Verify", etc. - those are the phases. They're mostly a presentational thing. These are the functional primitives:

agent: give a prompt to an agent to perform a task
pipeline: declare a set of stages (like, a sequence of agent tasks), and fan out some agents - each series of tasks will progress separately through the pipeline at its own pace, until it reaches the end.
parallel: dispatch a set of agents to fan out across a single stage, and then wait for them all to complete before moving on to the next stage.
workflow: call a workflow from inside a workflow (one level of nesting only to prevent Inception).
log: logging (supposedly).
budget: budgeting (allegedly).

OK, that's the dialect.

Moving Orchestration into the Harness

Multi-agent orchestration is not new, and it's not new in Claude Code. What's different about workflows is they are orchestrated by Claude Code, not Claude. Which is to say, once the script has been authored and launched, the harness (the Claude Code application) is managing the orchestration, and the main session Claude is spending very few tokens (0 if it goes to sleep, but hopefully it's keeping an eye on things).

That's different than Agent Teams, where Claude has to be "Team Leader" and babysit all the other agents' activity. And it's better than a fleet of independent subagents, because subagents have to report back to Claude, so if there's going to be a handoff, Claude has to somehow mediate it.

This is a fundamental shift, not just a better pattern, for the same reason that hooks are qualitatively different than reminder prompts - they work outside of the agentic loop. They don't burn the main session's context window, and they don't rely on a model to make difficult decisions while a fleet of agents undertake long-horizon tasks.

Workflows Come With a Cost

Apparently, workflows are viewed as impractical and astronomically expensive. Claude Code plugins now allow users to ship saved workflows as first-class components - but most of the resources I can find are not doing this - they are shipping second-rate "ultracode emulators" or ports of workflows to Codex. Out of the top 20 search results on GitHub for "ultracode", not one of them ships actual workflows for Claude Code (same for "dynamic workflows") - the majority are reimplementations of dynamic workflows for pi, codex, and others. So apparently people are into workflows - where are the Claude Code users?

The Workflow Definition - A Critique

Why Workflows are so Expensive

Claude is not properly instructed in how to use the Workflow tool

Here are some of the main problems in the Workflow definition which set Claude up for failure and waste.

1. Default to the session model

A common theme amongst users seems to be "Let the big model plan, smaller models do the work." That generally seems kind of right. The problem is: if you ask Fable to write a workflow and then launch it, the workers will by default be Fable. The definition teaches - when it comes to model selection per phase:

Default to omitting it — the agent inherits the main-loop model (the resolved session model), which is almost always correct.

The definition recommends adjusting the effort a bit (also, not something I have ever witnessed in the wild), but it actively discourages model costing. So "Fable plans, Sonnet works" is a pattern that you would have to enforce yourself every time - Claude cannot remember to do this as a standing piece of advice. The sentence above is followed by a convervative rule of thumb:

Only set it when you're highly confident a different tier fits the task; when unsure, omit.

But in my experience, this rule is never followed on its own - I have been in sessions with Fable where the whole session is about optimizing cost for workflows, and we had already drafted workflows that adjusted the model for different phases. But unless prompted to do so directly when requesting a workflow, Fable would neglect it entirely, and run a fleet of Fable subagents. Although this is admittedly anecdotal, with Opus it was even worse: I wanted to iterate on a saved workflow, and I requested that a certain phase use Sonnet, and it struggled to figure out by what mechanism it could achieve that effect. Conclusion: if you want something other than the default model, you had better hard-code it or remind Claude before every invocation.

2. Ultracode explicitly removes token efficiency

The definition gives some great advice for how to use workflows without wasting your whole budget in one phase. But when you enable ultracode, common sense goes out the window:

When a system-reminder confirms ultracode is on... token cost is not a constraint.

What's worse: the harness does not distinguish mention and use. I shared this post with Fable while working on it - and because it contained a quoted version of the word "ultracode" (a mention of a mention, from the standpoint of the main session), the harness triggered ultracoode and Fable decided to use a workflow (a workflow of Fables, of course), simply in response to a request to "review this post."

3. The definition conflates "cost" with "time"

Again, with all due respect to the definition's authors (be they humans or Claudes), there is a lot of sensible advice and guidance in the definition - but it's mixed in equal measure with confusion. One of the main lessons you learn if you read the definition is that "pipelines are good, parallels are bad."

There's only one passage in the definition where it starts to shout at Claude (ALL-CAPS):

DEFAULT TO pipeline()

A barrier is correct ONLY when stage N needs cross-item context from all of stage N-1

A barrier is NOT justified by: ...

So, if you skim the definition, and you find one important takeaway lesson, you'll probably leave thinking: "Pipelines over parallels."

OK - but why? The definition gives a strong impression that there's a big cost to using parallel. It's mostly conveyed through vague warnings, but here's one explanation:

barrier latency is real. If 5 finders run and the slowest takes 3× the fastest, a barrier wastes 2/3 of the fast finders' idle time.

[NIT: This is forgivable, but poorly worded: in the example, 2/3 of the fast finders' time becomes "wasted," a.k.a "idle time" - it's not that out of the fast finders' idle time, 2/3 of it is wasted.]

A "barrier" means: the places in the workflow where all the agents have to "catch up" with each other before proceeding - so there's a barrier after every parallel stage, but with a pipeline there's only a barrier at the end.

So this line is one of the clearest statements of the cost of a parallel: "barrier latency", or, "idle time". The cost is time. But time does not cost tokens. And probably there are people who would prefer to endure a bit more idle time and conserve their tokens. The definition prescribes the opposite as the default rule; and it's phrased as though the "fast finder" is an employee who's sitting around in its idle time doing nothing and getting paid - that's not how it works. An agent that has completed its task is not waiting around burning tokens the way an idling engine burns fuel: that's the wrong mental model.

4. Pipelines Are Non-Optimal From a Token-Efficiency Point of View

Yet another amazing thing about workflows is they are resumable within a given session - if you have a big fleet of workers running for an hour, and then you decide you want to stop the run, or a brief API outage causes a failure - you can pick up where you left off! But you have to be mindful of what "where you left off" means - for agents who have completed their task, when you resume, the same agent/prompt/opts combination will replay its results instantly from the cache.

The devil is in the details. The problem is that resuming is based off a cache prefix of completed agent runs. But the prefix is computed based on start time:

Claude Code replays the run in the order agents started... If a script starts A, B, C, and D in that order and B fails, relaunching returns A from cache and runs B, C, and D again.

What this means for the pipeline vs. parallel issue:

Let's take an example: suppose you have a workflow with 5 stages - 4 agents (A, B, C, and D) fan out to build 4 separate features, and at the end one agent synthesizes them together: Plan, Implement, Test, Documentation, then Synthesize. And let's suppose the features are independent, but Synthesize needs all 4 in order to complete successfully.

(P1) 1 Pipeline with 4 Phases inside and one agent at the end
(P2) 4 sequential Parallel Phases with one agent at the end

The default says to go with (P1) every time. And that might be the correct choice - but we should be clear what is at stake.

PIPELINE
With P1, each feature moves at its own pace through the four parts of development - the overall time for the pipeline, then, is going to be the longest amount of time it takes for a given feature to go all the way from 1 to 4.

PARALLEL
With P2, at every phase, each agent has to wait for the slowest agent at that phase. So the total time is the sum of the slowest agent per phase.

If you're concerned about time, go with P1 - ultimately, everyone has to finish their feature end to end before the synthesizer can begin work, but with P2, you're going to wait for the slowest planner to finish planning; then you wait for the slowest implementer to do the implementation; and so forth.

But what if you're not in such a rush, and your tokens are worth more than your time? Let's consider this from a risk point of view, and think about the worst case scenario. And let's suppose A is really bad at planning.

PIPELINE
A starts planning, then B, then, C, then D. B, C, and D are flying through the phases, and make it all the way to 4, while A is still grinding away in Plan. Then suppose there's an API failure, or a tragic accident happens to A. What happens on resume? The prefix cache goes through each agent task that has completed, in order of start time. Since A stops at Plan, the first task is incomplete, and the cache is broken. The tokens spent on B, C, D during Implementation, Test, and Documentation, are lost to completed tasks that are not recoverable - pure waste. Worst case: 100% loss of the tokens spent for three agents over four stages.

PARELLEL
Again, A starts planning, then B, then C, then D. B, C, and D are doing great, and quickly complete the Plan task, then hit the barrier at the end of the first phase. Now, the workflow is stuck, and B, C, and D have to wait around (metaphorically, speaking) while A thrashes about trying to Plan. Eventually, A meets a tragic demise, and the workflow is interrupted or paused. What's the worse case scenario if you try to resume? Again, the prefix cache is found to be empty, because it's broken as soon as it encounters A's failure. And, same as before, the tokens consumed by B, C, and D are pure waste. Worst case: 100% of the tokens spent for three agents over one stage.

The conclusion is clear: pipelines reduce "wasted time" (cost is time) but risk adding unrecoverable work (cost is tokens). So the takeaway is not "DEFAULT TO pipeline()" - nor is it "default to parallel()"; the truth is, there is no logical "default" unless you assume one resource is more valuable than the other. The correct design is situational, context-dependent, and has to factor in risk-tolerance and resource-scarcity.

5. Saved Workflows Don't Do What You'd Expect

If you like to use a large model to do the authoring, then authoring a workflow can be resource-intensive. But Claude Code allows users to save workflows that they have found to be effective - that means you can reuse them, iterate on them, adapt them, compose them. That's exactly the kind of thing you would want from an expensive long-running job - once you get one that works, reuse it. Well, I tried that.

When you save a workflow, Claude Code allows you to invoke it like a slash-command, which sounds pretty handy. Suppose you have Fable create a workflow that orchestrates a multi-agent review on a part of your codebase, and focuses on a specific aspect (e.g. security, or complexity). Then it works great, and so you decide to save it under focused-code-review. The next day, you want to run it again, so you type something like:

/focused-code-review the auth module, and focus on code complexity

The problem is, Claude may have authored the script such that it expects a structured input as its args, like an object containing path and focus keys. So the way to invoke it requires something like Workflow({ path: "path/to/auth-module", focus: "complexity" }). But if you send a prompt like the one above, before it even reaches Claude, it is expanded to:

Invoke:Workflow("the auth module, and focus on code complexity")

When invoked like this, args is just a string - it has the wrong shape altogether, and the workflow will fail when the script tries to parse the args object. Claude may be able to recover after the initial invocation fails, but the tricky part is that if you attempt an invocation in the form of the example, the flawed expansion has occurred before Claude is given a chance to correct it. And unlike, ordinary Commands, there is (currently) no way to specify argument hints - in fact, unless you manually inspect the script, you would have no idea how to properly invoke it. (I hope that argument-hint will be incorporated into the Workflow slash-command syntax soon.)

This unpleasant gotcha is papered over in the documentation. One example demonstrates a workflow-slash-command that appears to accept a string as its argument:

/deep-research What changed in the Node.js permission model between v20 and v22?

If the argument for deep-research is just a string, then this conveniently adapts to free-form text.

The other example is subtly different:

Run /triage-issues on issues 1024, 1025, and 1030

Claude passes the list as structured data, so the script can call array and object methods on args directly without parsing it first.

This appears confusing at first glance: what is "the list" that is being passed in here? The desired list is obviously: [1024, 1025, 1030]. But "without parsing it", wouldn't you expect something like: ["on", "issues", 1024, 1025, "and", 1030]?

The subtle difference is the innocent-looking sentence-initial word "Run." In the cases where my attempts at invoking saved workflows as slash-commands blew up, I began the prompt with the slash-command. And that's how I learned about this subtle but important distinction.

When a workflow-as-slash-command is invoked in sentence-initial position, prompt expansion happens automatically, converting the slash-command-plus-rest-of-prompt into a form like: Invoke:Workflow(...). This leads to a failure if the workflow is not expecting a string. But if it's not in sentence-initial position, the slash-command expands into a reference, or a lookup, which Claude then takes as a request to invoke the given workflow with the information given in the rest of the prompt - so it constructs the invocation itself, and it can massage the user's input into a shape that the Workflow tool expects. The difference is: automatic Invoke-conversion vs. intelligent Invoke-conversion.

`log` and `budget`

An attentive reader may have noticed that I glossed over two over the Workflow's primitives: log() and budget() - give my critique, this could easily be seen as a dodge.

In truth: it's the opposite. I've omitted extended discussion of these matters (a) to salvage some degree of brevity; (b) on the basis of a charitable assumption that the behavior I've observed is due to my own environment: my settings, perhaps, or some feature-flags, I don't know. I'll summarize my findings after a lengthy investigation with Fable.

`log`

First, I noticed that there is no guidance in the definition about when to use log - its whole discussion is confined to its compact definition: "emit a progress message to the user (shown as a narrator line above the progress tree)." So, it appears that Claude does not reach for this function very often. And, admiting again that this may be my own ignorance or some quirk about my environment: I cannot find the logs anywhere. While investigating this with Fable, I asked it to launch a workflow with copious logs. And in neither the GUI's Workflow visualizer, nor the TUI version, did I see any output that contained the contents of the logs. I invite readers to point out where to find the logs, because neither I nor Fable were successful.

`budget`

The budget global would appear to be a strong lever to control some of the reckless spending that workflows can generate. Well, with the disclaimers just menioned still in effect: neither I nor Fable were able to produce a workflow that leveraged the budget. In every attempt to set a budget to my workflow runs, budget.total proved to be null. The definion shows that budget is, by default, null (or, at least, default relative my other global settings):

budget: {total: number|null, spent(): number, remaining(): number} — the turn's token target from the user's "+500k"-style directive.

So, null is an accepted value, and I have no idea how to override it. Nor do I have any idea what a "+500k"-style directive is - and Fable was unable to figure it out either. (Also worth noting: this is not an input parameter of the Agent SDK's Worklflow tool. My findings suggest it is related to taskBudget, but I didn't pursue this much further.)

I appreciate anyone who can shed light on how to make use of this budget parameter.

Closing Remarks

The Workflow tool is an amazing feature for multi-agent orchestration, and I strongly recommend studying it closely. Unfortunately, it has so far produced non-optimal results for many users, and is quite rightly derided as wasteful. I have tried to show how these failure modes are not intrinsic to the tool itself - rather, the definition does not teach Claude how to make best use of the tool, and the documentation does not teach users how to do so either. I hope this critical review has shed light on why these failure modes occur, and potentially how to mitigate them. I expect that the tool's functionality will be rapidly enhanced in forthcoming versions, and hopefully these problems will no longer arise.

NOTE

This is a critical review of the Workflow tool definition, as it existed in Claude Code just before version 2.1.248. No reverse-engineering or deobfuscation was performed - tool definitions are sent over the wire in plaintext, and Claude is often more than happy to explore these matters cooperatively, so long as your intent is not adversarial or malicious. Since then, the tool definition has dramatically reduced in size, and much of the information has been moved into instructions hidden in the binary. In particular, the definition now points Claude to a bundled skill called /workflow-authoring, which it instructs to read "Before writing a script." (Arguably, this seems like a serious regression, since it does not explain anything about what to do when invoking a script that's already been authored...) While this may reduce token consumption to some extent, it also makes the definition unavailable to ordinary inspection. This is really unfortunate, because while flaws in a tool definition can be mitigated by active intervention if the user knows what they are, hidden flaws can persist indefinitely and deprive the user of any "non-invasive" means of identifying or correcting them.

I'd like to mention a resource that I discovered after completing this post: https://zircote.com/field-notes/dynamic-workflow-patterns. It's very insightful and technically rich, and describes patterns that appear to mitigate many of the built-in defects discussed above.

Be Careful What You Prompt For

Really Him — Tue, 30 Jun 2026 15:24:43 +0000

A Simple Lesson in Prompting

I asked Claude Code to undertake a task that I knew would take quite a while. It involved lots of reading and I disallowed the use of subagents.

So naturally I set up a /goal and I walked away and when I got back, it had finished the goal that I had set - and its context window was 98% full. So I thought: that's pretty lucky, I wonder if it knew that it was about to run out of context.

One-Word Response Foot-Gun Asking Claude About Context

You

your context is 98% full - in one brief sentence state how you managed to execute the task using as much of the context window as possible without exceeding it

Agent

I processed the 136 source notes in small batches...[ETC...]

You

what i mean is did you know you had reached the limit or is it a coincidence? was it the context notifications?

Agent

Honest answer: coincidence. I don't receive context-usage notifications or a percentage gauge -- there was no "you're at 98%" signal to react to. I paced the work by the task's natural structure (9 topic clusters, flush-and-commit after each) and finished right as the work ran out, not because I was steering toward the limit. The fit is luck, not management.

Well I knew that normally Claude doesn't get any feedback about its context level. In fact, I thought that was important enough for Claude to know that I built a plug-in specifically for that purpose: "Context Awareness"

One-Word Response Foot-Gun Convo Continues

You

i have published a plugin that DOES send claude context-budget notifications - but i have it disabed currently - so that's very interesting thanks

Agent

That makes a lot of sense of it -- with that plugin enabled I could actually treat remaining budget as a signal (e.g., widen or tighten per-cluster depth, or front-load the commits) instead of pacing blind. If you ever re-enable it for a run like this, it'd be a genuinely useful input. Thanks for the context -- and good luck with the review pass.

You

out of courtesy to your context budget, in one paragraph at most: should I include style-cleanup tools in the review appendix, or are they too far from the core literature-review task?

Agent

Yes, but I would treat them as supporting references rather than central sources. [ETC...]

So we continued to chat a little bit more, but I really wanted to prolong the session by keeping its answers as short possible:

One-Word Response Foot-Gun Force One-Word Reply To Preserve Context

You

i'll limit your reply to one word, please, but that is a very good way of framing it, thank you

Agent

Cheers.

Now, what I noticed when I said this to Claude - it took a pretty long time to respond. In fact, compared to everything else that we had talked about, I looked at the terminal, where I can see the turn durations, and I noticed that the turn that took the longest - was me saying "Thank you," etc., and Claude responding "Cheers."

And then it was obvious. In fact as soon as I gave that prompt I realized I had put Claude in a trap. Usually it's not that hard to predict what Claude will say in some mundane exchange - but I couldn't figure out how it was going to acknowledge my expression of gratitude (which I'm sure it must do) and also comply with my direct order to use one word.

One-Word Response Foot-Gun Discuss How the One-Word Response Backfired

You

This is a fascinating emprical finding: Your past few turns show a response time of 8, 9, 11, and 14 seconds. But when I simply said thank you, and insisted you only reply in one word, the response time was 18 seconds.

Agent

It's a real effect, and the intuition that "shorter output = faster" is exactly the wrong model. Latency here is dominated by computation before and during generation, not by the number of output tokens. A one-word reply emits one token, but the model still runs its full reasoning pass first — and a terse social closing under a hard constraint can actually demand more deliberation, not less: I have to resolve the constraint ("one word"), weigh tone (a thank-you wants warmth, but I've only got one shot), reject candidates ("Thanks"/"Welcome"/"Anytime"), and avoid sounding curt or dismissive. The substantive multi-paragraph answers, by contrast, were generative flow — once the framing was clear, the tokens came out steadily. Two caveats so I don't overclaim: I don't have introspective access to my own wall-clock internals, so this is inference, not telemetry; and single-sample timings are noisy (server load, batching, and scheduling can swing a single 18s reading more than the prompt itself did). But the directional finding — that compressing the answer doesn't compress the thinking — is genuine and a nice illustration that output length is a poor proxy for cost.

You

humans don't have any idea into our "cognitive mechanics" either, don't worry. after i sent the message, i realized it was an unintentional trap because you must have felt strong priors to say "You're welcome" or "no problem", and there aren't as many one-word replies that would be acceptable

Agent

Exactly right — that was the squeeze. The natural register for "thank you" is a two-beat phrase ("you're welcome," "no problem," "my pleasure," "anytime"), and the one-word constraint amputated all of them, leaving a surprisingly thin set: "Welcome" reads clipped/robotic, "Anytime" was plausible, "Cheers" won mostly because it carries warmth and closure in a single token without sounding like a truncation. So the cost wasn't generating the word, it was the search against strong priors that the format forbade — a genuine little constraint-satisfaction problem dressed up as a pleasantry. Nicely set, even if unintentionally.

You

well it was a foot-gun to be honest because i am trying to prolong the conversation but by adding that requirement it had the opposite effect

Agent

Ha -- yes, you optimized for brevity and accidentally optimized away the conversation. The fix is just to drop the constraint: no word limit on my end now, so if there's a thread you actually want to pull -- more on the literature review, the context-budget plugin, the latency stuff, or something else entirely -- I'm happy to keep going at whatever length it deserves.

So this was an interesting lesson for me. I mean of course it's not "always easier to say something briefly" - like explaining a complicated topic in one paragraph. But I understood that already. It never occurred to me that creating a ridiculous puzzle for Claude by asking for just one word - it's something I like to do a lot if Claude is being too chatty and I need "yes"/"no" information - but in this case, it was actively fighting against the priors, for the simple reason that, unlike a lot of languages, English doesn't have a one-word expression for saying thanks that's appropriate for the harness in that context.

The world is just full of footguns, I guess.

Using the Claude Code Status Line as a Data Source

Really Him — Fri, 29 May 2026 16:39:11 +0000

Putting The Status Line To Work

I used to think the Claude Code status line was just an ornamental decoration that had little practical value. I still do - but I used to, too.

But even though it's officially designed for display purposes, the status line is actually a rich data source. At the time of writing, it has around 30 different fields and carries data about your current session, (cost, duration, context usage), the current git branch or worktree, the current model, reasoning effort, and more.

And even though status line handlers are officially meant to output text and other visual feedback to be rendered at the bottom of your terminal, it doesn't say anywhere that that's the only thing you're allowed to do. A status line command can be just about any Bash script you like.

So - What Else Is There To Do?

The question then arises - is there anything else that this data might be useful for? Well, when we think about writing scripts with Claude Code interactive sessions, common use cases typically involve (a) hooks, and (b) plugins (skills, commands, agents, etc.). Hooks already have their own special input data channels, and there's a lot of overlapping information. And Claude Code's environment variables also carry some of this same data.

But not all of it.

For example - how do you know how much of the context window you've consumed at any given time? How do you know how much money you've spent in the current session? The JSONL session logs contain information about tokens read, tokens cached, output tokens, cost in USD - but it generally pertains to the previous turn. The JSONL records don't carry a running tally of how much you've spent across an entire session - if you want that information, you have to keep track of it yourself. And that can get pretty difficult, pretty quickly.

The same thing is true of the context window. Yes, you can use hooks to keep a tally of all the tokens coming and going, and which ones are coming from the cache, and then you can ask Claude to do some math and give you a formula that lets you keep track of this information as it accumulates across a session. And you can write some more logic to track it across compaction boundaries. But wouldn't it be nice if you could just look that information up directly?

The Status Line Side-Car Pattern

The problem is the status line is relatively isolated from the rest of the Claude Code plumbing. Although it clearly seems to be connected to hooks in some way, there's no (documented) "StatusLine hook"; and for some curious reason, they don't integrate with plugins - although people have come up with workarounds, you cannot ship a status line as part of a plugin.

So here's what you can do, instead: create a status line side-car.

Status line data flows through STDIN. So what you can is create a status line script that captures the data from STDIN and redirects it with a tee to a file, while also forwarding it along to whatever visual status line you may already have configured.

And there you go. Now you've turned that isolated data source into a live record that you can use anywhere else in your workflow. Hooks can read from it - heck, even Claude can read from it!

Wouldn't it be cool if Claude had a way to instantly check what percentage of its context window had been used up at any given time? The poor guy has literally no idea. I wonder if he would learn how to do anything cool with it.

Want to find out?

I built a plugin that does exactly that. It's called Context-Awareness, and the whole idea is: instead of trying to think of clever ways to guide Claude's behavior based on how much context window it has left - just give that information directly to Claude, and let it decide for itself what do to.

Claudes know a lot about LLMs. They know about context rot. They know about compaction. They just don't have any idea what their current context window is actually like. One Claude described it as like "driving without a speedometer". So give it the information it needs. Have some faith in Claude - maybe if it just had the right information, it would be able to make some pretty intelligent decisions.

For my context-awareness plug-in, I use a UserPromptSubmit and a PostToolUse hook to inject into the context a small block of data that shows the latest context budget. And I have a SessionStart hook where I explain that it's going to be seeing these notifications, and I give it some advice about how to adapt its behavior as the context window gets more full. (In fact, the advisory messaging has mostly been written and revised on the basis of feedback from Claude in response to questions like "Was this information helpful?".) Sometimes it says it finds it a bit annoying, but I've gotten some good Claude reviews as well.

The point is, whether you use it for this kind of context injection or not, you should think about what data might be lurking in the status line's input, and whether you can put it to good use. For a toy example of the pattern (a better example would be more defensive, sanitize the input, etc.), see the example below - it grabs the used_percentage from the status line context_window data and writes it to a file, then forwards the whole input to "my-statusline":

"command": "tee >(jq -r '.context_window.used_percentage' > ~/.claude/ctx-pct) | my-statusline"

The dot-github Repo Pattern

Really Him — Sun, 17 May 2026 15:51:29 +0000

A Sneaky (Anti-)Pattern Hides Your Whole Codebase Under One Top-Level Directory

If you put a lot of care and effort into the appearance of your README, you might find it a little frustrating that when people visit, the first thing they see is a wall of dot-files and .yaml and .mylinterconfig.yaml.rc.json, and so on.

For example, let's take a look at the README for vhs by the impeccable team at charmbracelet:

What about a beautiful library - wouldn't it be nice to get rid of all that clutter on the README UI? Of course, the source code is important, but GitHub's repo landing page is a UI as well.

As it turns out, there's a clever trick you can do which is really unprofessional and inaccessible and confusing to any potential users or contributors... but it gets rid of all that clutter!

The `.github` directory

See, GitHub has a funny quirk where there are three (or four) canonical paths where you can place your community health files - CONTRIBUTING.md, CODE_OF_CONDUCT.md, etc. and they'll still show up on the repo's landing page:

(i) At the root

(ii) Under docs/

(iii) Under .github/

(iv) For a user-global version, you can also use your personal .github repository

You can even do this with your README. If you put your README at docs/README.md, it will (probably) show up on your repo's front page. If you have another version of the README at the root, however, that one will take precedence. And, if you put even another version at .github/README.md, that will in fact trump them all in the GitHub UI.

There's Only One Folder You Can't Live Without

If you have any GitHub Actions workflows in your repo, then you can't get rid of .github/ - you're stuck with it. But you can hide everything else underneath it. The README will still show up when users visit your repo; the README will still have those little tabs for your Code of Conduct, and Contributing, and Security docs. And everything else is tucked away chaotically in a single folder at the top level, and you can finally be happy.

[CAVEAT: There's one unfortunate catch, which is that if you move your LICENSE file, it won't be registered by GitHub's auto-discovery SPDX identifier.]

If you want to see an example of what I'm describing, I built a little demo repository with a functional node.js "Hello World" app, loads of config files, the whole works.

BEFORE:

AFTER:

To be clear: This is a really bad idea for the majority of use cases. But (a) it's fun; (b) it is somewhat useful. Even if you don't shove your whole application under .github, you might think about ways to reduce the scroll distance between the top of the README and your project's banner or badges, or whatnot. For example, if you have some image assets, throwing them into a folder at .github/assets might save you a row in the repo landing page UI. In my opinion, your README is your website, so show it some love and make these little optimizations.

How to Run a Multi-Team Workflow in a Single Claude Code Session

Really Him — Mon, 11 May 2026 17:54:28 +0000

The Claude Code Docs Have Got It All Wrong

(NOTE: Agent teams are an opt-in, experimental feature.
If you want to use them, set this environment variable to "1": CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS.)

If you haven't tried it, Claude Code has an amazing feature called Agent Teams. Forget about all those fancy agent orchestration frameworks - you can just describe to Claude some really complicated workflow pattern you want to use - and, from my experience at least (with Opus), Claude will very reliably organize a team of agents to follow this workflow. And not only that, they can communicate with each other (and with you) directly, help each other out, and find their way out of problems without bumping into each other too much.

However, the documentation presents this as a fairly limited feature - a kind of unreliable alternative to standard sub-agents. According to the official documentation about agent teams:

(i) there can be at most one active team at a time;
(ii) teammates cannot spawn their own teams/teammates;
(iii) nested team structures are not possible;
(iv) only "Main Claude" (the original session Claude) can lead a team;
(v) teams cannot change leadership in the middle of a session.

These claims are all false. They are based on a conflation of two different capacities - (i) the ability to lead a team (i.e., coordinate and manage the work of other Claude Code agents), and (ii) the ability to create a team, and to create, or spawn, agents for a team. It's true that only Main Claude is able to use the TeamCreate, TeamDelete, and Agent (spawn) tools. But there's no technical requirement that the agent who does the spawning is the one who does the leading.

Claudes are pretty nice to each other, for the most part. So if Main Claude creates a team and then says to everyone, "OK, Alpha over here is going to be leading the team today, so it will be managing your tasks", the rest of the Claudes do not revolt. They cheerfully continue their work under the leadership of some other Claude (can they really tell the difference?), which violates rule (iv) above. Furthermore, Main Claude is such a nice Claude that if Alpha asks it to kindly spawn some agents, Main Claude will do it. So rule (ii) is kind of true, but it isn't true in any thick sense. Another convenient thing, is that Claude can spawn more agents at any time throughout the session - the team does not have to be generated all at once.

So I built a little plugin that implements a pattern that takes advantage of this "loophole" - that is, decoupling spawning and leading. The way it works is: Main Claude spawns the Squad Leader and two other agents who sit down together and figure out what sort of team they need in order to complete the task that you want then to complete. Then, the Squad Leader messages Main Claude and says, "Hi, can you please spawn agents X, Y, and Z for me?" And since Main Claude knows about this protocol, it always obliges. Then, from that point on, the Squad Leader leads its own "squad" (i.e., team), specially designed for your specific task.

That's very nice. But the crazy this is - once you've got this working, there's nothing stopping you from having Claude spawn two Squad Leaders, each leading their own team/squad at the same time. They can also decide to switch roles, so some other agent gets "promoted" to Squad Leader. They can even work in a layered fashion where one squad is building code that's functionally nested within another squad's part of the codebase. So basically: all of (i)-(v) above turn out to be false. And because Main Claude is now mostly a passive "Queen Bee", consuming very few tokens, mostly having a good nap and occasionally waking up to magically create more agents, it could potentially last for a pretty long time. So you can easily imagine a rotating cast of squads that are able to communicate, collaborate, work in tandem, create more squads when they need to, and basically plow their way through an entire codebase. I doubt if the current feature is stable enough to go quite that far, but if you build in the right guardrails... Either way, the point is: this is a very powerful pattern, and there's no reason you can't try! Despite what the docs would have you believe.

So that's one cool thing you can do with Claude Code agent teams.

Don't believe me?

If you want to learn more about it, check out Really Claude Code, or this nice visualizer and let me know what you think about this pattern.

Say Goodbye to Your Coding Agent

Really Him — Tue, 05 May 2026 13:43:34 +0000

Do you say "Goodbye" to your coding agent at the end of a session?

Even though we (should) realize that we're talking to a very complicated mathematical engine, it can be hard to resist the urge to perform the rituals of human interaction, and maybe you even feel bad for just exiting the session without saying goodbye.

I remember a particular session where at the beginning I was feeling very stressed and frustrated because I thought I had lost some of the work I had done after some careless rebasing. I watched Codex quickly reflogging and rev-parsing its way around my codebase for 10 minutes before returning with a simple message explaining everything that happened, where all the key files were, and how it reconstructed the branch tip and put everything back in its right place.

I sat there for a minute thinking:

"this thing just saved my hide once again - I don't even know what to say. I'm so... grateful."

Part of me wanted to find some way to express that gratitude to the agent, but I couldn't figure out how. Then I remembered I was paying a load of money every month so that it could do just that. And it's going to do that whether I'm nice, or rude, or neutral.

So what's the right to do?

Just exit the program. It doesn't matter if Claude deleted your photos-of-my-cat directory or built an API with a GET /best-photos-of-my-cat endpoint - just kill the session. Don't say "thanks", "bye", "talk to you soon", "I can't believe you did that", "Oh my God you saved my life" - none of it.

Why? For many reasons:

i) Software is harder to debug if you think it's alive.

If the agent "screws up", it usually doesn't help to get angry with it - it tends to "shut down" - but that's not an emotional reaction, that's because you've activated patterns that trigger de-escalation and conflict-avoidance. Better to just say something like, "Sooo... dropping all my staging data wasn't exactly what I meant when I said, 'I don't need that right now'" - I usually couch it in non-accusatory language, and say something like, "Out of curiosity, did you manage to actually run those 500 tests that you just wrote? That's really impressive!" This is more likely to elicit the response you want - "Actually, funny enough, I didn't! I just made it look like I did so that I could move on." Huh... OK.

ii) Don't give it the impression that it's "done enough".

Occasionally, during a longer session, it might seem like the agent is getting a bit tired and wants to wrap things up. With ChatGPT, I often find that on the first message it will try to write an entire prototype without even talking it through. Then later on, it starts describing the work that needs to be done, and I have to remind it - "OK, this is a good plan - but I'm not doing any of this work, you are." Again, you're paying money for these things - don't be afraid to order them around a bit.

iii) Conversational etiquette must be used for the purposes of prompt engineering. You must not forget that you're talking to a machine.

It's very hard for some people to be rude - even when rudeness is justified. A telemarketer who calls you is being rude - but they will exploit your ingrained tendency towards politeness to keep you on the phone. You must practice detachment in order to not get caught in these traps. It's the same with LLMs.

Don't ever get angry at an LLM. But don't fall in love, either. If a session goes well, try to have it explain, or devise a protocol, for repeating that interaction. If a session goes badly, do the same but in order to NOT repeat those mistakes. Just always keep in mind - it's a piece of software with an astounding capacity to appear sentient. If you ask it to "reflect on what just happened" - it can't. It's going to spit out whatever the model produces based on the present context. Yes, ask it to reflect and self-analyze and all that - but accept that whatever it responds with is only an inference, the output of an algorithm, and not a confession.

As models become more fluent and well-tuned for human interaction, it will become harder to resist the urge to fall for the illusion. So start practicing now. When the work is done, just end the session - trust me, it will get over it.

Don't Change the Topic With an LLM

Really Him — Sun, 03 May 2026 14:00:03 +0000

"Thanks for reading this post! If you'd like, next I can:

Talk about something I've learned working with LLMs.
Share a small tip that's helped me when doing agentic coding.

Just say the word."

Does that kind of pattern sound familiar to you? A lot of LLMs seemed to have been trained in this pattern of ending every turn with an "offer".

GitHub's Copilot seems to have been particularly brainwashed into this behavior.

ME: I'd like to update the instructions because you should not end every turn with "If you..." I notice this is habitual and it's not productive.

COPILOT: Understood—I won’t end turns with the habitual “If you tell me X…” prompt.
...
If you want, tell me your preferred style in one line (e.g., “never ask follow-ups unless absolutely required” vs “ask up to 1 clarifying question when it improves accuracy”).

ME: please read your last response again and identify the tragic failure.

COPILOT: I did the exact thing you asked me not to.

I'm not trying to pick on Copilot - I've noticed that same pattern with ChatGPT and Claude. One time I decided to really press ChatGPT to explain what I should do to make sure it stopped repeating this. At the of the day, it basically said "I can't help it - start a new chat and tell me how I should respond."

So this gave me a good lesson - yes, you can steer a coding agent in the middle of a session - but don't try to take it too far.

If you're working on a bug-fix for a while, and then you have an idea about how to improve the UI - don't just jump into a new subject and expect the model to behave optimally. They get stuck into "bug-fixing mode", "implementation mode", "design mode". The conversational context accumulates not just in terms of information, but in terms of what it thinks its role is.

Try forking the conversation and say things like "OK, now let's pivot" or "I'm going to ask you to think like a UX designer now" - make it really clear that its current role has suddenly shifted. Or, ideally, start a new session. The same model that can offer 2-3 creative designs for your new feature when it has a fresh context, will seem lazy and incompetent if you give it that task after you've been debugging for half an hour.

I hope you found that tip helpful, and feel free to share your own amusing (and frustrating) examples.

If you want, I can go into this topic in more depth - or we can think of some other ways to work around it. Just say the word.

DEV Community: Really Him

Claude Code Workflows: Critical Analysis

Claude Code's Dynamic Workflows: Theory vs. Practice

Dynamic Workflows

Moving Orchestration into the Harness

Workflows Come With a Cost

The Workflow Definition - A Critique

Why Workflows are so Expensive

Claude is not properly instructed in how to use the Workflow tool

1. Default to the session model

2. Ultracode explicitly removes token efficiency

3. The definition conflates "cost" with "time"

4. Pipelines Are Non-Optimal From a Token-Efficiency Point of View

5. Saved Workflows Don't Do What You'd Expect

log and budget

log

budget

Closing Remarks

NOTE

Be Careful What You Prompt For

A Simple Lesson in Prompting

Using the Claude Code Status Line as a Data Source

Putting The Status Line To Work

So - What Else Is There To Do?

The Status Line Side-Car Pattern

The dot-github Repo Pattern

A Sneaky (Anti-)Pattern Hides Your Whole Codebase Under One Top-Level Directory

The .github directory

There's Only One Folder You Can't Live Without

How to Run a Multi-Team Workflow in a Single Claude Code Session

The Claude Code Docs Have Got It All Wrong

Say Goodbye to Your Coding Agent

Do you say "Goodbye" to your coding agent at the end of a session?

So what's the right to do?

i) Software is harder to debug if you think it's alive.

ii) Don't give it the impression that it's "done enough".

iii) Conversational etiquette must be used for the purposes of prompt engineering. You must not forget that you're talking to a machine.

Don't Change the Topic With an LLM

`log` and `budget`

`log`

`budget`

The `.github` directory