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:

Avoid Prefer
Start with multi-agent orchestration Use one agent; split only when context truly requires it
Load every workspace file at boot Read an index first, then drill down
Write directly to wiki for everything Capture in inbox first, let knowledge sediment
Make root CLAUDE.md huge Keep root as a router; push details down
Treat TODO.md as an unquestioned command queue Validate stale TODOs before acting
Require MCP for core workflow Make files the core protocol; add MCP on demand

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 [email protected].