TL;DR — AI-Native Workspace is an open-source framework for running a real research or engineering workspace with AI coding agents. Its core idea is simple: separate the Model, Agent, Protocol, and Application layers so you can swap Claude, DeepSeek, Codex, Cursor, MCP servers, project docs, and knowledge workflows without rewriting everything.

Most AI coding workflows start as a pile of useful fragments: a CLAUDE.md, a few prompts, some shell scripts, maybe a .cursorrules file, and a note that says “remember to update the TODO.” That works for one project. It starts breaking when the workspace grows to five projects, three model providers, a wiki, an inbox, a handful of local services, and months of accumulated decisions.

AI-Native Workspace is our attempt to turn that mess into an architecture.

The project is not another dotfiles dump. It is a layered framework for treating the workspace itself as the operating system: the model provides reasoning, the agent acts like a process, protocols are the system calls, and the application layer is where real work lives.

That metaphor sounds abstract, but it solves a very practical problem: how do you keep an AI-operated workspace portable when models, agents, and tools change every few months?

The Problem: Most Agent Workflows Are Too Coupled

A lot of current “AI workflow” setups are tightly bound to one ecosystem:

• one model provider,
• one coding agent,
• one config format,
• one project layout,
• one set of tool integrations.

That gives you a fast start, but the cost shows up later. If the model becomes expensive, you rewrite your scripts. If your agent changes its config format, you rewrite your rules. If you add a second project, your root instructions become a dumping ground. If chat history disappears, the agent loses the reasons behind past decisions.

AI-Native Workspace starts from the opposite assumption:

The workspace should outlive any single model, agent, provider, or tool.

So the framework separates the system into four layers.

The Four-Layer Architecture

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

┌─────────────────────────────────────────────────────────┐
│  Application                                            │
│  Projects · Inbox · Wiki · workflows                    │
├─────────────────────────────────────────────────────────┤
│  Protocol                                               │
│  CLAUDE.md conventions · CLI tools · MCP servers        │
├─────────────────────────────────────────────────────────┤
│  Agent                                                  │
│  Claude Code · Codex · Cursor · markdown-aware agents   │
├─────────────────────────────────────────────────────────┤
│  Model                                                  │
│  DeepSeek · Claude · Qwen · OpenAI · local models       │
└─────────────────────────────────────────────────────────┘

Each layer has one responsibility. More importantly, each layer can change without forcing the others to change.

Layer 1: Model

The model layer is the LLM that provides reasoning capability: Claude, DeepSeek, Qwen, OpenAI, Gemini, a local model through Ollama or vLLM, or a third-party relay.

AI-Native Workspace treats the model as the most disposable layer. That is intentional. Model quality and pricing change constantly. A workflow that only works with one provider is fragile.

In practice, the framework favors provider swaps through environment configuration. You might use a cheap daily model for routine editing and a stronger model for deeper architecture work. The workspace does not need to know which one is currently running.

Layer 2: Agent

The agent layer is the software that reads instructions, reasons about the task, and calls tools. Today that might be Claude Code. Tomorrow it might be Codex CLI, Cursor, Aider, Continue, or a custom LangGraph agent.

The key design decision is that the workspace instructions are written in plain markdown. The file may be called CLAUDE.md, but the contents are not inherently Claude-only. Any agent that can read markdown can understand the conventions.

That means CLAUDE.md becomes an agent runtime config, not just a README. It tells the agent what projects exist, where state lives, how to end a session, how to resume work, and which docs are authoritative.

Layer 3: Protocol

The protocol layer defines how the agent interacts with the world.

There are three levels:

1. File protocol — markdown conventions such as CLAUDE.md, inbox/TODO.md, and wiki/MANIFEST.md.
2. CLI tools — git, curl, docker, Python, Node, Hugo, or any local command-line tool.
3. MCP servers — optional integrations for search, databases, APIs, game servers, internal tools, and more.

The important part is that MCP is not required. The lowest common denominator is a readable file. A markdown-aware agent can still operate the workspace even if no MCP server is available.

This is one of the most useful constraints in the project: file protocol is the floor; MCP is the ceiling.

Layer 4: Application

The application layer is the actual workspace: projects, inbox, wiki, work logs, and accumulated knowledge.

A minimal workspace looks like this:

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

