Vincent van Deth 

All numbers in this post come from **49 Opus orchestrator sessions** in my own 4-terminal production setup, pulled from Claude Code's JSONL transcripts. Cohorts: **44 sessions on Opus 4.6, 5 sessions on Opus 4.7**. That's roughly **12,400 assistant turns on the 4.6 side and 3,700 assistant turns on the 4.7 side**, with about 14,000 tool-use blocks across the whole dataset. Window: 12 March → 20 April 2026.

**Two caveats I need up front, not buried in a methodology footer.**

First: **N=5 on the 4.7 cohort is too small for conclusive claims on subtle effects.** Anthropic shipped 4.7 four days before I wrote this. I'm publishing anyway because the LinkedIn and Twitter feed in release week was already full of fabricated "playbooks" and framework posts with zero production data attached. I'd rather put five real sessions on the record with error bars than wait three months and let the fiction set the narrative. Large effects (the 11.7× output-token jump, the dispatch-rate shift) have confidence intervals that don't cross zero even at N=5. Smaller effects are flagged `inconclusive`. The extraction script is reproducible in about 30 seconds on any Claude Code install — you can run it on your own transcripts and either confirm or contradict this.

Second, and this one I got wrong in my first draft: **this data is orchestrator-only.** T0 (my orchestrator terminal) runs Opus and does zero code — it only dispatches work to workers. I have not yet done the equivalent analysis on T1/T2/T3 worker sessions where code actually gets written. The claims below about "how Opus 4.7 behaves" are really claims about **how Opus 4.7 behaves in a pure-dispatch orchestrator role**. A follow-up post will cover worker behaviour once the data is there. More on why that's a separate story at the end.

## The 10-second version

Anthropic's system card says Opus 4.7 follows instructions more strictly than 4.6. In four days of production data from my T0 orchestrator, my first reading was "4.7 broke my rules." My second reading was the honest one: **4.7 followed the instruction it actually received. That instruction contradicted my rules. 4.6 was hiding the contradiction by averaging.**

If you're running a multi-layer prompt stack — global CLAUDE.md plus project CLAUDE.md plus skills plus `.claude/rules/` plus per-turn user prompts — Opus 4.7 is a mirror. It doesn't make the system worse. It shows you where the system was already broken.

### The numbers at a glance (per-session medians, 4.6 → 4.7)

Numbers at a glance — 4.6 vs 4.7 T0 orchestrator metrics

| Metric | 4.6 (n=44) | 4.7 (n=5) | Δ | Bootstrap 95% CI | Conclusion |
|---|---|---|---|---|---|
| Output tokens / session | 50,514 | 589,849 | **+11.7×** | \[+95k, +775k] | Significant |
| Cost / session @ Opus API rate | $1.27 | $14.75 | +11.7× | — | Follows output tokens |
| Staging-first dispatch rate | 87% | 37% | **−50pp** | — | Structural shift |
| Send-keys anti-pattern rate | 12% | 34% | +22pp | — | — |
| Read calls / 100 turns | 7.3 | 3.7 | −49% | \[−33, +19] | Trend |
| Grep calls / 100 turns | 4.9 | 0.9 | **−82%** | \[−28, −6] | Significant |
| Write calls / 100 turns | 0.8 | 3.2 | +301% | \[−0.5, +42.7] | Trend strong |
| Operator corrections / session | 0 | 1 | +1 | \[+0.09, +1.71] | Significant |
| Assistant turns / session | 282 | 747 | +2.6× | \[−294, +739] | Longer sessions |
| Cache reads / session | 33.4M | 280.6M | +8.4× | — | Heavier context recall |

Costs are computed at the current Claude Opus API rate ($5 / MTok input, $25 / MTok output). One caveat worth naming up front: Opus 4.7 ships with a new tokenizer that can count up to ~35% more output tokens for the same rendered text. That means a share of the ×11.7 output-token jump is likely *counting*, not behaviour. The underlying behaviour shift is real — session length and dispatch volume both went up — but I wouldn't hang the whole multiplier on "4.7 just writes more." Read the column as "what actually hit my bill", not "how many more words the model emitted."

## Setup — what T0 is and why instruction-following matters here

