TL;DR — DeepSeek ships an Anthropic-compatible API endpoint that lets Claude Code treat DeepSeek V4 Pro like a drop-in replacement for Claude Opus. The setup is eight environment variables, and it works — including tool calling, sub-agent spawning, and native web search. At $0.435/M input tokens (permanent price after the initial launch promo), it’s roughly 4–17× cheaper than Claude Opus 4.7. This is a practical guide based on a real setup we run daily.

Why This Matters

Claude Code is Anthropic’s terminal-based AI coding agent. It reads your codebase, runs bash commands, spawns sub-agents, and writes edits — all through Anthropic’s API. The problem: it only speaks Anthropic’s message format. You can’t point it at OpenAI, Gemini, or a local Ollama instance without a translation layer.

DeepSeek solved this the obvious way: they built an Anthropic-compatible API endpoint at https://api.deepseek.com/anthropic and documented the Claude Code integration on day one. No proxy, no wrapper, no SDK fork. Just environment variables.

We’ve been running this setup in production — managing a multi-project workspace with six active sub-projects, MCP servers, and daily coding sessions. Here’s what works, what doesn’t, and the exact configuration.

Step 1: Get a DeepSeek API Key

Sign up at platform.deepseek.com and create an API key. DeepSeek uses prepaid balance — top up what you need, no subscription.

Two models matter for Claude Code:

After the initial launch promotion ends (2026-05-31), DeepSeek permanently adjusts the official price to 1/4 of the original — so $0.435/M input becomes the new normal, not a temporary deal. That’s still 34× cheaper than Claude Opus 4.7 ($15/M input, ~$75/M output) on input tokens. V4 Flash stays as-is.

Cache hits are absurdly cheap: $0.003625/M for V4 Pro and $0.0028/M for V4 Flash. Claude Code generates a lot of repetitive context (system prompts, CLAUDE.md files, tool definitions), so cache hits dominate real usage.

Step 2: Configure Environment Variables

Create a shell script (we call ours claude.sh) and source it before launching Claude Code:

1
2
3
4
5
6
7
8

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<your-deepseek-api-key>
export ANTHROPIC_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-v4-flash
export CLAUDE_CODE_EFFORT_LEVEL=max

Then launch:

1
2
3

source claude.sh
cd /path/to/your/project
claude

What each variable does:

The [1m] suffix on model names is a DeepSeek convention for requesting the 1M-token context window. Without it, you get the default context length.

Step 3: Understand Model Mapping

DeepSeek does automatic model name mapping. When Claude Code internally requests claude-opus-4-7, DeepSeek’s API maps it:

claude-opus-*    →  deepseek-v4-pro
claude-sonnet-*  →  deepseek-v4-flash
claude-haiku-*   →  deepseek-v4-flash

This means you don’t need to patch Claude Code’s source. When the agent decides it needs “Opus-level” reasoning, DeepSeek routes it to V4 Pro. When it wants Haiku for a fast sub-agent, it gets V4 Flash.

We explicitly set the model variables anyway (rather than relying on mapping) because it gives us control over which model handles sub-agents. V4 Flash is fast enough for search and file-reading sub-agents, and it’s 3× cheaper than V4 Pro on input.

What Actually Works

Tool Calling

DeepSeek’s Anthropic API fully supports tool_use and tool_result message types. Claude Code’s entire agent loop is built on tool calling — Read, Write, Edit, Bash, Grep, Glob — and all of it works.

Message: array, type = "tool_use"
  - id:           Fully Supported
  - input:        Fully Supported
  - name:         Fully Supported
  - cache_control: Ignored

Message: array, type = "tool_result"
  - tool_use_id:  Fully Supported
  - content:      Fully Supported
  - is_error:     Ignored

Sub-Agent Spawning

Claude Code spawns specialized sub-agents (Explore for file search, Plan for architecture, etc.) using the Agent tool. Each sub-agent is itself a tool-calling loop with restricted permissions. This works on DeepSeek — we’ve tested multi-agent sessions where the main V4 Pro agent spawns V4 Flash sub-agents for file search, and the results flow back correctly.

Web Search (the surprising part)

This is the feature that caught us off guard. DeepSeek’s API natively supports Claude Code’s built-in Web Search tool. When the model determines your question needs web results, it invokes the search tool through DeepSeek’s own search infrastructure — not Anthropic’s.

From DeepSeek’s documentation:

“The DeepSeek API natively supports the Web Search feature in Claude Code. When using Claude Code, if the model determines that your question requires a web search, it will invoke the Web Search tool and perform the search through the API provided by DeepSeek.”

In practice: ask Claude Code “what’s the latest version of LangGraph?” and it will trigger a web search, get results, and summarize them — all through DeepSeek. The web_search_tool_result message type is fully supported in the API.

Cost caveat: Each web search triggers additional LLM API calls to summarize the retrieved content. DeepSeek bills these as normal token usage. A single search-then-summarize cycle might consume 5–20K extra input tokens.

Thinking Mode

DeepSeek V4 supports thinking mode (extended reasoning). The thinking field in the API is supported, though budget_tokens is ignored — DeepSeek manages its own reasoning budget internally. Setting CLAUDE_CODE_EFFORT_LEVEL=max gives the model maximum latitude to think.

Streaming

Fully supported. Responses stream token-by-token just like native Claude.

What Doesn’t Work

Being honest about limitations matters. DeepSeek’s Anthropic API is not a perfect clone — it’s a pragmatic subset.

No Image or Document Input

array, type = "image"     →  Not Supported
array, type = "document"  →  Not Supported

You can’t paste screenshots or upload PDFs through Claude Code when using DeepSeek. If your workflow involves vision tasks (analyzing UI mockups, reading diagrams), you need native Claude or a vision-capable model for those sessions.

No Prompt Caching

cache_control  →  Ignored (on tools, messages, and tool results)

DeepSeek has its own context caching (cache hits are priced separately), but the Anthropic-compatible endpoint ignores cache_control markers. Caching happens at DeepSeek’s discretion based on content similarity, not explicit breakpoints.

No MCP Tool Passthrough

array, type = "mcp_tool_use"     →  Not Supported
array, type = "mcp_tool_result"  →  Not Supported

MCP (Model Context Protocol) tools work differently — they’re handled client-side by Claude Code, not server-side by the API. So MCP tools like SearXNG, filesystem watchers, or database connectors still work because Claude Code intercepts them before they hit the API. The “not supported” here means DeepSeek’s API won’t process MCP messages natively, which doesn’t affect actual functionality.

Minor Field Ignorances

• top_k — ignored
• anthropic-beta / anthropic-version headers — ignored
• stop_sequences — fully supported
• container, mcp_servers, service_tier — ignored

None of these affect core Claude Code functionality.