workspace/
├── CLAUDE.md              # workspace-level cognitive config
├── inbox/                 # low-friction capture buffer
│   ├── README.md
│   └── TODO.md
├── projects/              # concrete work
│   ├── project-a/
│   │   └── CLAUDE.md
│   └── project-b/
│       └── CLAUDE.md
└── wiki/                  # matured knowledge base
    └── MANIFEST.md        # progressive-loading index

This layer is where AI-Native Workspace becomes more than an agent config template. It defines a practical knowledge lifecycle.

Highlight 1: Inbox First, Wiki Later

The most valuable idea in the project may be the simplest one: do not force every note to become structured knowledge immediately.

The inbox/ folder is a draft buffer. Session summaries, temporary notes, half-formed ideas, TODOs, and meeting scraps can all land there. They do not need perfect taxonomy on day one.

Only when something becomes repeatedly useful does it graduate to the wiki/.

That is a better fit for real AI-agent work than trying to maintain a pristine knowledge base at all times. Agents generate lots of intermediate state. Humans also forget details between sessions. The inbox gives both sides a cheap place to put context before deciding what deserves permanence.

Highlight 2: Progressive Context Loading

AI agents fail when they load too much irrelevant context. A workspace with hundreds of notes cannot be stuffed into every prompt.

AI-Native Workspace uses wiki/MANIFEST.md as a lightweight index. The agent reads the manifest first, sees one-line summaries, and then loads only the relevant files.

This is the same idea as a database index:

• scan the cheap index,
• choose a few relevant entries,
• fetch details only when needed.

The result is a workspace that scales without turning every session into a context dump.

Highlight 3: Layered CLAUDE.md Files

The framework uses CLAUDE.md at multiple levels:

1
2
3

~/.claude/CLAUDE.md              # global preferences
<workspace>/CLAUDE.md            # workspace map and shared workflows
<workspace>/<project>/CLAUDE.md  # project-specific instructions

This prevents the root file from becoming a 500-line junk drawer.

The root CLAUDE.md should be a router: what exists, where to look, and what rules apply across the whole workspace. Project-level details stay inside each project. Stable knowledge moves into project docs or the wiki. Temporary state stays in the inbox.

That separation is boring in the best possible way. It makes the workspace readable after months of use.

Highlight 4: Human-Readable, Agent-Optimized

AI-Native Workspace is designed for agents, but it does not hide the system from humans.

That matters because humans are the fallback operator. APIs fail. Models regress. Tools break. Sometimes the agent simply gets confused. When that happens, a human should be able to read the same files and continue the work.

This is why the framework avoids magic as much as possible. Plain markdown, plain folders, plain CLI tools, explicit protocols.

Highlight 5: Anti-Patterns as First-Class Design

The repo is unusually explicit about what not to do. A few examples:

This is a sign that the project came from real use rather than a clean-room diagram. The anti-patterns are scars from operating a multi-project AI workspace every day.

Who Should Use It?

AI-Native Workspace is useful if:

• you work with AI coding agents daily,
• you run multiple projects in parallel,
• you care about cross-session continuity,
• you want to switch between model providers without rebuilding your workflow,
• your work accumulates knowledge over months.

It is probably overkill if you only have one short-lived project. In that case, a simple CLAUDE.md may be enough.

The Bootstrap File Is the Product

One interesting detail: the repo includes BOOTSTRAP.md, a document written for AI agents rather than humans.

The intended workflow is simple:

1. Create an empty workspace directory.
2. Open Claude Code, Codex, Cursor, or another agent.
3. Paste BOOTSTRAP.md as the first prompt.
4. Let the agent create the initial structure.

That makes the project self-instantiating: the framework explains itself to the agent that will build it.

Final Thoughts

AI-Native Workspace is not trying to be a heavyweight platform. Its bet is almost the opposite: the durable layer of an AI-native workflow should be simple files, explicit conventions, and clear boundaries.

Models will change. Agents will change. MCP servers will come and go. But a well-structured workspace can survive those changes.

That is the core insight:

Do not build your workflow around a model. Build it around a workspace architecture that can swap models.

For anyone trying to turn an AI coding agent into a long-running research or engineering partner, that distinction matters.

Project link: RedDragonHQ/ai-native-workspace

If you have any questions, concerns, or want to understand how this works in a real workspace, feel free to contact us at contact@aibrew.ai.

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.