Overview

The Codebase surface gives an agent durable, structured access to source repositories. Where Builder is concerned with producing new software from a specification, Codebase is concerned with the harder problem: operating safely inside code that already exists, that the agent did not write, and that is too large to fit in any context window.

A production repository is not a pile of text. It is a graph of symbols, a history of decisions, a set of implicit invariants, and a test suite that encodes what the team actually believes. Treating it as a flat corpus and retrieving the top-k most similar chunks produces agents that write plausible code which violates conventions three directories away. Pimsy instead builds a persistent, incrementally-updated model of the repository and plans edits against that model.

The four-layer model#

Every repository attached to a workspace is represented at four levels of abstraction. Higher layers are cheap to query and give the agent orientation; lower layers are expensive and are consulted only for the regions an edit actually touches.

Why retrieval alone is insufficient#

Embedding search retrieves text that resembles the query. Code correctness depends on relationships that have no textual similarity at all. A function and the migration that changes the shape of its return value share no vocabulary. A configuration constant and the deployment manifest that overrides it are lexically unrelated. The symbol layer exists precisely to capture the edges that prose similarity misses.

• Definition resolution — a name in scope is bound to exactly one definition, not to the five files that mention it.
• Reverse references — before an edit, the agent enumerates every call site rather than guessing at blast radius.
• Type flow — signature changes propagate through the type graph so downstream breakage is known before any file is written.
• Test attribution — each symbol carries the set of tests that exercise it, making verification targeted rather than a full-suite gamble.

The edit lifecycle#

1. 1

   Orient

   The agent resolves the request against the corpus and semantic layers to identify candidate regions, without parsing anything.

2. 2

   Localise

   Candidate regions are expanded into a precise symbol set. Reverse references establish the true blast radius.

3. 3

   Plan

   A change plan is produced: an ordered list of symbol-level edits with the invariants each must preserve. The plan is inspectable before any file is modified.

4. 4

   Apply

   Edits are written as structured patches against a workspace branch. The working tree is never mutated in place.

5. 5

   Verify

   The behavioural layer selects the minimal test set that covers the changed symbols. Failures return control to the planner with the failure attached.

6. 6

   Present

   The agent emits a reviewable diff with per-hunk rationale linking each change back to the plan step that motivated it.

Boundaries#

Codebase deliberately does not own version control identity, CI credentials, or release authority. It produces branches and patches; a human or an explicitly configured policy decides whether those become commits on a protected branch. This separation is what makes it safe to grant an agent broad read access to a repository while keeping write authority narrow.