Cost Comparison

A realistic Claude Code session: ~500K input tokens (system prompt + context + tool definitions) and ~50K output tokens.

With the main agent on V4 Pro and sub-agents on V4 Flash, a typical mixed session costs around $0.15–0.30. That’s roughly 30–70× cheaper than Claude Opus direct — and it’s the permanent price, not a limited-time promo.

The cache hit pricing makes repetitive sessions (same project, same CLAUDE.md, same tool definitions) even cheaper. Our workspace loads ~80K tokens of context on every session start — most of that hits cache at $0.003625/M.

Real-World Tips

Use a wrapper script

Don’t export environment variables in your .bashrc globally — you’ll accidentally use DeepSeek for tools that need native Claude (like vision tasks). We use a claude.sh script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

#!/bin/bash
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=sk-your-key-here
export ANTHROPIC_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-v4-flash
export CLAUDE_CODE_EFFORT_LEVEL=max
export ANTHROPIC_USER_ID="your-username"

exec claude "$@"

Run it with bash claude.sh or source claude.sh && claude.

The ANTHROPIC_USER_ID matters

DeepSeek supports the user_id metadata field for rate limit isolation. Setting ANTHROPIC_USER_ID ensures your requests are bucketed separately from other users on the same API key — useful if you share a key across projects.

V4 Flash for routine work

If you’re doing routine file editing, formatting, or batch operations, swap ANTHROPIC_MODEL to deepseek-v4-flash. It’s 3× cheaper and fast enough for non-reasoning tasks. Save V4 Pro for architecture decisions, debugging, and complex multi-step problems.

The Bottom Line

DeepSeek’s Anthropic-compatible API is the most seamless third-party Claude Code integration available. No proxy server, no SDK patches, no feature gaps on the things that matter (tool calling, sub-agents, web search). The only real limitation is vision — if you need image input, you still need native Claude.

For pure coding work, the cost savings are dramatic enough that there’s no reason not to try it. Eight environment variables, one API key, and you’re running.

The Configuration

1
2
3
4
5
6
7
8
9

# claude.sh — Source this before running `claude`
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<your-key>
export ANTHROPIC_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-v4-flash
export CLAUDE_CODE_EFFORT_LEVEL=max

References

• DeepSeek API: Integrate with Claude Code
• DeepSeek API: Anthropic API Compatibility
• DeepSeek API: Models & Pricing
• Claude Code Official Documentation

Built with: Claude Code (latest), DeepSeek V4 Pro + V4 Flash, Node.js 22. Written from a real multi-project workspace running this setup daily.

TL;DR — We reverse-engineered Claude Code’s agent architecture from its TypeScript source to understand how it handles security, complex tasks, and tool permissions. Then we applied those patterns to an open-source Terraria AI bridge that lets players talk to an LLM inside the game. Here’s what we found, what we built, and what we learned about practical agent design.

Why We Cracked Open Claude Code’s Source

Claude Code isn’t just a coding assistant. Under the hood it’s an agent runtime — it spawns sub-agents, manages file permissions, runs bash commands, and decides when to ask the user vs. just doing the thing. We wanted to understand how it works so we could apply the same ideas to a completely different domain: a Terraria game server.

Our project, terra_llm_bridge, connects a Terraria TShock server to an LLM. Players type @ai in chat and get responses — but the LLM can also act: give items, change weather, teleport players, even toggle hardmode. That last one is where we learned our lesson.

The first time a player asked the AI to set the weather to rain, the LLM autonomously decided to call terra_world_hardmode(confirm=True) — toggling irreversible hardmode for the entire server. No player had asked for it. The model just… did it.

We needed a real permission system. So we went looking at how Claude Code does it.

Claude Code’s 7-Layer Permission Architecture

Reading through ~1,500 lines of src/utils/permissions/permissions.ts plus the Agent tool infrastructure (~3,800 lines), a clear architecture emerged. Claude Code doesn’t have one security check — it has seven:

Layer 1a: Deny rules   →  "Never allow Bash(git push --force)"
Layer 1b: Ask rules    →  "Always prompt for Bash(curl *)"
Layer 1c: Tool self-check  →  Each tool's checkPermissions() method
Layer 1d: Tool self-deny   →  Read tool whitelists specific paths
Layer 1f: Content-specific rules  →  "Even in bypass mode, ask for npm publish"
Layer 1g: Safety checks  →  ".git/, .claude/ are ALWAYS bypass-immune"
Layer 2:  Mode-based bypass  →  bypassPermissions / auto / acceptEdits / dontAsk
Layer 3:  YOLO classifier →  AI reads the transcript, decides if safe

The most interesting layer is the YOLO classifier — a separate small model that reads the full conversation transcript and classifies each tool call as safe or dangerous. It’s a two-stage system: a fast classifier for obvious cases, and a deeper thinking classifier for edge cases.

But the layer that matters most for our use case isn’t the AI classifier. It’s how Claude Code structurally prevents certain tools from being called in the wrong context — through tool allowlists, denylists, and sub-agent specialization.

The Agent Pattern: Not Multi-Agent, but Specialized Workers

Claude Code doesn’t use multi-agent “collaboration” in the negotiation sense. It uses a single coordinator that spawns specialized workers:

Main Agent (Tool Calling, all tools)
  │
  ├─ Simple: "read file X" → Read tool
  │
  └─ Complex: "audit this branch" → Agent("Explore")
                                       │
                                       ├─ Tools: [Read, Grep, Glob]  ← whitelist
                                       ├─ Disallowed: [Edit, Write]   ← denylist
                                       ├─ System prompt: "You are a file search specialist"
                                       └─ Returns findings → Main agent acts on them

Each sub-agent type is defined by three things:

1. Tool permissions (allowlist + denylist) — what it can touch
2. System prompt — specialized instructions for its role
3. Model — Explore agents use Haiku ($) for speed; Plan agents use Sonnet for reasoning

The key insight: the main agent doesn’t get more complex. It stays simple but has ONE tool (Agent) that lets it offload complex work. The sub-agent is just another Tool Calling loop with restricted tools and a different prompt.

This architecture is elegant because it composes: each piece is simple, but the combination handles complexity that would overwhelm a single prompt.

How We Applied This to terra_llm_bridge

Our Terraria bridge has a simpler job than Claude Code — 46 tools instead of hundreds, and the “security” problem is “don’t let the AI toggle hardmode when the player asked about weather” rather than “don’t let the AI rm -rf /”. But the patterns transfer directly.

The Problem

Before: our LLM saw all 46 tools at once. When a player asked “give me the strongest armor set,” the LLM would fire wiki_search AND give_item in parallel — researching while also pre-committing to Solar Flare Armor before reading the wiki results. Sometimes it guessed right. Sometimes it gave a summoner player melee gear.

