Why file-system agents beat sandboxed ones for real codebases

The core divide: sandboxed agents vs file accessCopy Anchor Link

There are two kinds of code AI agents: those that run inside a safe, limited sandbox with no real file I/O, and those that can inspect and rewrite your actual file tree.

A sandboxed agent sees whatever is sent in context — a pasted file, a prompt, maybe a synthetic tree view. All of its writes are simulated, staged as patches, or rendered in markdown. Nothing hits disk.

A file-system agent is given a path to your repo. It reads, rewrites, creates, and deletes real files in your checkout. Claude Code is the archetype here: Anthropic describes it as an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Cursor follows the same pattern — a coding agent that understands and builds inside your codebase rather than beside it.

The difference is decisive at three tasks: surveying code across dozens of files, making schema-aware changes that keep several files in sync, and wiring new features into the real app — imports, tests, build configs, routes. If you want a coding agent that goes beyond toy changes, it needs to touch the real tree.

The Model Context Protocol documentation frames the underlying idea well: MCP is an open standard for connecting AI applications to external systems, including local files. The sandbox question is really an access question — what systems the agent is allowed to touch.

Why so many tools default to sandboxed agentsCopy Anchor Link

Plenty of AI dev tools stop at the sandbox boundary. They operate on snippets or files in isolation — or, at best, on synthetic views of the codebase built from indexers and partial snapshots.

The practical reasons are real: safety (arbitrary file writes risk anything from a wiped source tree to injected malicious code), speed (whole-tree analysis on big repos gets expensive), and easier infrastructure (a browser-based agent often has no disk access by design, so patches travel as data blobs).

But the tradeoff is fatal for real software automation. A sandboxed agent can write impressive-looking code, but it cannot verify that code against the repo, cannot wire changes end to end, and cannot run the post-change build or test. In practice, every AI-generated patch becomes a stack of follow-up tasks for a human to debug and wire.

The pain of synthetic context: where sandboxed agents hit a wallCopy Anchor Link

Take a concrete example: extending a payments integration in a SaaS project, with code spread across a billing component, an API route, a client library, environment examples, and docs. A sandboxed agent sees whichever files you feed it. Paste only the component and it has no idea about the API route or the env files.

You can glue things together by hand: find every touched file, copy them into the agent in order, ask for a multi-file patch. But that is friction, not flow — the human becomes the context builder and patch applier, and the agent's changes come back inconsistent in imports, names, and types. This is why complex upgrades and refactors stall in snippet-bound tools.

A real agent needs real code, and the ability to change it.

Our default: ship the codebase, not the facadeCopy Anchor Link

OTF's position — stated as our philosophy, not an industry fact — is that an AI-native template must arrive as a full repo: live file tree, buildable, production-wired. Nothing gated behind a cloud UI, nothing that requires a cloud-side agent to interpret the code.

That format means your agent gets access to the real artifact: the repo as it would exist in production. No hallucinated paths, no mystery structure, no glue code required. This is the same principle behind our agent-readable repository structure work — the repo layout itself is part of the agent interface.

It also connects to cursor rules for Next.js: conventions encoded in the repo travel with the files, so any file-system agent that opens the tree inherits the project's idioms automatically. And for teams running agents against production-shaped code, our AI app security checklist covers the guardrails that file-system access demands.

Why in-tree AI config is the enablerCopy Anchor Link

You have seen README.md. The stronger pattern is threading agent-oriented config through the repo itself: a CLAUDE.md spelling out design intent and extension patterns, .cursorrules encoding coding conventions and file patterns, and prompts mapped to the file-tree structure.

What this buys: a clear task file describing what exists and where new work goes, guardrails telling the agent the shape of the repo and what it may touch, and extension guidance grounded in first principles baked into the kit rather than guessed from a chat window.

An illustrative sketch of the pattern:

# CLAUDE.md (illustrative sketch, not a real file)

## Adding a new payment provider

1. Implement the provider adapter alongside existing providers.
2. Update the billing component switch.
3. Document the new environment variable.
4. Run migrations after saving.
5. Update dependent list views.

wired for file-system access, instructions like these land as context in every generation turn. Less guessing, fewer half-wired features. Our cursor prompts for agent sessions guide goes deeper on shaping those turns.

The workflow: an agent that extends for realCopy Anchor Link

Make it concrete. You want to add a feature, and your tool of choice supports a repo-access mode, as most now do. You open the kit repo in the agent-enabled editor and ask for the new route following existing patterns, docs update included.

The agent scans the file tree, reads the in-tree config for extension conventions, writes the real files, updates the docs, and runs post-write checks where wired. You review the diff, commit, and push. No glue, no error-prone context assembly, no drift to reconcile by hand.

And if you later switch to a faster or cheaper model or tool, nothing breaks: in-repo config and conventions lay the same rails for every agent that speaks file-system.

The stable contract underneath tooling churnCopy Anchor Link

A new coding agent launches nearly every week, each with its own quirks, context limits, and opinionated CLI. The stable layer — the one that does not change — is a real codebase, shipped as files, with in-tree config telling any agent how to extend features the right way.

Your agent is only as strong as what it can see and change. Templates that ship static artifacts or pasted-in starters block the very reason developers want AI help: fast, safe extension of real software. Sandboxed tools look safe but stay shallow; file-system agents risk more but can actually get code shipped. That last mile is the only one that counts.

SourcesCopy Anchor Link

• Claude Code documentation — Claude Code as an agentic coding tool that reads codebases, edits files, and runs commands; the file-system-agent archetype.
• Cursor documentation — Cursor as a codebase-aware coding agent; second archetype citation.
• Model Context Protocol introduction — MCP as the open standard connecting AI applications to external systems including local files.

Point any file-system agent at a real starting point: browse OTF kits.