Neo

The Challenge

Codebases are opaque to most people. Even for engineers, understanding a new repository means hours of reading, navigating file structures, tracing dependencies, and building a mental model. For non-technical stakeholders — executives wanting an architecture overview, new hires onboarding, compliance teams auditing — the codebase might as well be a black box.

We wanted to build something simple: point an autonomous AI agent at any public GitHub repository and ask questions in natural language. "Explain how authentication works in this codebase." "Give me a high-level architecture overview for a board presentation." The agent explores, reads, reasons, and explains — like having a senior engineer walk you through the code.

The Technical Problem

Neo required an architectural choice: the Claude API or the Claude Agent SDK. The API handles request-response conversations — you send a prompt, you get a response. But Neo's agent needs to autonomously explore a codebase: reading files, searching for patterns, navigating directories, reasoning about what to look at next. That's tool use in an autonomous loop with no human-in-the-loop for approvals — the Agent SDK's domain, not the API's.

The trade-off: the Agent SDK doesn't just call an API — it orchestrates a local process that runs tools and maintains state. It spawns subprocesses, needs a persistent shell environment, requires filesystem access to read and navigate code. This is fundamentally incompatible with serverless functions.

Standard serverless platforms (Vercel, AWS Lambda) run in constrained sandboxes: no subprocess spawning, no persistent shell, no filesystem beyond /tmp, strict execution time limits. The Agent SDK needs a real compute environment — something closer to a development machine than a lambda function.

The question: how do you give a web visitor access to an autonomous agent that needs a full compute environment, without running dedicated servers?

The Architecture

A hybrid approach: Next.js handles the frontend on Vercel, while a Cloudflare Worker orchestrates agent execution in an isolated Sandbox container.

The Sandbox is the key innovation. Cloudflare Sandbox provides ephemeral Linux containers — real compute environments with filesystem, subprocess spawning, and persistent shell access. Each request gets a fresh container: the Worker clones the target repository into it, runs the Agent SDK, streams the results back to the browser, and the container is destroyed.

The pipeline: Browser makes a request to Next.js on Vercel. Next.js forwards to the Cloudflare Worker. The Worker spins up a Sandbox container, clones the repo, and executes the agent runner. The agent streams its exploration — tool calls, reasoning, responses — as NDJSON events back through the Worker to the browser. The visitor sees the agent thinking in real time.

Each container is ephemeral, isolated, and fresh. No shared state between requests, no cross-user contamination, no persistent data. The agent gets a clean environment every time — same as a developer opening a repo for the first time.

Two Surprising Insights

Self-Awareness Requires Explicit Framing

When asked "what tools can you use?", the agent would hallucinate capabilities — even after reading the source code that defines its constraints. The fix was a single line in the system prompt: "This codebase defines you."

With that framing, the codebase becomes the system prompt. The agent reads the allowedTools array and understands that it describes itself. It discovers what it can do by reading the code, not from instructions. This matters for autonomy — if you tell the agent its capabilities, it's not truly autonomous. If it discovers them by reading its own constraints, it is.

Stateless Context Is Solvable

Each request spins up a fresh container with zero memory. The agent has no idea what conversation just happened. The solution: the frontend collects recent conversation turns and prepends them to each prompt, wrapped in <conversation_context> tags. The system prompt is crafted to recognise and use prior history efficiently without broad re-exploration.

Simple, effective, and the right trade-off for a proof of concept. What changes when you need persistent memory is a different architectural decision — but for many agent applications, history prepending is enough.

The Pattern: Agent-to-UI

Neo demonstrates an architecture pattern that extends beyond codebases. The core: an autonomous agent that explores and explains a body of artefacts, made accessible through a web interface.

The same pattern applies wherever users need to navigate and understand complex information:

• Legal teams navigating contract repositories and case files
• Compliance officers reviewing policy documents and audit trails
• Researchers exploring academic literature and datasets
• New hires onboarding through company knowledge bases
• Analysts interrogating financial reports and documentation

The architecture handles this: a web frontend for the conversation, a worker for orchestration, and an ephemeral container where the agent has the compute environment it needs. The domain changes; the pattern doesn't.

What Neo Demonstrated

Neo proved that autonomous agents can be made accessible through a standard web interface — not just as CLI tools for engineers, but as products that anyone can use. The hybrid architecture (Vercel + Cloudflare Sandbox) solved the fundamental serverless incompatibility, and the streaming pipeline delivers real-time agent exploration to the browser.

The insights about self-awareness and stateless context directly informed how we think about agent design at Gramercy. Neo was the precursor — the first step from agents as tools to agents as products.