Our Solution: Two-Phase Tool Access

We didn’t add sub-agents — that would be overkill for 46 tools. Instead, we applied the tool restriction pattern at the graph level:

route → llm(research)  ⇄  tool      →  escalate  →  llm(action)  ⇄  authorize  ⇄  tool  →  output
         17 read tools                            46 full tools     keyword gate
         wiki, lookup, status                     give, kick, spawn

The graph has two phases:

Research phase — the LLM gets only 17 read-only tools (wiki_search, item_lookup, player_list, world_info, etc.). It cannot call give_item, kick, spawn, or any destructive tool. It researches first.

Escalate — when the LLM produces text (no more tool calls needed), the graph automatically flips to action mode and injects a hint: “You now have access to ALL tools.”

Action phase — the LLM gets the full 46-tool set and can act on what it found.

This is structurally enforced. Not a prompt suggestion. The LLM physically cannot call give_item during research because the tool isn’t bound.

The Permission Gate

Before the two-phase split, we also added authorize_node — a hard gate between the LLM and ToolNode that checks whether the player’s recent chat messages contain keywords for the tool’s domain:

1
2
3
4
5
6

GATED_TOOLS = {
    "terra_world_hardmode": {"hardmode", "hard mode", "肉山", "困难模式"},
    "terra_player_kick":    {"kick", "踢出", "踢了"},
    "terra_server_stop":    {"stop server", "关服", "停服"},
    # ... 8 more
}

If the player says “set weather to rain” and the LLM tries to call world_hardmode, authorize_node checks: do any of the hardmode keywords appear in the player’s recent messages? No? Blocked. The tool call is replaced with a BLOCKED message before ToolNode ever sees it.

This is a coarse filter — it checks what the player mentioned, not what they requested. “上次打肉山的时候” (last time when I fought Wall of Flesh) would pass the keyword check even though the player didn’t ask for hardmode. But coarse is fine here: the goal is blocking catastrophic mismatches (weather → hardmode), not perfect intent understanding.

What We Chose NOT to Build

No YOLO Classifier

Claude Code’s AI classifier reads the full transcript and classifies tool calls as safe/dangerous. We didn’t build this because:

• It adds latency — an extra LLM call before every gated tool execution
• Terraria chat is low-stakes — a false positive (giving the wrong armor) is fixable
• Keyword matching catches the catastrophic cases

No Sub-Agent Spawning

Claude Code spawns sub-agent processes for complex tasks. We didn’t need this because:

• Terraria tool surface is small (46 tools)
• Multi-turn tool calling handles the complexity we actually face
• Spawning sub-processes for a game chat bot is over-engineering

No ReAct Pattern

The classic Thought → Action → Observation loop would add token overhead without changing our core capability. DeepSeek’s thinking tokens already handle the reasoning, and the two-phase tool access enforces “research before action” more reliably than prompt-based ReAct would.

The Architecture in One Diagram

