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