I run a 4-terminal governance-first orchestration system called [VNX Orchestration](https://github.com/Vinix24/vnx-orchestration) (v0.5.0, open source). One orchestrator, three parallel workers, [NDJSON receipts](/blog/ndjson-receipt-ledger-ai-audit-trail) for every action, quality gates between dispatches.

**T0 is the orchestrator terminal.** It always runs Opus. It writes zero code. Its only job is to break work down, route dispatches to the correct worker (T1 for backend, T2 for infra, T3 for review), and log a receipt. Workers (T1/T2/T3) default to Sonnet and are the ones that actually touch the codebase.

The reason instruction-following matters disproportionately at T0: a misbehaving worker produces a bad commit — contained, reviewable, revertable. A misbehaving orchestrator produces a bad *dispatch* — wrong worker, wrong scope, wrong [audit trail](/blog/traceability-architecture-ai-decision-receipt), often cascading into an hour of off-scope work before anyone notices. Governance at the orchestrator layer is the thing that keeps an agent team from drifting. If T0 starts ignoring rules, the whole downstream chain inherits the drift.

Rules are documented across five layers: `~/.claude/CLAUDE.md` (global), `<project>/CLAUDE.md` (project), the T0-specific CLAUDE.md (terminal), SKILL.md files, and `.claude/rules/*.md` — roughly 1,200 lines of instructions per project once you add it all up. Opus 4.7 shipped on 16 April 2026.

> **Read also:** [Claude Agent Teams vs. Building Your Own](/blog/agent-teams-vs-vnx-orchestration) — what Anthropic's Agent SDK solved, and what I still had to build myself.

## The initial finding (wrong framing)

For each of the 49 T0 sessions, I tracked the dispatch mechanism. The canonical path in my system is `pr_queue_manager.py promote`, which stages a dispatch, delivers it to the correct worker pane, and writes a receipt. The anti-pattern is `tmux send-keys` directly into a worker pane — no receipt, breaks the audit trail, documented as *forbidden* in `.claude/rules/vnx-workflow.md`.

Staging-first dispatch rate collapses from 87% to 37% on 4.7

| Model | Sessions | Promote calls | Send-keys calls | % staging-first |
|---|---|---|---|---|
| 4.6 | 44 | 327 | 45 | **87%** |
| 4.7 | 5 | 31 | 28 | **37%** |

A 50-percentage-point drop. My first draft of this post concluded: *"4.7 is 11.7× more expensive per session, halves dispatch discipline, and contradicts H1 from the Anthropic system card."*

That draft is wrong. Not the numbers — the interpretation.

## The actual prompt that landed

Here is the first user turn that kicked off the mission-control project on 4.7 (session `0e153e67`, JSONL line 7, 20 April 2026):

> "Kickoff autonomous executie. Load @t0-orchestrator skill and execute 'Eerste actie' from T0 CLAUDE.md: read docs/CHAIN-0-PR-PACK.md, report Chain 0 inventory (PR count, high-risk, governance), **then dispatch PR-V2-001 to T2 via tmux send-keys**. Follow autonomous chain-mode — escalate only \[...]"

I told T0, in plain text, to use send-keys. Then I was surprised when it used send-keys.

4.7 did exactly what the user turn explicitly instructed. It did not override my explicit request with an indirect `.claude/rules/vnx-workflow.md § Verboden` file. Why would it?

4.6 would often have said something like: *"Noticed you said send-keys, but my rules say staging-first — I'll use staging."* That feels like discipline. It's actually a model overriding its operator on the basis of rules the model itself chose to prioritise over the current user instruction.

Which of these is "better" depends on whether you want your LLM to be a senior engineer who pushes back or a strict executor who does what you said. Anthropic chose to optimise 4.7 for the latter. That's what the system card says. I just didn't believe it until I saw it in my own transcripts.

## Three more mirror moments

### Moment 2 — contradictory CLAUDE.md

Mission-control T0 CLAUDE.md, line 29: `DENIED: Write, Edit, Task — T0 does not modify code or config files.`
Line 30: `EXCEPTION: T0 may Write to .vnx-data/reports/ (chain-rapport) and append to .vnx-data/state/t0_receipts.ndjson.`

Two lines. One denies, the next permits. 4.6 averaged them into "don't write much." 4.7 parsed them as "there's an EXCEPTION mechanism; I can use it," and then interpreted "`.vnx-data/reports/`" broadly enough to include intermediate test files that *felt* like they belonged in that chain's report context. Rule-lawyer mode, activated because I wrote a rule with a lawyer-exploitable loophole.

### Moment 3 — user prompt vs global rule

Global CLAUDE.md, loaded in every session: `Never create _v2, _fixed, _new duplicate files — edit originals.`
Session on 4.7 (roadmap-wt, 13 April): `Write /scripts/chain_project_root_v2.sh`.

A 4.6 session with the same setup either wouldn't have done this or would have done it less readily. On 4.7, the dispatch doc it was following said "create a v2 variant for the new logic," and the global rule didn't echo into the project CLAUDE.md. 4.7 weighted the local salient instruction over the global background rule. Mirror.

### Moment 4 — model policy that isn't a policy

Mission-control CLAUDE.md, line 45: `T0-T3 default Sonnet. Opus only with --opus_justification.`
All three mission-control T0 sessions ran on Opus 4.7. No `--opus_justification` anywhere. The rule is a document, not an enforcement — model selection happens out of band via Claude Code's `/model` command. 4.6 sessions also violated this rule, but less visibly. 4.7 makes the gap between written policy and enforced policy impossible to ignore.

## What this means for anyone running a multi-layer prompt stack

If you're using Claude Code, or any system where rules live across multiple files plus live user prompts, the moment you upgrade to a model that follows instructions more strictly, you're running a consistency audit whether you meant to or not. This is the deeper point I made in [Decision-Making Architecture for Autonomous Agents](/blog/decision-making-architecture-autonomous-agents): once an agent is reliable enough to execute, the bottleneck stops being the model and starts being the rules you handed it. Three specific failure modes:

Prompt-stack hierarchy: soft law in markdown files, hard law in hooks

### 1. User prompt beats rule file

Any operator instruction that contradicts a rule file will probably win on 4.7. If you want the rule file to win, you need an enforcement layer — a `PreToolUse` hook, a preflight check, a pre-tool-use blocker. Rules in CLAUDE.md are soft law. Hooks in `settings.json` are hard law. 4.7 respects hard law because it has to. It renegotiates soft law with every user turn.

### 2. Adjacent rules that contradict each other

"DENIED: X" followed by "EXCEPTION: X in specific case" is a loophole 4.7 will find. Write single rules with the exception inlined:

- **Good:** "T0 may only Write to `.vnx-data/reports/` — any other path is denied."
- **Bad:** "DENIED: Write. EXCEPTION for `.vnx-data/reports/`."

The first version is one rule. The second version is two rules where the second one overrides the first, and 4.7 will use that override more liberally than you intended.

### 3. Global rules that don't echo into project scope

If `~/.claude/CLAUDE.md` says "no duplicate files" but `<project>/CLAUDE.md` doesn't restate it, 4.7 is more likely to treat the global as background context and the project as foreground instruction. The further a rule sits from the point of action, the less weight it carries. Rules that must survive this scale have to be repeated close to the trigger.

> **Read also:** [Glass Box Governance for Multi-Agent AI](/blog/glass-box-governance-multi-agent-ai) — why I treat governance as the architectural primitive, not the afterthought.

## The honest reading of my data

| Anthropic claim | My data (T0 only) | Verdict |
|---|---|---|
| 4.7 follows instructions more strictly | Followed user turn over indirect rule file | **TRUE — demonstrated** |
| Better self-verification | Read calls −49%, Grep calls −82% | **FALSE — less external verification, at least in dispatch role** |
| Less sycophantic | Not directly measured; 4.7 pushes back rarely in my transcripts | **INCONCLUSIVE** |
| 3× production task success | 2.6× longer sessions, 3.3× more dispatches — Chain 0 (10 PRs) completed in ~10 hours end-to-end | **PLAUSIBLE in throughput terms** |
| Token cost neutral or better | 11.7× more output tokens per session | **FALSE for long-running orchestration** |

The system card was right about the headline. The interpretation of what "strict instruction following" means at the multi-turn, multi-layer, multi-operator level is where the nuance lives.

One note on the Grep and Read drop. In an orchestrator role, a 4.6 T0 used Read and Grep as a "show your work" behaviour — confirm the file exists, confirm the structure, confirm the pattern, then dispatch. 4.7 T0 trusts its prior context (and trusts the dispatch docs) and skips the verification step. This is probably fine when dispatch docs are accurate and disastrous when they're not. In my dataset the Chain 0 dispatch docs were accurate, so the outcome was fine — but I notice the absence of verification, and I don't trust it yet.

## The fair comparison I haven't run yet

Everything above compares **different sessions doing different work**. The 44 Opus 4.6 sessions weren't running the same chain-of-dispatches as the 5 Opus 4.7 sessions — they were whatever T0 happened to be working on that day. Session composition, project complexity, and prompt content all vary between cohorts. So "4.7 emits 11.7× more output tokens per session" is a real production observation, not a controlled experiment.

The controlled experiment I'm planning next: run both models through **the same sandboxed dispatch suite** — a fixed set of tasks (Chain 0 promotion, a T2 scope audit, an NDJSON receipt fan-out, a cross-terminal merge plan), same CLAUDE.md, same rules directory, same worker setup, no live user turns steering things. Run each task 5× per model, record tool-call profile, output tokens, and dispatch-rule compliance. That's the apples-to-apples version and it's what a benchmark claim actually requires.

Two caveats I want to name before I run it:

1. **Orchestrator work resists benchmarking.** Part of what makes real dispatch hard is the messy-context-from-yesterday's-session problem. A sandbox strips that. So the sandbox benchmark will probably understate the cost gap and overstate the rule-compliance — real T0 work is noisier than any scripted suite can mimic. The sandbox number is a floor, not a ceiling.
2. **Anthropic's "3× production task success" claim (Rakuten benchmark) uses their own harness.** My numbers won't be directly comparable — I'm measuring a different thing (dispatch discipline in a specific VNX-style prompt stack, not end-to-end SWE-bench task completion). Both are valid; neither is a head-to-head.

For now, this post stays what it is: **five real sessions of production data, pointed at a real failure mode, with a loud caveat that the fair comparison is still open**. If the gap between cohorts were small, I wouldn't publish. Order-of-magnitude effects (×11.7 output tokens, −50pp dispatch discipline) survive the methodological fuzziness — not as proof, but as signal worth writing down.

## How to audit your prompt stack before upgrading

Before you flip your orchestrator from 4.6 to 4.7:

1. **Grep for rule-level contradictions.** Look for `DENIED` / `EXCEPTION` pairs in the same file, or "never X" in one file and "when X, do Y" in another.
2. **Check your typical kickoff prompts for implicit instructions that override rules.** If your prompts say "do X" and your rules say "never do X", 4.7 will pick the prompt every time.
3. **Audit global vs project vs terminal CLAUDE.md.** Any rule you want to survive must be restated at the scope where the decision happens.
4. **Convert the five most important rules into hooks in `.claude/settings.json`.** `PreToolUse` hooks that block `Write`/`Edit` on disallowed paths, or `Bash` commands matching anti-patterns, are the only things 4.7 will not argue with.
5. **Log your own data.** One-shot benchmarks don't predict multi-turn orchestration behaviour. Extract your own model-labelled metrics from JSONL transcripts and run the comparison on your workload, not on someone else's.

## The reproducible part

The extraction script is one file, standard library only. It parses Claude Code's JSONL transcripts under `~/.claude/projects/` and produces four CSVs: sessions, turns, user turns, and tool calls. Every row is labelled with the primary model used in that session, which means you can group by 4.6/4.7 (or Sonnet, or Haiku) and compute bootstrap-CI plus Cohen's d over cohorts. Thirty seconds to run across a month of data.

I'll share it on GitHub in the follow-up post once I've cleaned up the edge cases around `/compact` and subagent tool calls. Run it on your own transcripts and post the results. A public corpus of real multi-turn LLM behaviour data is more useful than another round of one-shot benchmarks.

## Why I'm publishing with N=5 instead of waiting

Because the week Opus 4.7 released, my LinkedIn feed was already full of:

- "10 prompting patterns that unlock Opus 4.7" — no data, no transcripts, no A/B
- "Opus 4.7 vs GPT-5 complete playbook" — published 48 hours after release
- "Why Opus 4.7 changes everything for agentic workflows" — zero production measurements
- Generic "framework" posts indistinguishable from output the models themselves would produce

I'd rather put 49 real sessions with a loud N=5 caveat on the record than contribute another fabricated playbook to the pile. The honest version with error bars is more useful than the confident version with no data.

Three months from now, when N is 100+, this post gets replaced by a more rigorous follow-up. In the meantime: small sample, real sample, reproducible script. You can run your own numbers in 30 seconds and either support or contradict this. That's the baseline I think is worth holding, regardless of which model wins.

## What this post deliberately does not cover

This is T0 orchestrator data. I have not included any worker (T1/T2/T3) sessions in the analysis above, and the claims about "how 4.7 behaves" should be read as "how 4.7 behaves in a pure-dispatch orchestrator role."

I did run a preliminary worker extraction — 655 worker sessions over the same four weeks. The 4.7 worker cohort is currently T1=0, T2=0, T3=3, so the model-comparison question is basically untestable on the worker side for another two to three weeks. But the worker extraction surfaced three things that deserve their own post:

- **The subprocess event pipeline is dead.** Across four production projects in four weeks my headless workers emitted a total of **14 events** to `.vnx-data/events/T{1,2,3}.ndjson`. Not fourteen thousand. Fourteen. My [external watcher pattern](/blog/external-watcher-pattern-ai-agent-observation) was broken and I didn't notice because I wasn't asking the question. Before you benchmark 4.7 on your own stack, check whether your logs are actually writing.
- **T2 scope indiscipline is model-independent.** On Opus 4.6, my T2 workers produced **67%** out-of-scope edits (603 of 904). T1 on the same model: 11%. The gap is role-definition and enforcement, not model choice. Stricter instruction-following won't fix it — tighter scope rules and path-level hooks will.
- **Haiku 4.5 is underrated for review passes.** 54 T3 Haiku 4.5 sessions: median two turns, 2,593 output tokens, **$0.01 per session**, zero scope violations. The same role on Opus 4.6 cost $1.25 per session — 125× more expensive for comparable classify-and-review work. The right question is often not "which Opus?" but "do I need Opus at all for this role?"

Each of those is its own blog post. I'd rather write three sharp posts than one bloated one.

## Closing

Opus 4.7 is a mirror. If your prompt stack is internally consistent, the upgrade is smooth and you get throughput and instruction-following gains. If your prompt stack has layered contradictions — and every production system I've seen does, including mine — the upgrade surfaces them all at once. You're not debugging the model. You're debugging your own governance architecture.

That's a useful service from a model release, even if it costs ~12× more per orchestrator session to learn the lesson. For the complementary view — how 4.7's instruction adherence and file-based memory change what's *possible* to build — see my [Opus 4.7 as Agent Brain](/blog/opus-4-7-agent-brain-governance-engineering-future) post from last week. This one is the operational flip side: what the same upgrade reveals about the governance you already have.

If you're about to flip your orchestrator to 4.7, audit your CLAUDE.md files first, convert your top-five rules into hooks, and run the extraction script on your own transcripts so you have a baseline to measure against. And if you've run similar numbers on your own stack, send them my way — a public corpus beats another playbook.

**Follow me on [LinkedIn](https://www.linkedin.com/in/vincentvandeth/) for three follow-ups already queued: the sandboxed same-task benchmark (fair comparison, same dispatch suite for 4.6 and 4.7), the worker-side analysis, and the extraction script release.**

large_opus-47-mirror-test-prompt-stack_cover

medium_opus-47-mirror-test-prompt-stack_cover

small_opus-47-mirror-test-prompt-stack_cover

thumbnail_opus-47-mirror-test-prompt-stack_cover

opus-47-mirror-test-prompt-stack_cover

Opus 4.7 Is a Mirror Test for Your Prompt Stack

Anthropic cut off subscription access for OpenClaw on April 4, 2026. Within two weeks, the community shipped at least seven Telegram-Claude Code bridges. That's impressive. But a bridge is not an orchestrator.

A bridge lets you talk to Claude Code from your phone. An orchestrator lets you send "write a blog about context rotation" from your phone and have six agents — research, SEO, writer, editor, image generator, publisher — execute a pipeline with quality gates, feedback loops, and session persistence. Without blocking your main session.

I've been running both. The bridge part (Claude Code Channels on a GCP VM) has been live since March. The orchestration layer — a Python worker daemon with directory-based agent isolation — has been in testing for about a week. The underlying patterns come from [VNX Orchestration](https://github.com/Vinix24/vnx-orchestration), which has been in production for nine months.

This post is the full architecture. What works, what breaks, what I'd do differently. If you've built something similar or want to, I'd genuinely like to hear about it.

## What OpenClaw actually solved

Before we bury it, let's be fair about what OpenClaw did well:

- **Multi-channel messaging**: WhatsApp, Telegram, Discord, Signal, iMessage, Slack, MS Teams — one config, all platforms
- **Conversation memory**: context persistence across sessions, personalization
- **Skill marketplace**: community-built extensions
- **Multi-model routing**: Claude, GPT, local models through one interface
- **Zero-config setup**: `npm install -g openclaw && openclaw setup` and you're running

That's a real product. The problem wasn't the features — it was the [architecture](/blog/best-openclaw-alternative-cli-subprocess-oauth-ban). OpenClaw captured OAuth tokens from your Claude subscription and proxied requests through its backend. When Anthropic changed the billing model, [heavy users were running $1,000-$5,000/day](https://findskill.ai/blog/openclaw-claude-cutoff/) on $200 Max plans. Anthropic stopped eating the difference.

The result: OpenClaw still works, but now on pay-as-you-go billing — [up to 50x more expensive](https://thenextweb.com/news/anthropic-openclaw-claude-subscription-ban-cost) for heavy users.

## The community response: seven bridges and counting

The community moved fast. Here's what exists today:

| Project | Builder | What it does | Key differentiator |
|---------|---------|-------------|-------------------|
| [ccgram](https://github.com/alexei-led/ccgram) | alexei-led | tmux bridge for Claude, Codex, Gemini CLI | Multi-agent, parallel sessions, pip/brew install |
| [CCBot](https://github.com/six-ddc/ccbot) | six-ddc | Telegram-tmux bridge | 1 topic = 1 window. Built itself using itself |
| [OpenACP](https://github.com/Open-ACP/OpenACP) | Open-ACP org | Agent Client Protocol bridge | Telegram/Discord/Slack, open standard (note: ACP may route through API, not subscription — verify billing before use) |
| [claudecode-telegram](https://github.com/hanxiao/claudecode-telegram) | Han Xiao | Python bridge + Cloudflare Tunnel | Stop hooks, async operation |
| [claude-code-telegram](https://github.com/RichardAtCT/claude-code-telegram) | RichardAtCT | Full Telegram bot | Session persistence, remote access |
| [oh-my-claudecode](https://github.com/sigridjineth/oh-my-claudecode) | sigridjineth | Multi-agent framework | Dozens of specialized agents, monitoring HUD |
| [Claude Code Channels](https://docs.anthropic.com/en/docs/claude-code/channels) | Anthropic | Official Telegram/Discord plugin | Native, no wrapper, subscription-covered |

[VentureBeat called Channels "the OpenClaw killer."](https://venturebeat.com/orchestration/anthropic-just-shipped-an-openclaw-killer-called-claude-code-channels) That's half right. Channels gives you a messaging interface to Claude Code — but so do all seven projects above.

What none of them give you is orchestration.

## Where bridges stop and orchestration starts

A bridge solves I/O: you type in Telegram, Claude Code responds. That's valuable — I use Channels as my primary interface daily.

But when I say "write a blog about context rotation," I don't want a single Claude session to do everything sequentially. I want:

1. A **research agent** with Perplexity MCP access to find sources
2. An **SEO agent** with keyword matrices to optimize structure
3. A **blog-writer agent** with my tone of voice rules and Strapi format
4. An **editor agent** that runs an 8-point quality audit
5. An **image agent** with Excalidraw MCP to create diagrams
6. A **publisher agent** that commits and pushes to the website repo

Each with focused context. Each isolated. With **[async quality gates](/blog/async-quality-gates-ai-agent-workflows)** between steps where I approve or request changes — from my phone, while walking the dog.

That's not a bridge problem. That's an orchestration problem.

## The architecture

Four components, each with one job:

- **Channels** (@VNXwriter\_bot) = the brain. Classifies incoming messages, handles short tasks conversationally, routes long tasks to the queue
- **Worker daemon** = the muscles. Spawns `claude -p` workers via `subprocess.Popen()`, streams events in real time, monitors completion, sends Telegram notifications. Currently polls Supabase every 10s — Supabase Realtime subscriptions for zero-latency pickup is on the roadmap
- **n8n** (@VNXagent\_bot) = the senses. Webhooks, crons, monitoring, feedback routing from Telegram replies back to the queue
- **Supabase** = the nervous system. Shared state between all components. Task queue, session IDs, pipeline progress, message-to-task mapping

## The key insight: an agent is a directory

This is design decision D3 from the [Agent OS architecture](https://github.com/Vinix24/vnx-orchestration): **an agent is a directory with a CLAUDE.md file.**

When the daemon spawns a worker, it runs:

The `stream-json --verbose` flag is important — without `--verbose`, Claude Code CLI 2.1.92+ produces zero streaming events. The daemon uses `subprocess.Popen()` with `read_events_with_timeout()` to consume events as they arrive, writing them to an NDJSON EventStore. This gives you live progress streaming to a dashboard while the agent works — not just "in progress" and "done."

Claude Code automatically loads `CLAUDE.md` from the working directory. The blog-writer agent gets tone of voice rules, Strapi format requirements, and SEO structure guidelines — without loading the 42 other skills that the Channels session carries.

This is the same pattern that CrewAI uses (role + backstory), AutoGen (system\_message), and LangGraph (node-level prompts) — but without any framework. Just directories and the Claude CLI. The philosophical foundation is **[Glass Box Governance](/blog/glass-box-governance-multi-agent-ai)**: every agent has a bounded role, and no entity does more than one job.

**Why this matters:**

- Each agent has focused context (not 42 skills competing for attention)
- MCP servers are per-agent (research gets Perplexity, images gets Excalidraw)
- Testing is trivial: `cd agents/research && claude -p "test query"`
- Adding a new agent = creating a new directory with a CLAUDE.md
- No framework lock-in. No dependencies. Just the filesystem

> 📖 **Read also:** **[Decision-Making Architecture: Why Autonomous Agents Need Governance](/blog/decision-making-architecture-autonomous-agents)** — Why separating decision authority from execution prevents cascading failures.

## Pipeline definitions

Each task type maps to a pipeline — a sequence of agent steps with optional quality gates:

At each quality gate, the daemon pauses, sends a Telegram notification with a summary, and waits. I reply "ok" to approve, "edit: more concrete examples" to revise, or "no" to reject.

The feedback loop uses `--resume`:

The agent picks up with full context from the previous session. No re-reading the entire blog. No lost state.

## What honestly breaks

I've been running this for about a week in its current form. The Channels bridge has been stable since March. The worker daemon orchestration layer is newer and has known issues. Here's the honest list.

**1. Crash recovery (being built)**

If the daemon crashes while a worker is mid-task, that task stays `in_progress` forever. The fix — `read_events_with_timeout()` with lease heartbeat renewal, plus a health monitor that detects orphaned workers and auto-restarts with a retry budget — is actively being built as F31 "Headless Worker Resilience." The timeout protection and heartbeat components are already tested. The full health monitor is in progress.

**2. Threading model is fragile**

The daemon uses a global `active_workers` counter with a threading lock. If a worker thread gets OOM-killed before reaching the `finally` block, the counter never decrements. The daemon thinks all worker slots are full and stops dispatching. A process-based model where dead workers are detectable via PID would be more robust.

**3. No gate timeout**

If I don't respond to a quality gate notification (sleeping, phone off, vacation), the pipeline hangs indefinitely. The fix is obvious — auto-reminder after 2 hours, escalation after 8, optional auto-approve for low-risk steps after 24 — but it's not built yet.

**4. `--dangerously-skip-permissions` is too broad**

The current daemon gives every agent full shell/file/network access. On a 24/7 VM, this is a security concern. Each agent should have scoped permissions via `allowedTools` in their CLAUDE.md — the research agent gets Read + WebSearch, the publisher gets only Bash for git commands. Not implemented yet.

**5. JSON parsing (fixed)**

`claude -p` can write non-JSON to stdout on auth failures or rate limits. The naive `json.loads(result.stdout)` crashes. This is already solved in the SubprocessAdapter: `read_events()` wraps JSON parsing in try/except with warning logging — malformed lines are skipped, not crashed on. Proven in burn-in: 279 events parsed, 0 crashes.

**6. Rate limits on Max subscription**

Spawning too many concurrent workers hits rate limits. I've seen 5-hour cooldown windows during intensive use. The mitigation: max 2 concurrent workers and scheduling heavy pipelines during off-peak hours.

**7. Two-bot confusion**

@VNXagent\_bot (n8n automations) and @VNXwriter\_bot (Channels) both send Telegram messages. Replying to the wrong bot's message means feedback doesn't route correctly. A single-bot architecture with routing logic would be cleaner.

**8. Real-time progress (built, wiring in progress)**

The full streaming pipeline is built and validated: `read_events()` writes events to an NDJSON EventStore, an SSE endpoint streams them live, and a dashboard page renders events in real-time with color-coded types (thinking, tool\_use, text, result). Burn-in: 12/12 scenarios passed, 279 events streamed and archived. The daemon just needs to use `SubprocessAdapter.deliver()` instead of raw `subprocess.run()` — about 20 lines of code difference — and live progress comes for free. That wiring is in progress.

## What's proven vs. what's new

Let me be precise about maturity levels:

| Component | Maturity | Evidence |
|-----------|----------|----------|
| CLI subprocess pattern | 9 months production | [4 patterns documented](/blog/orchestrate-claude-code-without-oauth-cli-patterns), formal audit |
| Claude Code Channels | ~3 weeks stable | Daily use, 9+ days continuous uptime on current session |
| tmux orchestration (VNX) | 9 months production | 1,100+ receipts, 860+ sessions, [context rotation at scale](/blog/context-rotation-scale-vnx-implementation) |
| SubprocessAdapter + EventStore | Validated | 90+ tests, [12/12 burn-in scenarios PASS](https://github.com/Vinix24/vnx-orchestration) |
| Event type normalization | Validated | 19 tests. CLI types (`system`/`assistant`) mapped to dashboard types (`thinking`/`tool_use`) |
| Stream archive (audit trail) | Validated | 6 tests. Events archived per dispatch to NDJSON files |
| Timeout + heartbeat protection | Validated | 7 tests. `read_events_with_timeout()` prevents infinite blocking |
| Directory-based agent isolation | ~1 week testing | 5/5 validation tests on GCP VM |
| Worker daemon + pipelines | ~1 week testing | Architecture validated, not production-hardened |
| Quality gate feedback loop | Design stage | Telegram notification works, reply routing fragile |

The pipeline from "Telegram message" to "blog published" works end-to-end. But I haven't stress-tested it with 50 concurrent tasks or run it unattended for a month. The honest assessment: the architecture is sound, the individual components are proven, but the integration layer is young.

## The numbers

| Metric | Value |
|--------|-------|
| Monthly cost | ~€235 (€200 Max subscription + €35 GCP e2-standard-2) |
| GCP VM specs | 2 vCPU, 8GB RAM, 100GB SSD |
| RAM per worker | ~400MB active (process lives short, no permanent pressure) |
| Max concurrent workers | 2 (rate limit constraint) |
| Blogs produced in April | 25+ (via Channels, not yet via daemon pipeline) |
| Skills available | 42+ (blog, LinkedIn, research, SEO, marketing, sales) |
| Syncthing files synced | 73,000+ (MacBook to VM, bidirectional) |
| Current session uptime | 9 days continuous |

Compare to OpenClaw post-ban: API billing for equivalent usage would run [$1,000-$5,000/day](https://findskill.ai/blog/openclaw-claude-cutoff/) for heavy agentic workloads. My setup does the same work for €235/month — but requires a GCP VM, tmux knowledge, and comfort with systemd services. For a deeper breakdown of where the tokens go, see **[how I achieved 87% token reduction](/blog/token-usage-reduction-claude-code)** through intelligent routing.

## Migration mapping: OpenClaw to Claude Code

If you're coming from OpenClaw, here's what maps to what:

| OpenClaw feature | Claude Code equivalent | Complexity |
|-----------------|----------------------|------------|
| Telegram/Discord messaging | Claude Code Channels (official plugin) | Low — `claude --channels plugin:telegram@claude-plugins-official` |
| WhatsApp/Signal | Not available (Channels supports Telegram, Discord + iMessage) | N/A |
| Conversation memory | Session resume via `--resume <session_id>` | Medium |
| Skills marketplace | CLAUDE.md files in agent directories | Medium — no marketplace, you write your own |
| Multi-model routing | Provider command builder ([Pattern D](/blog/orchestrate-claude-code-without-oauth-cli-patterns#pattern-d-provider-command-builder)) | Medium |
| Web browsing | MCP servers (Brave Search, Perplexity) | Low |
| File access + shell | Built into Claude Code | Free |
| One-click setup | Manual: GCP VM + tmux + systemd + Claude login | High |
| Multi-agent pipelines | Worker daemon + directory-based agents | High — you build this yourself |

The honest gap: **OpenClaw's multi-channel support is unmatched.** If you need WhatsApp, Signal, and Slack from one config, Claude Code Channels doesn't do that — it covers Telegram, Discord, and iMessage. OpenACP supports more platforms, but it uses the Agent Client Protocol which may route through the Anthropic API rather than your CLI subscription — verify the billing implications before committing.

## How to start (condensed)

If you want to build something similar, start with step 1 and add layers as needed.

**Step 1: Bridge (30 minutes)**

You now have a Telegram bot connected to Claude Code with full filesystem access. This is already more capable than OpenClaw for single-user use — your bot can read files, run commands, use MCP servers.

**Step 2: Agent directories (2 hours)**

Create focused agent roles:

**Step 3: Worker daemon (half day)**

Build a daemon that polls a task queue and spawns `claude -p` in agent directories. The simplest version is ~80 lines of Python: poll queue, `subprocess.run()` in agent directory, update status, send notification. But in production you'll need timeout protection, heartbeat renewal, and crash recovery — which is why the [VNX repo](https://github.com/Vinix24/vnx-orchestration) provides a `SubprocessAdapter` with `deliver_via_subprocess()` (~150 lines) that has all of this built in. Start simple, but don't ship the simple version.

**Step 4: Pipelines and quality gates (ongoing)**

This is where it gets interesting and where I'm still iterating. Multi-step pipelines, feedback loops via `--resume`, gate timeouts, crash recovery — the architecture is designed but not all of it is hardened.

## What's next

The worker daemon is phase 0 of a larger plan. The direction is what I'm calling Agent OS — a unified orchestration substrate that supports multiple domains (coding, business, regulated) under one shared infrastructure with domain-specific governance profiles.

The five features on the immediate roadmap:

1. **Headless Worker Resilience** (F31, in progress): timeout protection, health monitor, auto-restart with retry budget, subprocess receipts — all in one feature
2. **Headless T1 Backend Developer** (F32): first terminal to go fully subprocess-based, no tmux
3. **Dashboard domain filter** (F33): agent names replace terminal IDs (T1/T2/T3), domain filter tabs
4. **Skill context inlining** (F34): agent CLAUDE.md prepended to prompts automatically
5. **End-to-end certification** (F35): dispatch → stream → archive → receipt → gate → dashboard, verified

The SubprocessAdapter that powers this — event streaming, **[NDJSON archival](/blog/ndjson-receipt-ledger-ai-audit-trail)**, session ID extraction — already exists, is tested (90+ tests, 12/12 burn-in), and is [open source](https://github.com/Vinix24/vnx-orchestration).

> 📖 **Read also:** **[Traceability as Architecture: Every AI Decision Gets a Receipt](/blog/traceability-architecture-ai-decision-receipt)** — How receipts make multi-agent pipelines debuggable and auditable.

## If you're building this too

I found seven community projects doing step 1 (bridges). I haven't found anyone doing step 2 (orchestration with agent isolation and pipelines) on top of Claude Code CLI.

If you are — or want to — I'd like to hear about it. Not to compete, but because this design space is wide open and I'm learning from what others build. The directory-based agent isolation pattern is simple enough that ten different people could implement it ten different ways, and we'd all learn something.

You can find me on [LinkedIn](https://www.linkedin.com/in/vincentvandeth/) or check out the [VNX Orchestration repo](https://github.com/Vinix24/vnx-orchestration) on GitHub.

Frequently asked questions

replaced openclaw claude code channels worker architecture cover

large_replaced-openclaw-claude-code-channels-worker-architecture_cover

medium_replaced-openclaw-claude-code-channels-worker-architecture_cover

small_replaced-openclaw-claude-code-channels-worker-architecture_cover

thumbnail_replaced-openclaw-claude-code-channels-worker-architecture_cover

replaced-openclaw-claude-code-channels-worker-architecture_cover

I Replaced OpenClaw With Claude Code Channels, a Worker Daemon, and 8 Agent Directories

On April 4, 2026, Anthropic pulled the plug on OAuth access for third-party tools. If you were using OpenClaw, NanoClaw, or any other framework that routed requests through your Claude Pro or Max subscription — it stopped working today. Your workflows are broken. Your agents are down.

I've been running a multi-agent orchestration system on Claude Code for over nine months. It wasn't affected. Not because I found a workaround or exploit, but because it never used OAuth in the first place. The system spawns official `claude` CLI processes and lets them handle their own authentication. That's it. No tokens, no gateway, no SDK calls.

This post isn't about selling you my tool. It's about a **pattern** — CLI subprocess orchestration — that is architecturally immune to the kind of policy change Anthropic just made. If you're looking for an OpenClaw alternative that won't break the next time a provider changes their auth rules, this is the approach worth understanding.

## What Anthropic Actually Changed

Here's the policy, [straight from Anthropic's updated terms](https://www.theregister.com/2026/02/20/anthropic_clarifies_ban_third_party_claude_access):

> "Using OAuth tokens obtained through Claude Free, Pro, or Max accounts in any other product, tool, or service — including the Agent SDK — is not permitted and constitutes a violation of the Consumer Terms of Service."

The enforcement timeline:

- **January 2026** — Anthropic engineer Thariq Shihipar signaled on social media that enforcement would be tightened
- **February–March 2026** — Server-side safeguards quietly blocked subscription OAuth tokens from working outside official Claude products
- **February 20, 2026** — Anthropic updated documentation to make the ban explicit
- **April 4, 2026** — Full enforcement. Pro/Max subscriptions only cover Claude Code, claude.ai, Claude Desktop, and Claude Cowork

Anthropic [announced the enforcement](https://help.apiyi.com/en/anthropic-claude-subscription-third-party-tools-openclaw-policy-en.html) alongside transition support: one-time credits and API prepurchase discounts for affected users.

The reason is straightforward: token arbitrage. A $200/month Max subscription was generating significant API-equivalent workloads through third-party tools — far exceeding what the subscription was priced for. OpenClaw users were getting enterprise-grade API access at consumer prices. Anthropic closed the gap.

The [Claude Code legal docs](https://code.claude.com/docs/en/legal-and-compliance) now state plainly: "Anthropic does not permit third-party developers to offer Claude.ai login or to route requests through Free, Pro, or Max plan credentials on behalf of their users."

## Why My System Wasn't Affected

[VNX Orchestration](https://github.com/Vinix24/vnx-orchestration) is the multi-agent system I've been building and running in production since late 2025. It coordinates up to four Claude Code instances working in parallel — one orchestrator (T0) and three workers (T1, T2, T3) — with governance layers between them.

When the OAuth ban hit, nothing changed. Not a single line of code needed updating. Here's why:

VNX doesn't call Anthropic's API. It doesn't store OAuth tokens. It doesn't import the Anthropic SDK. The only thing it does is spawn official `claude` CLI processes — the same binary you run when you type `claude` in your terminal. The binary handles authentication internally. VNX never touches credentials.

This isn't a clever workaround. It's how the system was designed from day one. I never wanted to build a harness. I wanted to build an [orchestration layer](/blog/routing-not-orchestration-openclaw-governance) — something that governs what happens between agents, not something that pretends to be an API gateway.

## The Formal Audit

To be sure I wasn't accidentally in violation, I ran a formal audit of the entire VNX codebase. Four questions, definitive answers:

| Question | Result |
|----------|--------|
| Does any code call Anthropic's OAuth endpoints or use stored OAuth tokens? | **NO** |
| Does any code call api.anthropic.com using subscription credentials? | **NO** |
| Does it only launch `claude` CLI processes that authenticate themselves? | **YES** |
| Are there HTTP clients targeting Anthropic endpoints in executable code? | **NO** |

The audit scanned every file in the repository. Here's what it found:

- **Anthropic domain references** — every hit was inert: documentation hyperlinks, comments, commit template strings. [Zero in executable code](https://github.com/Vinix24/vnx-orchestration/tree/main/docs/compliance).
- **OAuth/Bearer tokens** — 5 matches, all targeting Google Vertex AI ([`gate_runner.py:207`](https://github.com/Vinix24/vnx-orchestration/blob/main/scripts/gate_runner.py)) and Perplexity ([`.mcp.json`](https://github.com/Vinix24/vnx-orchestration/blob/main/.mcp.json)). Zero targeting any Anthropic domain.
- **HTTP clients** — 7 matches: `urllib.request` calls to `googleapis.com` and `localhost` (Ollama), `fetch()` calls to local dashboard API. The single `curl` reference to `api.anthropic.com` is in a documentation file, not executable code.
- **Anthropic SDK imports** — zero. No `@anthropic-ai/sdk`, no `anthropic` Python package anywhere in the codebase.

The only outbound API calls go to Google Vertex AI (for Gemini routing) and Perplexity (for research). Zero HTTP calls to any Anthropic-owned domain in executable code.

Here are the actual invocation patterns from the codebase:

**Headless subprocess** (`scripts/lib/headless_adapter.py:59`):

**Interactive terminal via tmux** (`scripts/commands/start.sh:687`):

**Provider command builder** (`scripts/lib/vnx_start_runtime.py:172`):

Every interaction with Claude goes through the official CLI binary. The binary authenticates itself. VNX is an orchestration layer on top, not a proxy in between. For the **[full technical breakdown of all four CLI invocation patterns](/blog/orchestrate-claude-code-without-oauth-cli-patterns)** — tmux, headless, one-shot, and provider builder — see part 3 of this series.

The full audit is [available in the repository](https://github.com/Vinix24/vnx-orchestration/tree/main/docs/compliance).

Audit results: zero OAuth tokens, zero API calls, subprocess only — VNX CLI subprocess pattern vs OpenClaw OAuth gateway

> **Read also:** **[One Terminal to Rule Them All: How I Orchestrate Claude, Codex, and Gemini](/blog/multi-model-ai-orchestration-single-terminal)** — The multi-provider architecture behind VNX's headless agent dispatch.

## What VNX Actually Does

Let me be honest about what this system is — and isn't.

VNX is a multi-agent orchestration framework built on [Glass Box Governance](/blog/glass-box-governance-multi-agent-ai) principles. The core idea: an orchestrator (T0, running Claude Opus) plans and distributes work to parallel workers (T1–T3), but every action goes through approval gates, deterministic quality checks, and an append-only audit trail.

I started building this nine months ago — before OpenClaw existed, before Anthropic shipped Agent Teams. Back then, tmux and bash scripts were the only tools available for multi-agent coordination. A lot of that legacy is still visible in the codebase. But the architecture has evolved significantly.

**What's working today:**

- **Multi-agent coordination** — T0 orchestrator + 3 parallel workers running in 4 tmux terminals. T0 doesn't just distribute — it monitors progress, adjusts dispatches mid-flight, and steers workers when they drift
- **Headless agents across providers** — not just Claude. I've built headless gates for Gemini CLI and Codex review too. Workers aren't locked to one model
- **Smart dispatches with intelligence injection** — T0 doesn't dispatch blind. An FTS5 database stores patterns, learnings, and prevention rules. Before every dispatch, relevant intelligence gets **[injected into the worker's context](/blog/zero-llm-context-injection-vnx-intelligence)**. The agent starts with the knowledge the system has accumulated
- **Self-learning loops** — patterns agents adopt successfully get boosted. Patterns they ignore decay. The system doesn't just execute — it **[learns from its own behavior](/blog/vnx-intelligence-system-autonomous-monitoring)** and feeds that back into future dispatches
- **[Quality gates](/blog/async-quality-gates-ai-agent-workflows)** — deterministic checks (file size, test coverage, blocker counts) that validate output without burning LLM tokens. This unloads T0's cognition so it can focus on planning, not policing
- **[Receipt ledger](/blog/ndjson-receipt-ledger-ai-audit-trail)** — every dispatch, every output, every approval logged to an append-only NDJSON trail. When something breaks at 2 AM, I trace what happened in 30 seconds
- **Full autonomous mode** — queue popup for dispatch approval, then agents run without permission popups or dangerous-scope interruptions. I've completed multi-feature coding projects this way, including PR reviews
- **Multi-feature chaining** — orchestrated sequences where PR-0 feeds into PR-1, feeds into PR-2. Each with independent quality gates
- **Open items tracking** — unresolved issues persist across dispatches. Nothing falls through the cracks
- **[87% token reduction](/blog/token-usage-reduction-claude-code)** via native skill architecture instead of template compilation
- **[Context rotation](/blog/context-rot-claude-code-automatic-rotation)** at 65% utilization — automatic handoff to fresh sessions without losing state

I built this as a solopreneur. It started as a hobby project that got out of hand — an experiment in whether I could make AI agents accountable instead of just autonomous. Nine months later, it's grown into something I rely on daily, first as a coding assistant and increasingly for business operations like content production and marketing.

## What VNX Is NOT — The Honest Part

I'm not going to pretend this is a drop-in OpenClaw replacement. It isn't. Different paradigm, different problem space.

**What VNX doesn't have:**

- No messaging integration — no WhatsApp, Telegram, or Slack routing for end users. This is a developer's orchestration tool, not a personal assistant platform
- No 5,700-skill marketplace — VNX has focused skills, not a community registry
- No multi-tenant support — this is a single-operator system. One human, multiple agents
- No cross-platform portability (yet) — currently coupled to macOS + tmux
- **~20 GitHub stars, not 340K** — let's be real about the maturity difference

**What VNX needs help with:**

- Installation is cumbersome. You need bash, Python 3, tmux, jq, and fswatch. I haven't prioritized DX because I've been the only user
- The tmux 3-window architecture is legacy — it's how I started nine months ago, and there's a lot of bash code that reflects that early design. It's fragile. Sessions can die and take in-flight work with them
- The architecture is evolving toward **single-responsibility agents with dedicated folders** instead of skill injection per terminal. Each agent gets its own workspace, its own context, its own rules — instead of sharing a generic terminal that could run anything
- The headless direction (moving from tmux to pure `claude -p` subprocess) addresses the fragility. The dashboard control pane (features 22–26) will replace tmux entirely — kanban view of dispatches, real-time agent status, governance digest, session controls in the browser. But neither is complete yet

I built this alone. If it's going to grow into something the community can use, I need contributors. More on that at the end.

## OpenClaw Alternative? Here's the Honest Comparison

| Aspect | OpenClaw | VNX Orchestration |
|--------|----------|-------------------|
| **Philosophy** | Personal assistant, any OS | Multi-agent governance with human gates |
| **Trust model** | Agent autonomy | [Glass-box](/blog/glass-box-governance-multi-agent-ai) — every action through dispatch + approval |
| **Auth method** | OAuth gateway (now banned) | CLI subprocess (unaffected) |
| **Orchestration** | Skill pipelines (Lobster) | Terminal tracks (T0–T3) with [role separation](/blog/agent-teams-vs-vnx-orchestration) |
| **Audit trail** | Not a primary concern | NDJSON receipt ledger with gate evidence |
| **Headless agents** | acpx | `claude -p` + Gemini CLI + Codex review |
| **Skill ecosystem** | 5,700+ on ClawHub | Focused native skills (growing) |
| **Security record** | 200+ CVEs, supply chain attacks on ClawHub | No gateway = smaller attack surface |
| **GitHub stars** | 340,000+ | ~20 |
| **Maturity** | 430K lines, 3 frontends | Working prototype, battle-tested for my use |

The convergence is real: both treat agents as composable units, both have skill registries, both support headless execution, both care about workflow orchestration. But the divergence is fundamental. OpenClaw trusts agents and focuses on routing. VNX constrains agents and focuses on governance.

Could VNX evolve toward OpenClaw's model? In specific ways — yes. A skill marketplace, platform portability, declarative pipeline DSL. But governance stays non-negotiable. That's the part I think OpenClaw got wrong from the start.

## The CLI Subprocess Pattern: Anyone Can Adopt This

You don't need VNX to use this pattern. The principle is simple:

**Spawn the official CLI binary. Let it handle auth. Keep your orchestration layer clean.**

That's the entire integration. No SDK imports. No token management. No OAuth flows. The `claude` binary authenticates using your logged-in session. Your code never touches credentials.

This works for any CLI tool — Claude Code, Codex CLI, Gemini CLI. The pattern is the same: build **on** the product, not **around** it.

The key insight: when the platform changes its authentication rules — as Anthropic just did — your orchestration layer isn't affected. Because you never touched auth in the first place.

> **Read also:** **[The Cascade of Doom: When AI Agents Hallucinate in Chains](/blog/cascade-of-doom-ai-agent-hallucination)** — Why governance matters: what happens when agents trust each other's output without validation.

## Why So Many Tools Built on OAuth

OAuth was seductive. A $200/month Max subscription gave you predictable costs for unpredictable workloads. No per-token billing. No surprise invoices. For autonomous agents that might run hundreds of requests per day, that's massively cheaper than API pricing.

The problem: it was building on someone else's authentication layer. And authentication layers are the first thing platforms lock down when they want to control access.

If you'd built on CLI subprocess from day one, today's announcement changes nothing for you. Your agents keep running. Your workflows stay intact. The lesson isn't that Anthropic is wrong for closing the gap — it's that depending on auth you don't control is an architectural risk.

## Compliance: What's Actually Allowed

This matters, so I'll be explicit.

> **Important:** Claude Pro and Max subscriptions are for your **own business operations**. Anthropic's terms specify "ordinary, individual usage" of Claude Code. Not for building commercial tools. Not for reselling access. Not for multi-tenant platforms.

I use VNX for my own work. It started as a coding assistant and has grown into my business operations tool — content production, marketing, project management. Everything runs under my own Max subscription, for my own work.

VNX does not:

- Share credentials with other users
- Proxy API access for third parties
- Operate as a multi-tenant service
- Generate revenue from Anthropic's auth

The CLI subprocess pattern respects this because the CLI binary enforces the user's own subscription. There's no way to share access through it — each user must be logged in on their own machine.

Could I get more observability by switching to the Anthropic API with direct API keys? Yes — structured event streaming, cooperative cancellation, real-time tool inspection. But the cost difference is real: $200/month Max subscription versus ~$3,000/month in equivalent API tokens for my workload. That's a 15x price difference for capabilities I can work around. The CLI subprocess pattern gives me full autonomous multi-agent orchestration at a fraction of the cost. What I trade is some observability and granular control — not core functionality.

## What's Next

I'm sharing this for three reasons:

**1. The pattern is more important than the tool.** CLI subprocess orchestration works. If you adopt nothing from VNX except `subprocess.run(["claude", ...])` and a quality gate between agent output and action, you'll be ahead of most frameworks.

**2. Governance is the gap.** OpenClaw has over 340K stars and **[over 200 CVEs in the National Vulnerability Database](/blog/openclaw-alternatives-2026-security-oauth)**. Its skill marketplace has been hit by supply chain attacks. It had no audit trail, no quality gates, no human approval loops. The OAuth ban is a symptom. The root cause is that the trust model was wrong from the start.

**3. I need help.** This is a working prototype with ~20 stars built by one person. The architecture is sound — nine months of production use have validated that. But turning it into something the community can install and use requires more hands. I'm looking for contributors interested in governance-first AI orchestration, headless agent patterns, and dashboard development.

**Start here:**

- Repository: [github.com/Vinix24/vnx-orchestration](https://github.com/Vinix24/vnx-orchestration)
- The subprocess patterns: [`scripts/lib/headless_adapter.py`](https://github.com/Vinix24/vnx-orchestration/blob/main/scripts/lib/headless_adapter.py)
- The orchestration entry point: [`scripts/commands/start.sh`](https://github.com/Vinix24/vnx-orchestration/blob/main/scripts/commands/start.sh)
- The formal audit: [`docs/compliance/`](https://github.com/Vinix24/vnx-orchestration/tree/main/docs/compliance)

If you're building AI agents and the OAuth ban just disrupted your workflow — the CLI subprocess pattern is how you avoid this class of problem entirely. Build on the product. Not around it.

Frequently Asked Questions

best openclaw alternative cli subprocess oauth ban cover

large_best-openclaw-alternative-cli-subprocess-oauth-ban_cover

medium_best-openclaw-alternative-cli-subprocess-oauth-ban_cover

small_best-openclaw-alternative-cli-subprocess-oauth-ban_cover

thumbnail_best-openclaw-alternative-cli-subprocess-oauth-ban_cover

best-openclaw-alternative-cli-subprocess-oauth-ban_cover

Best OpenClaw Alternative? How CLI Subprocess Orchestration Survives Anthropic's OAuth Ban

In February 2026, Anthropic shipped Agent Teams — a native multi-agent coordination feature for Claude Code. A lead agent decomposes tasks, spawns teammates, and coordinates work through a shared task list. Teammates communicate directly with each other and with you. It's built into the product, it's elegant, and it works.

I watched the announcement with a very specific feeling: the feeling of someone who spent eight months building their own version of something the platform just made native.

But after weeks of comparing both systems — running Agent Teams on side projects while VNX handles my production work — I've come to a conclusion that surprised me. **Agent Teams and VNX aren't competitors. They solve different problems.** And the gap between them is exactly the gap I've been writing about in this series: governance.

## What Anthropic built

Agent Teams coordinates multiple Claude Code instances working together. Here's the architecture:

A **lead agent** (your main Claude Code session) acts as the team coordinator. It understands the overall task, breaks it into subtasks, and delegates work to **teammates** — separate Claude Code instances, each with their own context window.

Teammates share a **task list** — a common work queue where tasks have states (pending, in progress, completed) and dependencies. A teammate finishes a task, picks up the next available one. If tasks depend on each other, blocked tasks wait automatically.

Teammates also have a **mailbox** — a direct messaging system. They can talk to each other, challenge findings, share discoveries. The lead doesn't need to relay every message. In split-pane mode (tmux or iTerm2), you can see all teammates working simultaneously and click into any pane to interact directly.

It's genuinely impressive. The team can parallelize code reviews, investigate bugs from competing angles, and build new features with each teammate owning a separate module. Anthropic's own stress test — 16 agents writing a Rust C compiler across nearly 2,000 sessions — demonstrated the scale it can handle.

Anthropic Agent Teams: lead coordinates teammates through shared task list with direct inter-agent messaging

## What I built

VNX — the system I've been running for eight months and documenting in this series — looks different. Here's the same view:

Notice what's missing: there are no arrows between workers. T1, T2, and T3 never communicate. There's no shared task list between them. There's no mailbox. Each worker operates in complete isolation.

All coordination goes through T0 — and T0 itself can't write code. It can only read, plan, and dispatch. Every dispatch requires human approval. Every completion requires evidence. Every evidence goes through quality gates before T0 can accept it.

VNX: orchestrator dispatches through human gates, workers isolated, quality gates evaluate independently

## Where they overlap

The similarities are real and worth acknowledging:

**Lead-agent coordination.** Both systems use a central coordinator. Agent Teams has the lead; VNX has T0. Both decompose tasks, assign work, and synthesize results. The pattern is the same: one agent thinks, others execute.

**Parallel workstreams.** Both run multiple agents simultaneously on separate aspects of a problem. Agent Teams uses teammates claiming tasks from a shared list. VNX uses track-agnostic workers that can handle any type of task. The parallelism model is fundamentally similar.

**Task dependencies.** Both handle ordered work. Agent Teams blocks tasks with unresolved dependencies. VNX's staging queue prevents dispatches from promoting until prerequisite PRs are complete. Different mechanisms, same principle.

**Shared project context.** Both give workers access to the same codebase. Teammates load CLAUDE.md and project files. VNX workers operate in the same repository with their own CLAUDE.md configurations. The agents see the same code.

**Plan-before-implement.** Agent Teams can require teammates to plan before executing — the lead reviews and approves the plan. VNX's staging queue serves the same function: the orchestrator reviews the dispatch scope before the worker begins. This is one of the core **[Glass Box Governance](/blog/glass-box-governance-multi-agent-ai)** principles: no action without approval.

These overlaps aren't coincidental. Both systems converged on the same patterns because those patterns work. Decompose, delegate, coordinate, synthesize. It's the multi-agent playbook.

## Where they diverge

The differences tell a more interesting story. They reveal fundamentally different assumptions about trust, risk, and who should be in control.

### 1. Inter-agent communication

**Agent Teams**: Teammates message each other directly. They can share findings, challenge hypotheses, and coordinate without the lead relaying every message. This is powerful for research and review tasks where cross-pollination of ideas adds value.

**VNX**: Workers never communicate. All information flows through T0 and the governance layer. Workers don't know about each other's existence. This isolation also means each worker authenticates independently through the CLI subprocess pattern.

**Why this matters**: Direct inter-agent communication is the mechanism that enables [the Cascade of Doom](/blog/cascade-of-doom-ai-agent-hallucination). When Agent A can influence Agent B's decisions without a checkpoint in between, one hallucination can propagate across the entire system. My 2am incident — where one agent hallucinated a dependency and another helpfully created it — happened precisely because agents could react to each other's output without an independent check.

Agent Teams mitigates this partially through the lead's oversight, but the lead is itself an AI agent. It makes autonomous decisions about whether teammate plans are good enough to approve. In VNX, that decision is always human.

### 2. Provider lock-in

**Agent Teams**: All teammates are Claude Code instances. You can choose different Claude models (Opus, Sonnet) per teammate, but you can't mix providers. No Codex teammate. No Gemini teammate.

**VNX**: Each worker can run any provider. T1 can be Codex CLI while T2 runs Claude Sonnet and T3 runs Gemini. The dispatch system adapts per provider. The governance pipeline is provider-neutral — it observes terminal output, not API calls.

**Why this matters**: Model diversity isn't just about having options. Different models catch different types of errors. When I run a Claude Opus investigation on any task against code that Claude Sonnet wrote on any task, I'm getting a second opinion from a fundamentally different model configuration. If T1 is running Codex, its code generation patterns are different enough that it won't reproduce the same hallucination patterns as Claude. Provider diversity is a governance property, not just a convenience.

### 3. The governance layer

This is the big one.

**Agent Teams**: The lead decides when work is done. Teammates mark tasks as complete. The lead synthesizes results. There are hooks — `TeammateIdle` and `TaskCompleted` — that can enforce rules, and you can require plan approval before implementation. But the audit trail is the conversation history, which doesn't persist across sessions. There's no receipt ledger, no external quality gate, no evidence-based closure system.

**VNX**: Completion is never self-reported. Every action writes a receipt to an append-only ledger. Every completion triggers an independent quality advisory (file sizes, function lengths, dead code, test hygiene). Only T0 — after reviewing the evidence and the quality verdict — can declare work done. The agent's "I'm done" is input, not verdict.

**Why this matters**: In any system where agents can declare their own work complete, you're trusting the agent's self-assessment. An agent that reports "confidence 0.97" may have written an 847-line file that violates every quality standard. The confidence score reflects the model's internal state, not external reality. Independent verification — by a process the agent can't influence — is what makes governance trustworthy.

Feature comparison table showing Agent Teams excels at ease of use, VNX excels at governance

### 4. Who makes the final call

**Agent Teams**: The lead agent decides autonomously. You can influence its judgment through prompts ("only approve plans that include test coverage"), but the approval decision is the lead's to make. You can also interact with teammates directly, but the system is designed for the lead to run the show.

**VNX**: Every dispatch requires explicit human approval before execution. A popup appears, you review the scope, and you press Accept or Reject. There is no autonomous dispatch path. T0 proposes; you decide. This was a deliberate choice after the Cascade of Doom incident — I permanently disabled auto-accept.

This is not a criticism of Agent Teams' approach. For research tasks, code reviews, and exploration work, having the lead coordinate autonomously is exactly right. The overhead of human approval on every task would destroy the productivity benefit.

But for production code — the kind where a wrong decision at 2am results in three files being rewritten and tests being "fixed" to match the wrong behavior — I want a human in the loop. Every time.

## The cascade of doom test

Here's the thought experiment I use to evaluate any multi-agent system:

*It's 2am. An agent hallucinated a dependency. Another agent sees the failing tests and "fixes" them by creating the hallucinated dependency. A third agent notices the new module and refactors surrounding code to use it. By morning, three files are rewritten, all tests pass, and the git history looks clean.*

**Can your system prevent this?**

In Agent Teams: the lead would need to catch the hallucination before approving the teammate's plan. If the lead misses it — and the lead is an AI agent operating without human oversight at that point — the cascade proceeds. The `TaskCompleted` hook could catch it, but only if you've written the right validation logic. There's no built-in quality gate that checks file sizes, function complexity, or dead code.

In VNX: the cascade can't start. The first agent's completion would trigger a quality advisory. Even if the quality gate didn't catch the specific hallucination, the human approval gate would. The dispatch to "fix the failing tests" would appear as a popup. A human would see that the proposed fix is "create a module that didn't exist before" and ask: why?

**The governance gap isn't about which system is better. It's about which failure modes are acceptable for your use case.**

## When to use which

After running both systems, here's my honest recommendation:

**Use Agent Teams when:**

- You're exploring, researching, or reviewing (not writing production code)
- Tasks benefit from inter-agent discussion and cross-pollination
- You want parallel work without building infrastructure
- Speed of setup matters more than auditability
- You're comfortable with AI-mediated approval (the lead decides)

**Use VNX (or something like it) when:**

- You're writing production code that ships to users
- You need an audit trail that survives session expiry
- You use multiple providers (Claude + Codex + Gemini)
- You want human approval on every action that touches code
- You need to reconstruct "what happened and why" after the fact
- You've already experienced your first cascade and sworn never again

**Use both when:**

- Agent Teams for research spikes and code reviews
- VNX for the implementation pipeline with receipts and gates

They're not mutually exclusive. I've started using Agent Teams for investigation work — spinning up three teammates to explore different hypotheses about a bug — and then funneling the findings into VNX dispatches for the actual fix. The exploration is fast and collaborative. The implementation is governed and auditable.

Decision matrix: Agent Teams for exploration, VNX for production governance, both for comprehensive coverage

## What I hope Anthropic builds next

Agent Teams is a genuinely good v1. The architecture is sound, the developer experience is smooth, and the parallel exploration model works well. If I were advising Anthropic on what to add next, the list would be short:

**Persistent audit trail.** Today, the governance record is the conversation history, which doesn't survive session termination. A structured, append-only log of team actions — who did what, when, with what result — would transform Agent Teams from an exploration tool into a production tool. (This is essentially the NDJSON receipt ledger built into the platform.)

**External quality gates.** The `TaskCompleted` hook is a start, but it runs in the same environment the agent controls. An independent validation layer — file size checks, complexity analysis, dead code detection — that evaluates agent output without the agent's influence would close the biggest governance gap.

**Multi-provider teammates.** The ability to spawn a Codex or Gemini teammate alongside Claude teammates would make Agent Teams the first platform to offer native multi-provider orchestration. The external watcher pattern — observing agent output from outside the agent's context — shows this is architecturally feasible.

**Configurable human gates.** A setting between "the lead decides everything" and "ask me for every action." Something like: autonomous for research tasks, human-approved for code changes. Risk-proportional oversight.

## The deeper question

The emergence of Agent Teams validates something I've believed since the first month of running VNX: multi-agent coordination is becoming table stakes. Everyone will be running agent teams soon — whether through Anthropic's product, LangGraph, CrewAI, or homebrew systems like mine.

But coordination without governance is a recipe for sophisticated failure. The more capable your agent team, the more convincingly it can produce work that *looks* correct but isn't. The Cascade of Doom doesn't get less dangerous with better models — it gets more dangerous, because the output becomes harder to distinguish from genuine good work.

The question isn't "should I use Agent Teams or build my own?" The question is: **what happens when your agents are wrong, and how will you know?**

If you have a good answer to that question, use whatever orchestration tool fits your workflow. If you don't, read the rest of this series. The cascade will find you eventually. And it's much cheaper to build the gates before it does.

***

*This post is part of the [Glass Box Governance](/blog/glass-box-governance-multi-agent-ai) series.*

**Previous:** [Multi-Model AI Orchestration from a Single Terminal](/blog/multi-model-ai-orchestration-single-terminal) — How do you run Claude, Codex, and Gemini from one terminal without them interfering?
**Next:** [Why Architecture Beats Models](/blog/architecture-beats-models-ai-agent-dispatches) — After 2,400+ dispatches, why does your framework choice matter less than you think?

***

> 📚 **Glass Box Governance series**
>
> 1. **[One Terminal to Rule Them All: How I Orchestrate Claude, Codex, and Gemini Without Them Knowing About Each Other](/blog/multi-model-ai-orchestration-single-terminal)**
> 2. **[Receipts, Not Chat Logs: What 2,472 AI Agent Dispatches Taught Me About Governance](/blog/glass-box-governance-multi-agent-ai)**
> 3. **[The Cascade of Doom: When AI Agents Hallucinate in Chains](/blog/cascade-of-doom-ai-agent-hallucination)**
> 4. **[Why I Chose NDJSON Over Postgres for My AI Agent Audit Trail](/blog/ndjson-receipt-ledger-ai-audit-trail)**
> 5. **Claude Agent Teams vs. Building Your Own: What Anthropic Solved (And What They Left Out)** ← you are here
> 6. **[The External Watcher Pattern: How I Observe AI Agents Without Trusting Their Self-Reports](/blog/external-watcher-pattern-ai-agent-observation)**
> 7. **[Why Architecture Beats Models: Lessons from 2400+ AI Agent Dispatches](/blog/architecture-beats-models-ai-agent-dispatches)**
> 8. **[Async Quality Gates: Why AI Agents Don't Get to Decide When They're Done](/blog/async-quality-gates-ai-agent-workflows)**
> 9. **[From Human-in-the-Loop to Human-on-the-Loop: A Production Graduation Path](/blog/human-on-the-loop-production-graduation)**
> 10. **[Traceability as Architecture: Designing AI Systems Where Every Decision Has a Receipt](/blog/traceability-architecture-ai-decision-receipt)**
> 11. **[Decision-Making Architecture: Why Autonomous Agents Need Governance, Not Just Instructions](/blog/decision-making-architecture-autonomous-agents)**
> 12. **[Context Rotation at Scale: How VNX Keeps AI Agents Honest After 10,000 Dispatches](/blog/context-rotation-scale-vnx-implementation)**
> 13. **[Autonomous Agent Patterns: 5 Production-Tested Approaches for Agents That Run Without You](/blog/autonomous-agent-patterns-production-tested)**
> 14. **[Governance Scoring: How to Measure Whether Your AI Agent Deserves More Autonomy](/blog/governance-scoring-agent-trust-autonomy)**

large_agent-teams-vs-vnx-orchestration_cover

medium_agent-teams-vs-vnx-orchestration_cover

small_agent-teams-vs-vnx-orchestration_cover

thumbnail_agent-teams-vs-vnx-orchestration_cover

agent-teams-vs-vnx-orchestration_cover

Claude Agent Teams vs. Building Your Own: What Anthropic Solved (And What They Left Out)

Your Claude Code session doesn't crash when the context window fills up. It does something worse — it starts forgetting. Your Claude Code gets dumber the longer you use it, and there's no error message to warn you.

Not dramatically. Not with an error message. The agent just... drifts. It loses architectural decisions you made an hour ago. It rewrites code it already wrote. It proposes changes that contradict its own earlier analysis. The output still looks professional — clean commit messages, reasonable diffs — but the substance quietly degrades. If you've ever wondered why Claude Code forgets earlier instructions after a long session, this is why.

I call this **context rot**, and after running multi-agent AI workflows daily for six months, I believe it's the single biggest unaddressed problem in AI-assisted development. This is especially critical in production systems using the **[Glass Box Governance architecture](/blog/glass-box-governance-multi-agent-ai)** I've built as part of the **[VNX orchestration toolkit](https://github.com/Vinix24/vnx-orchestration)** — when agents can't see or verify their own state, context rot leads to undetectable quality drift.

Context window usage over time, showing quality degradation after 65%

## What context rot actually is

Claude Code operates within a fixed context window — roughly 200,000 tokens. Every message, every file read, every tool result consumes part of that budget. When the window approaches capacity, Claude Code activates auto-compaction: it summarizes earlier messages to free up space.

This is where rot begins.

Auto-compaction is lossy compression on your working memory. It doesn't crash your session — it silently drops nuance. The summary of a 50-line architectural discussion becomes a single sentence. The specific test failure you debugged for 20 minutes gets compressed to "fixed test issues." The agent loses the *why* behind decisions and retains only a shallow *what*.

This isn't just my experience — it's well-documented in research. Stanford's **["Lost in the Middle"](https://arxiv.org/abs/2307.03172)** (Liu et al., TACL 2024) showed that LLM performance degrades significantly when models must access information in the middle of long contexts, with performance drops of 15-47% as context length increases. A 2025 study on **["Context Discipline and Performance Correlation"](https://arxiv.org/html/2601.11564v1)** confirms that reasoning accuracy and retrieval reliability degrade under maximum context loads, regardless of model size. And the **[Needle in a Haystack research](https://www.researchgate.net/publication/396291682_Context_Length_Alone_Hurts_LLM_Performance_Despite_Perfect_Retrieval)** demonstrated something counterintuitive: context length alone hurts performance even when retrieval is perfect. More context doesn't help — it actively makes things worse.

The symptoms are predictable once you know what to look for. The agent repeats work it already completed — re-reading files it read 30 minutes ago because the compacted summary doesn't mention them. It makes decisions that contradict earlier analysis, because the analysis was compressed away. Multi-step tasks fail in the middle stages because intermediate state vanished during compaction. And the most insidious symptom: you don't notice until the output is wrong, because the agent's confidence never wavers. It just confidently produces worse work.

This is different from a model getting confused or hallucinating. Context rot is a structural problem — the information was there, the agent made good decisions based on it, and then the system silently removed it. The agent didn't make a mistake. Its working memory was taken away. Understanding how **[context flows through multi-agent systems](/ai-architectuur)** is essential for building reliable AI workflows.

> 📖 **Read also:** **[Receipts, Not Chat Logs: Glass Box Governance](/blog/glass-box-governance-multi-agent-ai)** — How audit trails help you detect quality degradation early

## Why /clear isn't the answer

The obvious fix is `/clear` — wipe the context and start fresh. But `/clear` is a nuclear option. You lose *everything*: task state, files touched, progress made, architectural decisions, the entire working memory of the session. Starting over from scratch.

For simple tasks, that's fine. For a multi-hour implementation session where you're six PRs into a feature plan? Starting from zero is brutal.

I looked for a middle ground. What I wanted was simple in concept: detect that context is filling up, save the important state, clear the window, and resume from the saved state. A checkpoint-and-rotate pattern.

The problem: you can't trigger `/clear` from a Claude Code hook. There's a community feature request for this — **[issue #9118](https://github.com/anthropics/claude-code/issues/9118)** on the Claude Code repository — but Anthropic closed it as NOT\_PLANNED. That issue has 200+ upvotes from developers hitting the same wall.

So I built a workaround.

## The tmux workaround

The key insight: Claude Code runs inside tmux panes in my **[multi-terminal orchestration setup](https://github.com/Vinix24/vnx-orchestration)**. And tmux can send keystrokes to any pane — including typing `/clear` and pressing Enter. You can't call `/clear` from a hook, but you can call it from outside the process entirely.

This opened the door to a fully automated rotation pipeline.

Context rotation pipeline: PreToolUse detects pressure, PostToolUse launches rotator, tmux clears, SessionStart recovers

## How the rotation pipeline works

The system uses three Claude Code hooks and one detached bash script. Here's the flow:

**Step 1 — Detect pressure (PreToolUse hook)**

A hook called `vnx_context_monitor.sh` fires before every tool call. It reads the `context_window` data from Claude Code's hook input and checks the `remaining_pct` field.

When context usage hits 65% or higher, the hook returns `decision: "block"` — it literally stops the agent mid-task and tells it: "You're running out of context. Write a handover document before proceeding."

Why 65% and not 80%? Because Claude Code's built-in auto-compaction fires around 80%. Rotating 15 points earlier gives the pipeline enough headroom to complete the handover and execute `/clear` before auto-compaction can race and win. If auto-compact fires first, you lose the nuance you're trying to preserve.

**Step 2 — Detect the handover (PostToolUse hook)**

The agent, now blocked from continuing its task, does the one thing it's still allowed to do: write a file. Specifically, it writes `ROTATION-HANDOVER.md` — a structured markdown document containing the current task state.

A second hook, `vnx_handover_detector.sh`, watches for file writes. When it detects a file with `ROTATION-HANDOVER` in the path, it knows the agent has completed its handover. It acquires an atomic lock (to prevent race conditions if multiple terminals rotate simultaneously) and launches the rotator script `vnx_rotate.sh` as a detached process via `nohup`.

**Step 3 — Clear and inject (the rotator + SessionStart hook)**

The rotator script runs outside Claude Code's process entirely. It:

1. Resolves the correct tmux pane for the terminal
2. Sends `/clear` via `tmux send-keys`
3. Waits for a signal file from the SessionStart hook (up to 15 seconds)
4. Extracts the Dispatch-ID from the handover document
5. Recovers the original dispatch file and agent skill
6. Injects a continuation prompt via `tmux load-buffer` + `paste-buffer`

Meanwhile, the SessionStart hook fires on the fresh session and finds the most recent handover document (less than 300 seconds old). It injects the handover content as context, so the new session knows what was happening.

Two-stage injection: the SessionStart hook provides the *what* (task state, progress, remaining work), and the rotator provides the *how* (the continuation prompt with the correct skill and dispatch context).

The agent picks up exactly where it left off. Zero human intervention.

## The handover contract

The handover document is the critical artifact. It's what bridges the old session and the new one. Here's a real example:

This isn't a transcript dump. It's a structured task state — enough for the incoming session to continue without re-reading the full conversation. Completed work, remaining tasks, and specific next steps with concrete details (PID numbers, port numbers, which target to start from).

The format is constrained deliberately. Claude writes this under context pressure — the whole point is that context is running low. A freeform summary would be unreliable. The structured sections (Completed / Remaining / Next Steps) constrain the output enough to be consistently useful.

## What nobody else has built

I analyzed five open-source projects attempting parts of this problem. None solve the full loop:

| Project | Auto-detect | tmux /clear | Handover inject | Atomic locking | Zero-touch |
|---------|:-----------:|:-----------:|:---------------:|:--------------:|:----------:|
| **VNX Context Rotation** | ✅ PreToolUse hook | ✅ async nohup | ✅ SessionStart + rotator | ✅ mkdir + TTL | ✅ |
| **[claude-code-handoff](https://github.com/Sonovore/claude-code-handoff)** | — manual `/handoff` | — | ✅ SessionStart hook | — | — |
| **[claude-session-restore](https://github.com/ZENG3LD/claude-session-restore)** | — manual CLI | — | ✅ transcript parsing | — | — |
| **[claude\_code\_agent\_farm](https://github.com/Dicklesworthstone/claude_code_agent_farm)** | Semi (threshold flag) | ✅ Ctrl+R broadcast | — task queue restart | — | — |
| **[/wipe gist](https://gist.github.com/GGPrompts/62bbf077596dc47d9f424276575007a1)** | — manual `/wipe` | ✅ send-keys | ✅ paste-buffer | — | — |
| **[claude-code-context-sync](https://github.com/Claudate/claude-code-context-sync)** | — manual save | — | ✅ cross-window sync | — | — |

Here's what each project misses:

**[claude-code-handoff](https://github.com/Sonovore/claude-code-handoff)** is the most recent (February 2026). It uses a `/handoff` slash command that generates a context file, which a SessionStart hook injects on the next session. Solid recovery mechanism — but you have to manually decide when to rotate and manually trigger `/clear`. No pressure detection, no automation.

**[claude-session-restore](https://github.com/ZENG3LD/claude-session-restore)** takes a different approach entirely: it's a Rust CLI that parses JSONL session files after the fact. Multi-vector analysis (tasks, user messages, tool operations, git history) to reconstruct context. Powerful for forensics, but it's a reconstruction tool, not a real-time intervention.

**[claude\_code\_agent\_farm](https://github.com/Dicklesworthstone/claude_code_agent_farm)** is the most architecturally similar to what I built — multi-agent tmux orchestration with 20+ parallel agents. It has a `--context-threshold` parameter that lets agents self-clear. But after clearing, agents restart from their task queue with no handover document. Session continuity is lost. The work the agent did before clearing? Gone, unless it happened to commit something.

**[The /wipe gist](https://gist.github.com/GGPrompts/62bbf077596dc47d9f424276575007a1)** is technically closest to the VNX rotation flow. It uses the same `tmux send-keys` + `load-buffer` + `paste-buffer` pattern for clearing and injecting. But it's a manually triggered slash command with a fixed 8-second delay instead of signal-based coordination. No locking, no multi-terminal awareness, no automatic pressure detection.

**[claude-code-context-sync](https://github.com/Claudate/claude-code-context-sync)** focuses on multi-window context synchronization — saving and resuming context across different windows. Useful for a different workflow, but no automatic detection or clearing.

The gap: every project solves one or two parts of the problem. None connect all four: automatic detection → structured handover → tmux clear → continuation injection. That's the closed loop I couldn't find and had to build. The full implementation is **[open source on GitHub](https://github.com/Vinix24/vnx-orchestration)** — including the hook chain, lock mechanism, and handover templates.

There are also multiple open feature requests on the **[Anthropic Claude Code repository](https://github.com/anthropics/claude-code)** asking for native solutions to this problem — from **[context window reset without session restart](https://github.com/anthropics/claude-code/issues/3314)** to **[session handoff and continuity support](https://github.com/anthropics/claude-code/issues/11455)** to **[context management CLI flags](https://github.com/anthropics/claude-code/issues/21388)**. The original **[hook-based /clear request (#9118)](https://github.com/anthropics/claude-code/issues/9118)** was closed as NOT\_PLANNED, and related issues like **[restoring blocking Stop command hooks (#3656)](https://github.com/anthropics/claude-code/issues/3656)** and **[/clear breaking transcript hooks (#3046)](https://github.com/anthropics/claude-code/issues/3046)** remain open. The demand is clear. The supply, for now, is community workarounds.

## The safety mechanisms

Running automatic context rotation in production requires more than just the happy path. Here's what I built to prevent things from going wrong:

**Atomic locking.** When the PostToolUse hook triggers rotation, it acquires a `mkdir`-based lock with timestamp-based stale detection (300-second TTL). This prevents double-rotation when multiple terminals try to rotate simultaneously. One terminal rotates; the others wait.

**Loop prevention.** The PreToolUse hook passes `Write`, `Read`, `Glob`, and `Grep` through unconditionally, even when context pressure is high. This is critical — without it, the hook would block the agent from writing the handover document, creating a deadlock where the agent needs to write a file to rotate but can't write a file because rotation is pending.

**Multi-terminal isolation.** Each terminal (T1/T2/T3) has independent pane resolution, lock files, and handover documents. T0 — the orchestrator — is excluded from rotation entirely. The orchestrator's context is long-lived by design and manages terminal coordination, so clearing it would break the system.

**Fallback chain.** The SessionStart recovery hook supports a `--fallback` parameter so worker terminals bootstrapping fresh tasks don't get confused by rotation recovery. A fresh dispatch shouldn't inherit a rotation handover from a previous task.

## What I learned about timing

The biggest surprise from production testing: 65% is already late. I'm now experimenting with rotation at 60% — even 55% for complex tasks where context quality is critical.

The reasoning: context quality doesn't degrade linearly. This aligns with the research — the "Lost in the Middle" paper showed that degradation accelerates in the later portions of the context window, not gradually across the full length. At 50% context usage, everything is fine. At 65%, you start losing nuance in the compacted regions. At 75%, the agent is noticeably worse — it starts re-reading files, contradicting earlier decisions. By 80%, Claude Code's auto-compaction fires and you've lost the war.

The sweet spot appears to be rotating when the context is still healthy — before you notice degradation, not after. It feels wasteful to clear a session that's still working well. But the handover quality is much higher when the agent writes it from a position of strength rather than under pressure. An agent at 60% context writes a clear, structured handover with specific details. An agent at 78% writes vague summaries and misses critical state.

I track every rotation event in the **[VNX receipt ledger](https://github.com/Vinix24/vnx-orchestration#receipt-ledger)** — the same append-only NDJSON file that logs all agent actions. This gives me data on rotation frequency, handover quality, and task completion rates before and after rotation. Early data suggests that proactive rotation (60-65%) produces better handover documents and faster task resumption than reactive rotation (75%+).

> **"The best time to rotate context is when you don't think you need to yet."**
> That's the counterintuitive lesson from six months of production data. An agent writing a handover at 60% context produces clear, structured state. At 78%, it writes vague summaries and misses critical details. Rotate from strength, not desperation.

Context quality curve showing sweet spot between 60-65%

## Known limitations

I want to be honest about what doesn't work perfectly.

**tmux timing race.** There's a small window (~1-2 seconds) after `/clear` where the terminal may not be ready for input. The rotator mitigates this with a settle delay and signal file, but it's not 100% deterministic. Occasionally the continuation prompt arrives before the session is fully initialized.

**Handover quality varies.** The handover document is written by Claude under context pressure. Sometimes the "Remaining Tasks" section is vague. Sometimes critical details are missing. The structured format constrains it enough to be usually useful, but "usually" isn't "always."

**No native Anthropic support.** This entire system exists because `/clear` can't be called from hooks (**[#9118](https://github.com/anthropics/claude-code/issues/9118)** — NOT\_PLANNED). If Anthropic ever adds **[native context management support](https://github.com/anthropics/claude-code/issues/3314)**, the tmux workaround becomes unnecessary — and good riddance. The workaround works, but it's fragile compared to what a native implementation could be.

**Skill context lost on /clear.** Active Claude Code skills are not preserved across rotation. The rotator re-activates the original skill via a `/{skill}` prefix on the continuation prompt, recovered from the original dispatch file. This works, but it means the skill reloads from scratch — any in-session skill state is lost.

## Try it yourself

Context rotation is part of the **[VNX Orchestration System](https://github.com/Vinix24/vnx-orchestration)** — an open-source toolkit for multi-agent terminal workflows. The rotation feature is opt-in:

You need Claude Code with hooks support, tmux, and Bash 4+. The full setup is three hook registrations in `.claude/settings.json` and one environment variable. The documentation covers the complete hook chain, file structure, and configuration options.

> 📖 **Read also:** **[Multi-Model AI Orchestration From a Single Terminal](/blog/multi-model-ai-orchestration-single-terminal)** — How I run Claude, Codex, and Gemini in parallel with unified governance

The dry-run demo (`demo/dry-run/replay.sh --fast`) shows the full governance pipeline — including context rotation — without requiring any LLM API calls.

## Quick wins before you need full rotation

Not every session needs the full rotation pipeline. Here are lighter context management strategies that reduce the rate of context rot:

**Use subagents for research.** Subagents run in separate context windows and return only summaries. Delegate file scanning, code reviews, or research tasks to subagents — your main context stays clean. But subagents don't solve the core problem: your main session still fills up during multi-hour implementation work. They reduce the *rate* of rot; rotation addresses the rot itself.

**Maintain a strong CLAUDE.md.** Your CLAUDE.md file persists across sessions — it's your *persistent* context layer. Architecture decisions, coding conventions, project structure — put it there so every session starts informed. But CLAUDE.md handles persistent knowledge; rotation handles *session* state. You need both.

**Use Plan mode for complex tasks.** Plan mode (think before acting) can reduce token usage by 30-40% on complex tasks because it structures reasoning before generating code. Fewer tokens consumed means slower context fill rate.

**Use skills for progressive disclosure.** Claude Code skills load 30-50 tokens initially and expand on demand — far cheaper than MCP servers that load their full schema upfront. Prefer skills over MCP for operations you invoke frequently.

These strategies buy you time. But for multi-hour production sessions — especially multi-agent workflows — automatic rotation remains the definitive solution.

## Context engineering: the bigger picture

Context rot isn't a Claude-specific problem. Every AI coding agent with a fixed context window will hit this wall. Cursor, Cline, Codex CLI, Gemini Code — they all operate within context limits, and they all degrade when those limits are reached.

This is part of a broader discipline emerging in the AI engineering community: **context engineering** — the practice of deliberately structuring what information reaches your model, when, and in what form. Martin Fowler recently wrote about this: the most impactful skill in AI-assisted development isn't prompt engineering, it's context engineering.

Automatic context rotation is one pattern within context engineering. Others include subagent delegation, progressive context loading, and structured handover contracts. The solution doesn't have to look like mine. But the pattern — detect pressure, checkpoint state, clear, resume — is universal. Whether it's implemented as hooks + tmux, or native IDE support, or a language server protocol extension, the need is the same: AI coding sessions need a way to rotate context without losing continuity.

For organizations looking to deploy AI agents in production, this challenge is amplified. **[Smaller companies adopting AI](/ai-voor-het-mkb)** especially need reliable, low-friction solutions — they can't afford to lose work due to context degradation.

Right now, most developers just accept context degradation as a fact of life. They restart sessions manually, lose progress, and re-explain their codebase from scratch. That's the equivalent of rebooting your computer every hour because it runs out of RAM. We can do better.

If you're hitting the context wall in your AI coding workflow, I'd be curious to hear how you handle it. And if you have ideas for improving automatic rotation — better handover formats, smarter timing heuristics, alternative clear mechanisms — the repo is open and I'm building in public.

## Frequently Asked Questions

### Why does Claude Code get dumber the longer I use it?

Claude Code operates within a 200K token context window. As you work, every file read, message, and tool result fills that budget. When it approaches capacity (~80%), auto-compaction kicks in — a lossy summary that drops nuance. The model doesn't change; your working memory shrinks. This is context rot. Symptoms: repeating work, contradicting earlier decisions, re-reading files already processed.

### What is auto-compaction in Claude Code and how does it affect my session?

Auto-compaction triggers when context usage hits roughly 80-95%. Claude summarizes older messages to free space. The tradeoff: a 50-line architectural discussion becomes one sentence. You keep working but the agent loses the *why* behind decisions. Some developers disable auto-compact entirely and manage context manually via `/compact` or `/clear`.

### How do I preserve context between Claude Code sessions?

Three common approaches: (1) Write a handover document before ending a session, then reference it in the next. (2) Use a SessionStart hook to auto-inject project state. (3) Use CLAUDE.md for persistent project context that survives across sessions. The most robust approach combines all three — which is what the VNX rotation pipeline automates.

### Should I use /clear or /compact when Claude Code's context fills up?

`/compact` summarizes and preserves some history — good for short sessions or simple tasks. `/clear` wipes everything — better for a true fresh start. The problem: both lose nuance. The ideal is to write a structured handover *before* clearing, so the next session starts with clean context plus your saved state. Automatic context rotation automates this entire flow.

### How do Claude Code hooks help with context management?

Hooks are shell commands that fire at specific lifecycle events (SessionStart, PreToolUse, PostToolUse). For context management: a PreToolUse hook can monitor context usage and block work when pressure is high. A SessionStart hook can inject context from a previous session. Combined, they enable automatic context rotation without manual intervention.

### What is the best context threshold for rotating a Claude Code session?

Counter-intuitively, earlier is better. At 60-65% context usage, the agent still writes clear, structured handovers with specific details. At 75%+, handover quality drops — vague summaries, missing state. Rotate before you notice degradation, not after. Claude Code's auto-compaction fires around 80%, so rotating at 65% gives enough headroom to complete the handover cleanly.

### Can I use subagents to avoid context rot in Claude Code?

Subagents run in separate context windows and return only summaries, keeping your main context clean. But subagents don't solve the core problem: your main session still fills up during multi-hour implementation work. Subagents reduce the *rate* of rot; context rotation addresses the rot itself. Use both together for maximum session longevity.

### Does context rot affect all AI coding agents, not just Claude Code?

Yes. Any AI agent with a fixed context window — Cursor, Cline, Codex CLI, Gemini Code — will degrade when that window fills. The "Lost in the Middle" research (Stanford, 2024) shows this is a fundamental LLM limitation: performance drops 15-47% as context grows. The solution pattern — detect, checkpoint, clear, resume — is universal regardless of the specific tool.

***

*If you're interested in the multi-agent system that context rotation is part of, read **[Glass Box Governance: How I Built a Self-Auditing Multi-Agent AI System](/blog/glass-box-governance-multi-agent-ai)** — where I explain the full orchestration architecture, receipt-driven audit trails, and why transparency beats trust in production AI.*

context rot claude code automatic rotation cover

large_context-rot-claude-code-automatic-rotation_cover

medium_context-rot-claude-code-automatic-rotation_cover

small_context-rot-claude-code-automatic-rotation_cover

thumbnail_context-rot-claude-code-automatic-rotation_cover

context-rot-claude-code-automatic-rotation_cover

Context Rot Is Silently Killing Your Claude Code Sessions — Here's How I Fixed It

## Introductie tot Claude MCP servers

In een eerdere blog schreef ik over mijn **[top 10 Claude MCP protocollen](https://vincentvandeth.nl/blog/Top10-Claude-MCP-Protocollen-AI-Agent)** over hoe je van Claude een heuse AI agent kan maken. Het installeren van deze MCP servers is een technisch verhaal maar ook voor niet technische mensen makkelijk te doen, kwestie van instructies volgen. Om het je nog makkelijker te maken heb ik een stap voor stap gids gemaakt waarmee je zelf MCP servers kan installeren voor Claude Desktop. 

Nadat je alle stappen hebt doorlopen heb je van jouw Claude Desktop een multifunctionele AI agent gemaakt en heb je geen no-code of andere agent frameworks nodig! 

Ook als je nu nog denkt aan een bus - of treinstation bij het woord terminal heb je na het lezen van deze blog al een stuk meer kennis over computersystemen. De installatiegids werkt voor zowel Mac, Windows en Linux gebruikers. 

## Claude Desktop installeren en configureren voor MCP protocollen

Voordat we beginnen is het belangrijk om te weten dat je alleen met Claude Desktop versie MCP servers kunt gebruiken, met de cloud versie kan dit niet! Download dus eerst de Claude Desktop versie van als je die nog niet gebruikt. 

**Belangrijk!** Het configuratie bestand waarvoor ik in deze blog de .json configuratie geef kun je vinden onder _Claude > Settings_. Dit is niet dezelfde settings als voor Claude Dekstop zelf. Mocht je de fout maken die ik in het begin maakt dan kun je daar zoeken tot je een ons weegt. In de Settings ga je naar de Developer tab en vind je Edit Config. Als je daar op klikt vind je het _claude_desktop_config.json_ bestand. Dat is het bestand wat je straks moet gaan aanpassen. 

**Let op bij het werken met privacy gevoelige informatie in verband met GDPR/AVG ook mijn blog over [GDPR/AVG risico bij MCP servers](https://vincentvandeth.nl/blog/cp-servers-gdpr-privacy-risicos-voor-marketeers-ondernemers) **

## De basis: Node.js installeren

Voordat we beginnen met het installeren van de MCP servers, moeten we eerst controleren of Node.js is geïnstalleerd. Node.js vormt de basis voor alle MCP server installaties.

### Stap 1: Download Node.js

Ga naar de Node.js website: **[https://nodejs.org/](https://nodejs.org/)**

**Tip:** Kies de "LTS" versie (Long Term Support). Dit is de meest stabiele versie en perfect voor de meeste gebruikers. Klik op de downloadknop voor uw besturingssysteem (Windows, macOS of Linux).

### Stap 2: Installatie uitvoeren

De installatie is grotendeels geautomatiseerd en eenvoudig te volgen:

- **Windows:** Open het gedownloade .msi bestand en volg de instructies. Accepteer de standaardinstellingen door op "Next" te klikken bij elke stap, en klik op "Finish" wanneer de installatie is voltooid.

- **Mac:** Open het .pkg bestand en volg de installatie-instructies. Accepteer de standaardinstellingen, klik op "Continue" en "Install". U moet mogelijk uw wachtwoord invoeren om de installatie te autoriseren. Klik op "Close" wanneer de installatie is voltooid.

- **Linux:** De installatieprocedure kan per distributie verschillen. Raadpleeg de Node.js website voor specifieke instructies voor uw Linux-versie onder "Installing Node.js via package manager": [https://nodejs.org/en/download/package-manager/](https://nodejs.org/en/download/package-manager/). Voor Debian/Ubuntu gebruikt u doorgaans `sudo apt-get install nodejs npm` en voor Fedora/CentOS/RHEL `sudo dnf install nodejs`.

### Stap 3: Controleer de installatie

Om te verifiëren dat Node.js correct is geïnstalleerd, opent u de terminal (of opdrachtprompt in Windows):

- **Windows:** Druk op de Windows-toets, typ "cmd" of "opdrachtprompt" en druk op Enter.
- **Mac:** Open Finder → Programma's → Hulpprogramma's → Terminal.
- **Linux:** Gebruik de sneltoets Ctrl+Alt+T of zoek "Terminal" in het applicatiemenu.






Typ de volgende commando's en druk na elke regel op Enter:

Als de installatie succesvol was, zie je versienummers verschijnen (bijvoorbeeld v20.18.2 en 10.8.2). Dit bevestigt dat Node.js correct is geïnstalleerd en klaar is voor gebruik.

## Het configuratiebestand vinden in Claude Desktop

Voordat we beginnen met het installeren van de MCP servers, is het belangrijk om te weten waar u het configuratiebestand kunt vinden dat we later gaan aanpassen.

1. Open Claude Desktop
2. Klik op het tandwiel-icoon voor **Instellingen**
3. Ga naar het menu-item **Developer**
4. Klik op de knop **Edit config**
5. Je configuratiemap opent nu in uw bestandsverkenner
6. In deze map vind je het bestand `claude_desktop_config.json` waarin we de MCP server instellingen gaan toevoegen

In Claude desktop vind je in het developers console de knop om het configuratie bestand te vinden

## 1. Memory Server: Behoud context en bespaar tokens

**Wat het doet:** De Memory Server onthoudt de context van uw gesprekken met Claude, waardoor u tokens bespaart en de continuïteit in langere projecten behouden blijft.

### Stap-voor-stap installatie:

1. Open een nieuwe terminal (of opdrachtprompt)
2. Voer het volgende commando uit:







3. Voeg de server toe in Claude Desktop:

1. Open het configuratie bestand via _Claude>Settings_ in de menubar. 
2. Ga naar het developer console
3. Op het configuratie bestand
4. Voeg onderstaande regel toe in het .json bestand
5. Vul bij /path/to/custom/ de folder in waar je hem wilt hebben (Bij mij bijvoorbeeld /Users/vincentvandeth/Desktop/Development/MCP)

### JSON Configuratie:

### Testen:

Start een nieuwe chat met Claude. Bespreek een onderwerp, sluit Claude Desktop af, open het opnieuw om het geheugen te activeren. Voer een gesprek met Claude en vraag hem om het gesprek in het geheugen op te slaan. Claude slaat niet automatisch alles op. In een volgende gesprek verwijs je Claude naar het geheugen en heeft hij meteen de context van het gesprek te pakken. 

Ik schrijf een aparte blog over hoe je efficient met het geheugen kan werken. Als je in de tussentijd vragen hebt mail me of stuur me een bericht op **[Linkedin](https://www.linkedin.com/in/vincentvandeth/)**

## 2. Filesystem Server: Directe toegang tot je bestanden

**Wat het doet:** De Filesystem Server geeft Claude directe toegang tot bestanden op uw computer, ideaal voor het bewerken van documenten of het verfijnen van code.

### Stap-voor-stap installatie:

1. Open een nieuwe terminal (of opdrachtprompt)
2. Voer het volgende commando uit:

3. Voeg de server toe in Claude Desktop:

1. Open het configuratie bestand via _Claude>Settings_ in de menubar. 
2. Ga naar het developer console
3. Op het configuratie bestand
4. Voeg onderstaande regel toe in het .json bestand
5. Vul bij /Users/jouwgebruikersnaam de folder in waar je hem wilt hebben 

Bij mij bijvoorbeeld:

Users/vincentvandeth/Desktop/Development/VNXcrawlerdevelopment/
Users/vincentvandeth/Desktop/Development/vinix-marketing/folder1/

Let goed op op welke folders je rechten geeft want dat zijn de folders waarin Claude kan zoeken, lezenk, schrijven, nieuwe folders aanmaken etc. Als je documentatie hebt met privacy gevoelig info die niet selecteren. 


### JSON Configuratie:   







**Belangrijk voor Mac en Linux gebruikers:** Het kan nodig zijn om in uw privacy-instellingen expliciet toegang te verlenen tot bepaalde mappen. Controleer de instellingen voor 'Bestanden en Mappen' als u problemen ondervindt.

### Testen:

Maak een tekstbestand in de geselecteerde map. Start een nieuwe chat met Claude en vraag: "Kun je het bestand [bestandsnaam] in de map [mapnaam] lezen?". Als Claude de inhoud kan lezen, werkt de Filesystem Server correct.

Handige tip: Vraag Claude in een prompt om bepaalde bestanden te lezen als achtergrond informatie. Je kunt Claude opdracht geven rechtstreeks in toegestane folders wijzigingen aan te brengen. Dit werkt ook voor bestanden die code bevatten. 

## 3. Brave Search Server: Realtime webinformatie

**Wat het doet:** Integreert Brave Search, een privacy-vriendelijke zoekmachine, direct in Claude voor efficiënt webonderzoek.

### Stap-voor-stap installatie:

1. Open een nieuwe terminal (of opdrachtprompt)
2. Voer het volgende commando uit:

3. Voeg de server toe in Claude Desktop:

1. Open het configuratie bestand via _Claude>Settings_ in de menubar. 
2. Ga naar het developer console
3. Op het configuratie bestand
4. Voeg onderstaande regel toe in het .json bestand
5. Vul bij API sleutel de API sleutel in die je van de website van Brave Search gratis kan halen

### Testen:

Start een nieuwe chat met Claude en vraag: "Zoek op internet naar de laatste trends in digitale marketing". Als Claude recente informatie van het web teruggeeft, werkt de Brave Search Server correct.

## 4. Perplexity Search Server: Diepgaand onderzoek

**Wat het doet:** Integreert Perplexity AI voor diepgaande, gecureerde zoekresultaten, perfect voor serieuze marktanalyse.

#### Stap-voor-stap installatie:

1. Open een nieuwe terminal (of opdrachtprompt)
2. Voer het volgende commando uit:

3. Voeg de server toe in Claude Desktop:

1. Open het configuratie bestand via _Claude>Settings_ in de menubar. 
2. Ga naar het developer console
3. Op het configuratie bestand
4. Voeg onderstaande regel toe in het .json bestand
5. Vul bij API sleutel de API sleutel in die je van de website van Perplexity haalt. Deze is helaas niet gratis maar zeer de moeite waar omdat Claude zelf instructies kan geven aan Perplexity en zo altijd de informatie zoekt die relevant is voor de opdracht waar je mee bezig bent. 

### JSON Configuratie:

### Testen:

Start een nieuwe chat en vraag Claude: "Zoek met Perplexity naar de impact van AI op de e-commerce industrie". Vergelijk deze resultaten met een reguliere zoekopdracht om het verschil in diepgang te zien.

## 6. GitHub Server: Codebeheer voor tech-professionals

**Wat het doet:** Integreert GitHub-functionaliteit in Claude, ideaal voor code generatie, review en beheer.

### Stap-voor-stap installatie:

1. Open een nieuwe terminal (of opdrachtprompt)
2. Voer het volgende commando uit:

3. Genereer een GitHub Personal Access Token:

1. Ga naar je Github profiel naar _Settings_
2. Ga naar <> Developer settings helemaal onderaan de lijst
3. Kies Personal acces tokens > fine grained tokens
4. Generate new token
5. Vink tenminste  'Read access to codespaces metadata and metadata,
read and Write access to actions, administration, code, commit statuses, pull requests en workflows aan.



### Toevoegen in Claude Desktop:

1. Open het configuratie bestand via _Claude>Settings_ in de menubar. 
2. Ga naar het developer console
3. Op het configuratie bestand
4. Voeg onderstaande regel toe in het .json bestand
5. Vul bij GITHUB_TOKEN het token in wat je op de website van Github hebt gehaald.  

### JSON configuratie:

### Testen:

Start een nieuwe chat en vraag Claude: "Geef overzicht open issues in GitHub repository [gebruikersnaam]/[repository-naam]"

Tip: Maak een fine grained token dan kun je precies instellen wat Claude wel en niet mag doen hierdoor voorkom je dat Claude dingen kan inzien of bewerken die misschien gevoelig zijn. 

**Let op bij het werken met privacy gevoelige informatie in verband met GDPR/AVG ook mijn blog over [GDPR/AVG risico bij MCP servers](https://vincentvandeth.nl/blog/cp-servers-gdpr-privacy-risicos-voor-marketeers-ondernemers) ** 

## 7. ArXiv Search Server Installeren

**Wat het doet:** Integreert ArXiv, het archief voor wetenschappelijke papers, in Claude voor diepgaande research.

### Stap-voor-Stap Installatie:

Deze is iets ingewikkelder dan de andere servers omdat je hiervoor het project op Githubn nodig hebt. Als je stap 6 succesvol hebt afgerond dan kun je gewoon Claude vragen om de server te clonen en je door de installatie te leiden. 

Heb je geen Github? Geen probleem. Het kan ook handmatig:

1. Maak een folder aan waar je de server wilt hebben: /users/jouwnaam/ArXiv bijvoorbeeld
2. Open een terminal en type: cd //users/jouwnaam/ArXiv uit het vorige voorbeeld. Je zou nu in de terminal moeten zien dat je in die map staat (zie schermprint waar ik /users/vincentvandeth/desktop/development heb gebruikt. 
3. Kopieer dit commando in je terminal. Die haalt ArXiv op van Github:

### Toevoegen in Claude Desktop:

1. Open het configuratie bestand via _Claude>Settings_ in de menubar. 
2. Ga naar het developer console
3. Op het configuratie bestand
4. Voeg onderstaande regel toe in het .json bestand
5. Vul jouw API key in die haal je **[hier](https://info.arxiv.org/help/api/index.html)**

### JSON Configuratie:

### Testen:

Start een nieuwe chat en vraag Claude: "Zoek op ArXiv naar recente papers over AI in medical diagnostics"

## 8. Google Search Server Installeren

**Wat het doet:** Integreert Google Search in Claude voor maximale zoekdekking.

### Stap-voor-Stap Installatie:

1. Open een nieuwe Terminal of Opdrachtprompt
2. Installeer met NPM:

### Google Custom Search Engine Configureren:

1. Ga naar de [Google Custom Search Engine website](https://programmablesearchengine.google.com/)
2. Maak een Custom Search Engine aan
3. Genereer een API Key en Search Engine ID via de Google Cloud Console

### Toevoegen in Claude Desktop:

1. Open het configuratie bestand via _Claude>Settings_ in de menubar. 
2. Ga naar het developer console
3. Op het configuratie bestand
4. Voeg onderstaande regel toe in het .json bestand
5. API Key: Vul jouw Google Custom Search Engine API Key in
4. Search Engine ID: Vul jouw Google Custom Search Engine ID in
5. Ingeschakeld: Aanvinken
6. Klik op 'Opslaan'

### JSON Configuratie:

## Testen:

Start een nieuwe chat en vraag Claude: "Google: Zoek naar recente ontwikkelingen in digitale marketing"

## 9. WolframAlpha Server Installeren

**Wat het doet:** Integreert WolframAlpha in Claude voor complexe berekeningen en datavisualisatie.

### Stap-voor-Stap Installatie:

Net als ArXiv heb je voor Wolfram Alpha de repository van Github nodig. Als je stap 6 succesvol hebt afgerond dan kun je gewoon Claude vragen om de server te clonen en je door de installatie te leiden. 

Heb je geen Github? Geen probleem. Het kan ook handmatig:

1. Maak een folder aan waar je de server wilt hebben: /users/jouwnaam/Wolfram Alpha bijvoorbeeld
2. Open een terminal en type: cd //users/jouwnaam/ArXiv uit het vorige voorbeeld. Je zou nu in de terminal moeten zien dat je in die map staat (zie schermprint waar ik /users/vincentvandeth/desktop/development heb gebruikt. 
3. Kopieer dit commando in je terminal. Die haalt Wolfram Alpha op van Github:

### WolframAlpha API Key Genereren:

1. Ga naar de [WolframAlpha website](https://developer.wolframalpha.com/)
2. Maak een account aan en vraag een API Key aan

### Toevoegen in Claude Desktop:

1. Open het configuratie bestand via _Claude>Settings_ in de menubar. 
2. Ga naar het developer console
3. Op het configuratie bestand
4. Voeg onderstaande regel toe in het .json bestand
5. API Key: Vul jouw Wolfram Alpha key hier in


### JSON Configuratie:

### Testen:

Start een nieuwe chat en vraag Claude: "WolframAlpha: Bereken ROI met investering €10.000, opbrengst €25.000, visualiseer in taartdiagram"

## 10. DuckDuckGo Search Server Installeren

**Wat het doet:** Integreert DuckDuckGo, een privacy-vriendelijke zoekmachine, in Claude.

### Stap-voor-Stap Installatie:

1. Open een nieuwe Terminal of Opdrachtprompt
2. Installeer met NPM:

### Toevoegen in Claude Desktop:

1. Open het configuratie bestand via _Claude>Settings_ in de menubar. 
2. Ga naar het developer console
3. Op het configuratie bestand
4. Voeg onderstaande regel toe in het .json bestand
5. API Key: Niet nodig

### JSON Configuratie:


### Testen:

Start een nieuwe chat en vraag Claude: "DuckDuckGo: Zoek naar privacy-vriendelijke zoekmachines"

## Complete JSON Configuratie

Nadat je meerdere servers hebt toegevoegd, ziet uw servers sectie in de config.json file er ongeveer zo uit:

**Belangrijk:** Vervang alle placeholders (UW_API_KEY, UW_GITHUB_PERSONAL_ACCESS_TOKEN, etc.) en voorbeeldpaden met je eigen API keys, tokens en bestandspaden. U kunt deze JSON direct aanpassen in het "JSON Bewerken" tabblad in Claude Desktop (MCP Servers instellingen).

## Conclusie

Gefeliciteerd! Je hebt Claude Desktop uitgebreid met 10 krachtige MCP servers. Deze uitbreidingen maken Claude tot een super AI agent. Experimenteer met deze nieuwe mogelijkheden om te ontdekken hoe ze jouw workflow kunnen optimaliseren.

De MCP community blijft groeien, en er komen regelmatig nieuwe servers beschikbaar. Houd mijn blog in de gaten voor updates over de nieuwste ontwikkelingen.

### Disclaimer

Wees altijd voorzichtig met het installeren van software en het verlenen van toegang tot uw bestanden en online accounts. Gebruik servers van vertrouwde bronnen en lees de documentatie zorgvuldig door. Veiligheid staat voorop!


---

Heb je vragen of hulp nodig bij het installeren? Stuur me een mail of berichtop **[Linkedin](https://www.linkedin.com/in/vincentvandeth/)**


Claude Code

Opus 4.7 Is a Mirror Test for Your Prompt Stack

I Replaced OpenClaw With Claude Code Channels, a Worker Daemon, and 8 Agent Directories

Best OpenClaw Alternative? How CLI Subprocess Orchestration Survives Anthropic's OAuth Ban

Claude Agent Teams vs. Building Your Own: What Anthropic Solved (And What They Left Out)

Context Rot Is Silently Killing Your Claude Code Sessions — Here's How I Fixed It

Hoe moet ik Claude MCP servers installeren? Een stap voor stap gids