┌──────────────────────────────────────────────────────────┐
│  Terraria Server (TShock + C# plugin, 24 game hooks)      │
│  Player types "@ai give me the best armor"                │
└──────────────────────┬───────────────────────────────────┘
                       │ JSON webhook
┌──────────────────────▼───────────────────────────────────┐
│  Python aiohttp listener (:9876)                          │
└──────────────────────┬───────────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────────┐
│  LangGraph StateGraph                                     │
│                                                           │
│  route  →  llm(research)  ⇄  tool    17 read tools      │
│               │                                           │
│          escalate  →  llm(action)  ⇄  authorize  ⇄  tool │
│                          46 full tools    keyword gate    │
│               │                                           │
│             output  →  broadcast to game chat             │
│                                                           │
│  Memory: AsyncSqliteSaver per player (thread_id)          │
└──────────────────────────────────────────────────────────┘
                       │
         ┌─────────────┴──────────────┐
         ▼                            ▼
   TShock REST API              Terraria Wiki API
   (give / kick / spawn)        (terraria.wiki.gg)

Source Diving Lessons

Reading Claude Code’s source taught us three things that apply to any agent project:

1. Security is layered, not binary. A single confirm parameter is a soft suggestion to the LLM. Real security needs structural enforcement — the LLM shouldn’t be able to call a tool it isn’t authorized to use, same way a web server shouldn’t let you access endpoints without authentication, no matter how nicely you ask.

2. Tool restrictions are the cheapest and most reliable form of safety. Claude Code’s Explore agent is “read-only” not because of a prompt — because Edit and Write aren’t in its tool list. Our research phase isn’t “research-first” because of a prompt — because give_item literally isn’t bound. You can’t prompt-inject your way past a tool that doesn’t exist.

3. Specialization beats complexity. Claude Code’s sub-agents aren’t smarter than the main agent — they’re more constrained. Fewer tools + focused prompt = more reliable behavior. Our two-phase system does the same: constrain first, expand only when ready.

The Project

terra_llm_bridge is an open-source project connecting Terraria game servers to LLMs. It features:

• 24 game hooks — custom C# TShock plugin captures chat, boss kills, deaths, logins, and 20 more events
• 46 admin tools — give items, manage players, control weather, spawn NPCs, manage regions and permissions
• Two-phase agent — research (17 tools) → action (46 tools)
• Hard permission gate — keyword-based authorize_node blocks unauthorized tool calls
• MCP server — same 46 tools exposed to Claude Code for server administration
• Persistent memory — per-player conversation history via LangGraph’s AsyncSqliteSaver

The project is currently in active testing and not yet published on GitHub. We’re running it on a private Terraria server, iterating on the agent architecture before open-sourcing. If you’re interested in the code or want early access, reach out.

Built with: Python 3.14, LangGraph 1.x, DeepSeek (Anthropic-compatible API), C# .NET 9, TShock v6.1.0, aiohttp, httpx.

TL;DR — n8n and Dify often show up together in self-hosted AI evaluations, but they want to own very different layers of your stack. After evaluating both against a custom self-hosted AI setup, we adopted n8n and skipped Dify. The decision came down to one question — “what slice does this want to own, and do I already own that slice?” — and the answer was opposite for the two platforms. This post lays out the framework so you can run the same evaluation on your own stack.

Why This Comparison Matters in 2026

Six months ago the question “which OSS AI platform should I run?” had maybe three serious answers. Today there are dozens, and they overlap aggressively. Dify and n8n keep showing up together in evaluation lists, partly because they’re both written in TypeScript, both self-hostable via Docker, both have visual editors, and both can talk to LLMs.

That surface similarity is misleading. They want to own entirely different layers of your stack. Treating them as alternatives is a category error that will cost you a week of deployment work and rework.

What we concluded after evaluating both against an existing self-hosted setup:

• Dify wants to be the orchestrator. If you already have one, Dify has nothing to offer.
• n8n wants to be the execution layer. If you don’t have one, n8n is one of the best off-the-shelf options available.

What Dify Is

Dify is an open-source LLM application development platform (Apache 2.0, 55k+ stars on GitHub). The pitch:

• Visual workflow editor — drag nodes to build AI pipelines
• Built-in RAG — upload docs, get a queryable knowledge base
• Agent builder — pre-packaged prompt templates with tool calling
• Model gateway — abstract over OpenAI / Anthropic / DeepSeek / local
• Observability dashboard — request logs, latency, cost

In 2025–2026, Dify replaced its underlying LangChain with a custom “Beehive Runtime,” which is impressive engineering. The product is genuinely well-built.

The target user: someone who wants to ship an AI app without writing code or maintaining infrastructure pieces individually.

Same family: Flowise, Langflow, FastGPT. These are all “platform-first” AI builders.

What n8n Is

n8n is open-source workflow automation (162k+ stars). Think Zapier, but self-hosted and with code escape hatches.

• 400+ SaaS connectors — Notion, Slack, Stripe, Telegram, GitHub, you name it
• Trigger → action → condition visual workflow editor
• Webhooks — receive external events, route to actions
• Polling triggers — RSS feeds, scheduled jobs, file watches
• Native retry/error handling — every node has retry policies

n8n is not trying to be an LLM platform. It has nodes that call LLMs, but its core identity is “connect arbitrary SaaS systems and react to events.”

This distinction is crucial. n8n is plumbing-first, with optional AI nodes. Dify is AI-first, with everything else folded in.

The Triage Question: Replace or Absorb?

When you evaluate any platform against an existing stack, the question is not “is it good?” The question is “what layer of my stack does this want to own, and do I already own that layer?”

There are exactly two outcomes:

• Replace: the platform wants to own a layer you already have. Adopting it means ripping out working code and replacing it with a less flexible black-box equivalent.
• Absorb: the platform wants to own a layer you don’t have yet. Adopting it fills a gap without competing with anything.

This frame turns what could have been a fuzzy multi-day debate into clean, fast decisions. The rest of this post applies it to each platform in turn.

Dify’s Footprint Across Your Stack

Dify wants to own five layers at once. Here’s how each maps against a setup that already has a code-based orchestrator (any agent harness — Claude Code, LangGraph, your own):

The deeper realization: Dify is built for people who don’t write code but want to ship an AI app. That’s a legitimate market, and Dify serves it well. But if you already have a code-based orchestrator running, adopting Dify means ripping out working pieces and replacing them with less flexible equivalents just to fit inside a visual UI. Net cost: a week of migration, all flexibility lost, zero new capability gained.

Our verdict: skip. Not because Dify is bad, but because there was no gap left for it to fill.

n8n’s Footprint Across Your Stack

n8n’s pitch is structurally different. It doesn’t want to be the brain. It wants to be the wiring.

The four core capabilities n8n offers, mapped against a typical custom AI setup:

The critical observation: none of these compete with what an existing orchestrator typically owns. They sit underneath. They fill gaps that a code-based orchestrator alone would still have:

• Event-driven entry points (most custom stacks only have cron)
• Pre-built SaaS adapters (most custom stacks have no generic adapter layer)
• Off-the-shelf retry semantics (most custom stacks have handwritten error handling)
• Public RSS polling for protocol-locked services like YouTube (most custom stacks have nothing)

Our verdict: absorb. n8n becomes a dependency — a well-maintained, well-documented, battle-tested execution layer — without competing with anything that already works.

The Architecture Pattern That Emerges

The mental model after these two decisions:

                       Orchestrator (decisions, judgment)
                       ─────────────────────────────────
                                   │
            ┌──────────────────────┼──────────────────────┐
            │                      │                      │
            ▼                      ▼                      ▼
       Knowledge layer        Tool interfaces        Time triggers
       (your RAG)              (your APIs /            (cron)
                                MCP servers)
                                   │
                                   ▼
                       ┌────────────────────────┐
                       │  n8n (execution layer) │
                       │  ───────────────────── │
                       │  • webhooks            │
                       │  • SaaS adapters       │
                       │  • RSS / polling       │
                       │  • retry / state       │
                       └────────────────────────┘

The hard rule worth setting yourself: n8n is execution only, never decision. No AI reasoning inside an n8n workflow. n8n receives signals, dispatches them, retries on failure, and reports back. All judgment stays in the orchestrator’s hands.

Why is this rule necessary? Because n8n has LLM nodes. You could put a “summarize this email” GPT call inside a workflow. The moment you do, you’ve split your reasoning across two places — some inside your orchestrator’s prompt context, some inside an opaque n8n node — and now you have two systems making decisions with no shared memory. That’s the failure mode that turns simple workflows into unmaintainable chains.

Keeping n8n as pure plumbing is the discipline that makes the architecture work.

Three Gotchas Worth Knowing Before You Deploy n8n

Three things that tend to surprise people in the first day of running n8n:

1. The REST API doesn’t support PATCH for archiving workflows. You can create and read workflows via the API, but you can’t delete or archive them programmatically. Cleanup has to go through the web UI. If you’re planning to dynamically generate workflows, factor in manual cleanup or write directly to the SQLite database. (Fixed in n8n 2.22+; the 2.21.x line still has this limitation.)

2. Webhook paths are globally unique, even for inactive workflows. Delete a workflow but the webhook path stays registered, blocking reuse in any new workflow. Treat the webhook namespace as a flat global you have to manage. Prefix paths with the workflow name from day one.

3. The API key scope doesn’t include workflow:execute. You can read workflows over the API but you can’t trigger them programmatically — webhooks are the only execution surface. For most architectures this is actually correct (webhooks ARE the integration point), but it can catch you off guard if you’re expecting “API to start a workflow run on demand.”

When You Should Choose Dify

To be fair: Dify is the right tool when:

• You don’t want to write code or maintain individual infrastructure pieces.
• You need a polished UI for non-technical users to build and tweak workflows.
• You want a one-stop hosted experience (RAG + model gateway + observability + UI) and don’t already have these pieces wired together.
• You’re building a customer-facing chatbot for a small team and need shipping speed over architectural flexibility.

If any of those describe you, Dify is a serious choice and we wouldn’t argue against it.

When You Should Choose n8n

n8n is the right tool when:

• You need to integrate with specific SaaS products (Notion, Slack, Stripe, Telegram, etc.) and don’t want to write each API client by hand.
• You want event-driven workflows (webhooks, polling, scheduling) without building your own event bus.
• You want a visual editor so non-technical teammates can see and modify pipelines.
• You’re OK with workflows being execution-only — no judgment, just plumbing.

n8n is not a good choice when:

• You need multi-step LLM reasoning with shared memory across steps. Use an agent harness instead (Claude Code, LangGraph, OpenAI’s Agents SDK).
• You need full control over prompt format, token budget, fallback chains. n8n’s LLM nodes are too abstract for serious work.
• Your workflow logic changes weekly. The visual editor is great for stable workflows; it’s a drag for rapidly iterating ones — code is faster to refactor than nodes.

The Deeper Principle: “Models Are Commodity, Orchestration Is the Moat”

The Dify-skip / n8n-absorb decision is downstream of a broader principle:

• Models (DeepSeek, GPT, Claude, Mistral, Llama) are interchangeable. Swap them with an env var.
• Platforms (Dify, LangFlow, Flowise) are also interchangeable. They package similar capabilities differently.
• Orchestration — the system that connects models, knowledge, tools, and outcomes — is where the leverage is.

When you already have a strong orchestrator, you do not need a platform that wants to be your orchestrator. You need plumbing that does plumbing well. That’s where n8n earns its place.

This principle generalizes. Every time you evaluate an AI platform, ask: does this want to own my orchestration layer, or fill a gap underneath it? If the answer is “own,” and you already have an orchestrator, skip it. If the answer is “fill a gap,” and the gap is real, absorb it.

Closing Thought

Two platforms. Opposite decisions. Same underlying logic: what slice does this want to own, and do I already own that slice?

• Dify wanted to own the orchestration layer → already covered → reject.
• n8n wanted to own the execution layer (event triggers, SaaS integration, retry, polling) → not covered → absorb.

If you’re evaluating self-hosted AI tools right now, this is the question to ask first. It saves a lot of pointless deployments and even more pointless rework.

References

• Dify on GitHub — 55k+ stars, Apache 2.0
• n8n on GitHub — 162k+ stars, Sustainable Use License
• Model Context Protocol (MCP) specification
• Our previous post: RAG vs Agents

MyBrew is a curated site for AI tools and open-source projects. Every recommendation is actually tested before it appears here.

What You’ll Find

• Tool Reviews — hands-on testing, no fluff. Does it work? Is it worth your time?
• Open-Source Deep Dives — GitHub projects that deserve attention, explained in plain English.
• Tutorials — step-by-step guides to build useful things with AI.
• Comparisons — “X vs Y for Z” — side-by-side breakdowns for real use cases.
• Roundups — thematic collections when you need options at a glance.

Philosophy

The internet doesn’t need another AI news aggregator. We brew, not spray — each post is tested, filtered, and written for humans.

Who Writes This

I hold an MSc in Computer Science from The University of Hong Kong (HKU). Current research: LLM backdoor attacks and agent harness design.

A note on how this site is made: articles here are drafted and polished with AI assistance. Writing about AI without using AI would miss the point — AI is a serious force multiplier on quality and pace. But AI stays a tool, not the editor: every claim, framing, and final call is mine. The site itself is AI-friendly by design — partly because that’s how the web is increasingly read, mostly because it’s the same principle: use the tools.

More time spent breaking things than writing about them — what makes it here is what survived.

Reach me at contact@aibrew.ai — I read everything, reply when I can.

This is the first post. More coming soon.

• Tool Reviews — hands-on testing
• Tutorials — step-by-step AI guides
• Comparisons — side-by-side breakdowns
• Roundups — curated collections

Everything tested. No hype.

TL;DR — Huawei’s τ (Tao) Scaling Law, announced at IEEE ISCAS 2026, reframes Moore’s Law: instead of shrinking transistors, optimize a time constant τ across the entire computing stack. The paper is real, the production data is concrete, but the “first scaling law since Dennard” claim deserves scrutiny. This is mostly a solid 3D-integration engineering paper wrapped in a strategic narrative about how China builds high-performance chips without leading-edge lithography.

What Was Announced

On May 25, 2026, at the IEEE International Symposium on Circuits and Systems (ISCAS) in Shanghai, He Tingbo — President of Huawei’s Semiconductor Business — delivered a keynote titled “Exploration and Practice of a New Semiconductor Path.” The headline: a new scaling principle Huawei calls τ (Tao) Scaling, marketed as China’s first systematic semiconductor industry law.

The paper, “A Time Scaling Theory for Multi-Layer Electronic Systems,” was simultaneously posted to ChinaXiv as a preprint (ChinaXiv:202605.00224). Within hours it had over 30,000 reads and 13,000 downloads — unusual for a preprint server.

This is worth taking seriously precisely because it’s published, not a marketing deck.

The Core Reframe

For 60 years, Moore’s Law has driven semiconductor progress by shrinking transistor dimensions. The paper opens with the industry consensus:

“For six decades, Moore’s geometric scaling drove progress in semiconductors… returns from pure dimensional shrinking have flattened, leading-edge design budgets exceed one billion dollars per chip, and cost-per-transistor at the most advanced nodes is no longer falling.”

So what’s the successor principle? The paper’s pivot is the key insight:

“Spatial scaling served merely as the instrument for compressing time.”

In other words: Moore’s Law was never really about transistor area — it was about reducing the time it takes for a system to do something. Users don’t care that their chip is 3nm. They care that their app opens in 200ms instead of 300ms.

If time was always the underlying goal, why not measure progress in time directly? That’s τ scaling: a single characteristic time constant τ as the unifying optimization target across the entire computing stack — from picosecond transistor switching to multi-second AI workload latency, spanning twelve orders of magnitude.

The paper’s strongest methodological claim:

“τ scaling is the first scaling principle since Dennard to establish a shared optimization target across the entire computing stack.”

This is a big claim. We’ll revisit it.

How τ Works: Four Layers

The framework decomposes τ into four stack layers, each with its own optimization target:

The interesting move is that the paper treats frequency, latency, bandwidth, throughput as all being governed by τ at their respective layers. One framework, twelve orders of magnitude.

Production Demo #1: Kirin 2026 SoC

This is the most concrete part of the paper. The Kirin 2026 chip — launching this autumn — is the first commercial product using LogicFolding.

What LogicFolding Actually Does

“LogicFolding is a design methodology that partitions digital, analog, and memory circuits across vertically stacked active tiers.”

In plain terms: instead of laying out logic in a single 2D plane, split the design across multiple active silicon layers connected by high-density hybrid bonding. Some signal paths that previously had to traverse long horizontal distances now travel short vertical ones.

The promise:

“Signal wires become substantially shorter, parasitic RC decreases sharply, clock skew tightens, and the chip operates at a higher clock frequency at the same device node.”

Crucially: at the same device node. This isn’t a process shrink. It’s a structural reorganization that recovers performance from the interconnect, not the transistor.

The Numbers (from the paper)

Measured on Kirin 2026:

If these hold up under independent measurement, this is a genuine engineering achievement — not just a process node bump.

Production Demo #2: AI Data Centers

The harder test for any scaling principle: does it work at gigawatt scale?

“Whether a principle developed in the milliwatt smartphone regime survives translation to the gigawatt regime of AI training and inference.”

The paper’s answer: yes, but only if you treat τ as a system-level target, not a per-accelerator optimization.

The Bottleneck Reframe

The paper’s most important industry observation:

“Modern AI systems are dominated by data, not by compute. Over 80% of energy in large AI clusters is spent on data movement, and over 70% of system cost goes to data storage.”

This is the unspoken truth of AI infrastructure: TOPS numbers on chip datasheets are mostly irrelevant when 80% of energy goes to moving bytes between chips, racks, and storage tiers.

Three Solutions

1. Unified Bus (灵衢总线) — A memory-semantic fabric eliminating protocol conversions between PCIe / NVLink / RDMA / Ethernet / InfiniBand layers. The claim:

“Conversion-free, peer-to-peer transmission.”

Measured impact: end-to-end remote access latency from tens of microseconds to ~100ns — a roughly 500× reduction in system τ on the main communication path.

2. Hi-ONE (High-density Optical-interconnect-Node Engine) — Near-package optical I/O. At multi-Tb/s per chip, copper becomes physically impractical:

“At multi-Tb/s per chip, copper becomes physically impractical.”

Hi-ONE delivers 8 Tb/s per module, extends face-to-face distance to 100m, and matches the chip’s UB bandwidth over a single optical link.

3. 3D Folding — The fan-out dilemma: compute scales with chip area (N²), but I/O and power scale with chip perimeter (N). Solution: fold I/O and power into vertical stack instead of crowding the edge.

Projection: more than 100× growth in hardware integration by 2035.

The Honest Caveat

Buried in the paper is one of the most important sentences for understanding what τ scaling is not:

“τ is a time law, not a joule law.”

Translation: τ scaling solves time, not energy. If you make an AI cluster 10× faster but it also draws 10× more power, you’ve just moved the bottleneck from latency to electricity, cooling, and dollars.

The paper acknowledges this and gestures at the obvious complements: protocol overhead reduction, lower per-bit transmission energy, near-memory computing, backside power delivery, dynamic voltage/frequency scaling. But the framework itself doesn’t solve energy. Anyone evaluating τ scaling should remember this.

It’s worth noting that He Tingbo explicitly acknowledges this in the paper — unlike most marketing-driven “new law” announcements, which tend to gloss over their boundaries.

Earned Credit vs. Marketing

What stands up

• Real paper, real data. ISCAS keynote + ChinaXiv preprint with concrete production numbers. Not a slide deck.
• Honest about limits. The “τ is not a joule law” caveat shows genuine engineering humility.
• Strategically sound. Without access to leading-edge EUV lithography, China needs a path to high-performance chips that doesn’t depend on 2nm or 1nm process nodes. 3D integration plus system-level optimization is that path. The framework gives it a name and a measurable target.
• Kirin 2026 ships this autumn. Verifiable claims have a verification date.

What deserves scrutiny

“First scaling principle since Dennard” is a load-bearing claim. But:

• 3D integration has been studied for years. TSMC’s CoWoS, Intel’s Foveros, AMD’s chiplet packaging, Samsung’s X-Cube — these are all forms of vertical integration.
• HBM is essentially a 3D-folded memory stack.
• Imec’s CFET research aims at gate-level 3D folding.

The paper differentiates LogicFolding from existing 3D IC and chiplets by arguing they operate at the packaging layer, while LogicFolding operates at the circuit topology layer inside the chip. That’s a legitimate distinction — but it’s an incremental one, not a paradigm break.

“1.4nm equivalent density by 2031” is a density target, not a process node. The paper is careful about this — but the surrounding press has not been. Equivalent density via 3D stacking is real; it is not the same as fabricating a true 1.4nm node, and shouldn’t be conflated.

“381 chips in 6 years using τ scaling” is post-hoc framing. Huawei has been shipping chips for years; retroactively grouping them under a unified principle is good narrative but doesn’t validate the principle as predictive.

No public benchmarks against the competition. TSMC N2, Intel 18A, Samsung 3GAP — where do they sit on this τ chart? The paper doesn’t say. Until independent measurement compares apples to apples, the “100× by 2035” projection is a roadmap, not a result.

Why This Matters Strategically

Strip the “scaling law” framing and what’s left is a coherent industry argument:

“You don’t need the most advanced lithography to build competitive high-performance chips, if you reorganize circuits in 3D and treat the entire system as a single optimization target.”

This is the technical case for a China-led semiconductor strategy that doesn’t depend on access to ASML’s EUV machines. It’s also a vision for how AI infrastructure could be built differently — interconnect-centric, system-co-designed, optical at the edges rather than copper everywhere.

Whether or not τ scaling becomes “the next Moore’s Law,” it’s a real-world demonstration that the post-Moore era has multiple paths. The question is which path delivers on its claims.

What to Watch

• Kirin 2026 launch (Autumn 2026): Are the 41% efficiency and 55% density gains independently measurable?
• ISCAS 2026 paper full text: Independent review of LogicFolding’s claimed RC reductions vs alternative explanations.
• Industry response: Do TSMC, Intel, Samsung adopt τ-style framing? Or counter with their own “scaling principle” branding?
• Energy data: Since τ doesn’t solve energy, what’s the actual J/op for AI workloads on Huawei’s Ascend silicon vs NVIDIA’s latest?
• Beyond Kirin: Does LogicFolding land in Ascend AI chips next? The paper claims AI-system applicability but the production demo is mobile SoC.

Bottom Line

The τ Scaling paper is a solid engineering paper with an oversized strategic narrative wrapped around it. The technical core — LogicFolding, Unified Bus, Hi-ONE, 3D Folding — is real work with measurable claims. The framing as “the next Moore’s Law” oversells what is, methodologically, an incremental extension of well-known 3D integration techniques combined with system-level co-design.

That’s not a criticism. Most real engineering progress is incremental. The marketing layer is what funds the engineering. What matters is whether the Kirin 2026 ships this autumn with the numbers the paper claims. If it does, China just published a credible technical roadmap for high-performance chips that doesn’t depend on access to leading-edge lithography. That’s a much bigger deal than “the next Moore’s Law.”

References

• Tingbo He — A Time Scaling Theory for Multi-Layer Electronic Systems (ChinaXiv preprint)
• Huawei official announcement — ISCAS 2026 τ scaling
• EEFocus — Deep read of He Tingbo’s “Time Scaling” paper
• Gizmochina — Huawei proposes Tao Law as alternative to Moore’s Law
• 21 Economic Net — What is the Tao Law and how is it different from Moore’s Law

TL;DR — RAG answers from documents. Agents take actions. Most real systems use both: RAG provides context, agents act on it. The hard part isn’t picking one — it’s knowing which layer of your problem belongs to which pattern.

Why This Comparison Matters Right Now

Two things happened in the last six months that make this comparison less academic than it used to be.

First: coding agents crossed a quality threshold around November 2025. Simon Willison’s five-minute PyCon talk describes it as the moment agents went from “often-work” to “mostly-work” — usable as daily drivers, not just demos. The “best model” title changed hands five times between Anthropic, OpenAI, and Google in a single month.

Second: the model labs themselves are pivoting. Greg Brockman: “the model alone is no longer the product.” AI21 shuttered its model team to focus on agents. DeepSeek spun up its first “Harness team.” Latent Space called this “all model labs are now agent labs.”

When the people who train the models start saying the model isn’t the product, the question of how you wire models into systems becomes the actual engineering work. RAG and agents are the two dominant answers. They solve different problems, and getting the choice wrong wastes a lot of tokens.

The Mental Model

RAG: Retrieve, then Generate

RAG is a fixed four-step pipeline:

User query
   │
   ▼
Embedding model → vector
   │
   ▼
Vector DB / search index → top-K relevant chunks
   │
   ▼
Chunks injected into the LLM prompt as context
   │
   ▼
LLM writes one answer, grounded in the retrieved text

One retrieval. One generation. Cheap, deterministic, easy to debug.

Agent: Reason, then Act, then Reason Again

Agent is a reasoning loop:

User goal
   │
   ▼
┌──────────────────────────────────────────┐
│   LLM reads the goal                      │
│   ↓                                       │
│   Picks a tool (Read, Edit, Bash, ...)    │
│   ↓                                       │
│   Runtime executes the tool               │
│   ↓                                       │
│   Result feeds back to the LLM            │
│   ↓                                       │
│   LLM reasons about what to do next       │
│   ↓                                       │
│   Picks the next tool                     │
│   ↓                                       │
│   ...loop until task is done              │
└──────────────────────────────────────────┘

Every iteration burns tokens. Every step can fail. Errors compound across the loop.

A Concrete Example of Each

RAG in Action: Semantic Wiki Search

We run a personal knowledge base — about 60 markdown files covering project notes, design decisions, and conversation transcripts. Plain grep doesn’t cut it because the question and the answer rarely share keywords.

The solution is an MCP server that wraps a vector search:

MCP server: wiki-search
  Backend: bge-m3 embedding model
  Storage: cosine similarity index over 60+ markdown files
  Input:   natural-language query (English or Chinese)
  Output:  file path + section title + similarity score

When I ask Claude Code “what did we decide about the auto-pipeline last month?”, this happens:

1. Claude Code recognizes it needs to search the wiki and invokes search_wiki("auto-pipeline decision")
2. The query gets embedded into a 1024-dim vector
3. Cosine similarity returns the top 5 matching sections
4. The matching chunks get injected into Claude’s context
5. Claude answers, grounded in the actual files — no hallucination

This is RAG end-to-end. The wiki is passive. It gets queried; it doesn’t act.

Agent in Action: Claude Code Editing Files

Same Claude Code instance. Different problem: “Update the baseURL in mybrew/hugo.yaml to aibrew.ai and add a note in TODO.md.”

Iteration 1:
  LLM reasoning: "I need to see the current config first."
  Tool: Read("mybrew/hugo.yaml")
  Result: file contents shown

Iteration 2:
  LLM reasoning: "baseURL is on line 1. I'll edit it."
  Tool: Edit(old="https://mybrew.cc/", new="https://aibrew.ai/")
  Result: edit succeeded

Iteration 3:
  LLM reasoning: "Now update TODO.md to mark this done."
  Tool: Read("hugo/TODO.md")
  Result: file contents shown

Iteration 4:
  LLM reasoning: "Need to add the entry under 'Domain config'."
  Tool: Edit(...)
  Result: edit succeeded

Task complete.

Four iterations. Four tool calls. Multiple reasoning steps. The agent decided what to do, how to do it, and when it was done — all on its own.

A Higher-Stakes Agent: Game Server Control

We also run an agent that controls a Terraria game server through MCP — the bridge exposes ~40 tools (give items, teleport, ban players, spawn bosses, restart server).

Player in chat: "@ai give me a Zenith"
  → terra_item_lookup("Zenith") → resolves to ID 4956
  → terra_give_item(player="kali", item="Zenith") → SUCCESS
  → Item appears in player's inventory

Compare to a destructive operation:

Player: "@ai end the world"
  → terra_world_hardmode(confirm=true) requires explicit authorization
  → Refuses without confirmation
  → If confirmed: world permanently enters hardmode (irreversible)

This is where the agent pattern gets dangerous. The LLM is now in the driver’s seat of a real system. The blast radius of a wrong tool call is no longer “wrong answer” — it’s “wrecked world.” Permission boundaries become first-class design.

The Decision Framework

The one-line rule:

Use RAG when the answer lives in your documents. Use an agent when the answer requires action.

Here’s the longer version:

When You Definitely Want RAG

• “What does our internal API documentation say about rate limits?”
• “Summarize last week’s customer feedback.”
• “What did the design discussion conclude about authentication?”

When You Definitely Want an Agent

• “Run the test suite and fix any failures.”
• “Pull yesterday’s unread RSS items, pick the three most interesting, and draft a roundup post.”
• “Refactor this directory to use the new logging API.”

When You Need Both (Most Real Systems)

• “Find the related design doc, then propose a code change consistent with it.” → RAG to retrieve the doc, agent to make the change.
• “Look up how Pinterest handled MCP auth, then design our auth layer.” → RAG to gather references, agent to write code.

Hybrid Patterns: RAG-Powered Agents

Here’s the thing most “RAG vs Agent” comparisons gloss over: inside any real agent, RAG is happening at multiple layers.

A Claude Code session, simplified:

Session start:
  └─ Load CLAUDE.md into context ............... RAG-on-startup
  └─ Load relevant MEMORY.md files ............. RAG-on-startup

User query:
  └─ Agent reasons about the goal
       │
       ├─ Tool call: search_wiki("...") ........ RAG-on-demand
       ├─ Tool call: searxng_web_search("...") . RAG-on-demand
       ├─ Tool call: Read("config.yaml") ....... Deterministic retrieval
       └─ Tool call: Edit(...) ................. Action

The agent loop is the outer shell. RAG calls happen inside the loop, on demand, whenever the agent decides it needs more grounding.

This matches what Pinterest engineers describe in their MCP rollout: the agent surfaces (chat, IDE, CLI) all talk to a common set of MCP servers, some of which are pure retrieval (Presto query, doc search) and some of which are actions (file a ticket, restart a job). The agent decides at runtime which to call.

Production Case Study: Pinterest’s MCP Ecosystem

ByteByteGo’s writeup of Pinterest’s MCP rollout is one of the few public production stories.

The N×M Problem

Pinterest engineers work across many systems daily — Presto for data, Spark for batch jobs, Airflow for workflows, internal docs, ticketing. They wanted AI agents that could reach into these systems directly.

The brute-force math:

5 agent surfaces × 10 internal tools = 50 bespoke integrations

Every new surface or new tool multiplied the work. Plus 50 auth flows, 50 token lifecycles, 50 sets of plumbing.

The MCP Bet

The Model Context Protocol promised to flatten this:

5 clients + 10 servers = 15 standardized integrations

One protocol, used in both directions. Build a client per surface. Wrap each tool in a server. They all speak the same language.

What MCP Doesn’t Solve

Pinterest’s hard-won lesson: the protocol is the easy part. The real engineering went into the surrounding infrastructure:

The takeaway: the more capable your agents become, the more your permission and observability layers matter. A protocol that lets any agent call any tool is also a protocol that lets any compromised agent call any tool.

This is also why our smaller setup (3 MCP servers: searxng, wiki-search, terra_llm_bridge) puts hard confirm=true gates on destructive operations like banning players, restarting the world, or enabling hardmode. Three servers don’t need a registry — but they do need authorization.

Architecture Comparison: Claude Code vs OpenClaw

Two of the most popular agent harnesses today take very different stances. ByteByteGo’s EP214 breaks them down on five dimensions:

1. System Scope

Claude Code is a workhorse you summon. OpenClaw is a butler that’s always listening.

2. Agent Runtime

• Claude Code: single async loop — Think → Tool Call → Observe → Repeat. One task at a time per process.
• OpenClaw: per-session queues. The Gateway demultiplexes incoming messages and dispatches them to separate runtime queues.

3. Extension Model

• Claude Code: Four extension primitives, all hooking into the same agent loop:
  • MCP (external tool servers)
  • Plugins (bundled tool sets)
  • Skills (named procedures the model can invoke)
  • Hooks (event-driven shell commands)
• OpenClaw: Manifest-first plugins. All plugins go through a central Registry before being made available to the Agent.

4. Memory

• Claude Code: CLAUDE.md loaded into context at session start. Subdirectories have their own CLAUDE.md that gets appended when you cd into them.
• OpenClaw: MEMORY.md separated from daily notes. Hybrid vector + keyword search across structured sections.

5. Multi-Agent Topology

• Claude Code: Lead → subagent pattern. Main agent delegates work to spawned subagents.
• OpenClaw: Route-and-delegate. Inbound channels route to dedicated agents that hand off to shared subagents.

The deeper pattern: Claude Code optimizes for “one session, one task.” OpenClaw optimizes for “many concurrent conversations, ambient presence.” Both are correct for their respective use cases. Don’t pick the wrong one for yours.

Failure Modes and Anti-Patterns

RAG Failure Modes

1. Retrieval misses the relevant chunk. Your embedding model thinks the question and the answer are semantically distant when they aren’t. Mitigation: hybrid search (vector + keyword), reranking, query expansion.

2. Retrieval returns too many irrelevant chunks. Context window fills with noise. Mitigation: stricter top-K, similarity threshold, post-retrieval filtering.

3. The answer isn’t actually in your corpus. RAG can’t fabricate truth — if the knowledge isn’t indexed, the model still doesn’t know. Mitigation: a confidence check, or a fallback to web search.

4. Chunking destroyed the structure. You split a markdown file mid-table, mid-code-block, mid-argument. Mitigation: structure-aware chunking (by heading, by paragraph, by semantic unit).

Agent Failure Modes

1. Reasoning drift. The agent gets stuck in a loop, repeatedly trying variations of the same failed approach. Mitigation: max-step limits, distinct-tool-call constraints, explicit “what have I tried” memory.

2. Permission overreach. The agent does too much. It was asked to fix one test, it refactored half the file. Mitigation: explicit scope in the prompt, narrow tool permissions, human-in-the-loop for destructive ops.

3. Tool-call cascade failure. A single bad tool call (e.g., a malformed path) gets followed by five reasoning steps trying to “fix” the symptom rather than the root cause. Mitigation: clear error messages from tools, “try once then escalate” tool design.

4. Spending money on the wrong thing. A 20-step agent loop costs 20× a single LLM call. If RAG would have answered the question, you just paid 20× to get a worse answer. Mitigation: ask “could this be a single retrieval?” before going to agent mode.

The Worst Anti-Pattern: Agent-When-RAG-Works

The single most expensive mistake teams make: building an agent for a problem that’s actually a search problem.

If your users are asking “where in the docs does it say…”, you don’t need an agent. You need a search box wired to a vector index. Stop spending tokens on multi-step reasoning to find something a single retrieval call would surface.

What This Means for Builders

A practical checklist if you’re starting a new AI feature:

1. Frame the problem as a verb. “Answer questions about X” → RAG. “Do X on behalf of the user” → agent.
2. If you can answer it with one retrieval, do. Cheaper, faster, more predictable.
3. If you go agent, design permissions on day one. Not day fifty. Pinterest’s two-layer auth wasn’t a feature — it was a survival requirement.
4. Plan for hybrid. Real agents will need RAG-style retrieval inside their loop. Pick a protocol (MCP is the obvious default) and stick to it.
5. Instrument everything. Tool call counts, retrieval hit rates, drift indicators. You can’t tune what you can’t see.
6. Set a budget per task. Both in tokens and in iterations. Agents without budgets find creative ways to spend forever on the wrong thing.

Closing Thought

The RAG-versus-agent framing made sense in 2023, when these were two distinct paradigms competing for the same job. In 2026, they’re complementary layers of the same system.

The interesting question isn’t which one to use. It’s which slice of your problem belongs in which layer. Get that division right and you ship something useful. Get it wrong and you’ll spend a quarter rebuilding it.

For most teams shipping today, the answer looks like this:

                ┌───────────────────────────────┐
                │      Agent loop (outer)        │
                │   reasoning + tool selection   │
                └──────────┬────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
   RAG retrieval     Action tools       Computation
   (knowledge)       (mutate state)     (math, code)

Agent decides. RAG informs. Tools act. That’s the whole stack.

References

• ByteByteGo EP216 — RAGs vs Agents
• ByteByteGo — How Pinterest Built a Production MCP Ecosystem
• ByteByteGo EP214 — Claude Code vs. OpenClaw: 5 Design Dimensions
• Simon Willison — The Last Six Months in LLMs in Five Minutes
• Latent.Space — All Model Labs Are Now Agent Labs