Category: AI Coding Agents

An agent searches for a feature name, finds no exact match, and concludes that the feature does not exist. It then adds a second implementation beside the first. That is not a random search failure. It is an inference failure: the retrieval method answered a narrower question than the agent believed it had asked.

Ralph code search problems become costly because the loop can repeat the same false negative with fresh confidence. The remedy is to understand what text search proves, recognize repository patterns that hide relationships, and require source-backed verification before turning “not found” into “missing.”

Why Ralph Can Miss Existing Features

Ralph code search problems begin where task language and repository language diverge. “Audit failed logins” may be implemented under event names, middleware, hooks, or a generic security pipeline. An exact search for the task phrase can return nothing even though the behavior exists.

That is a coding agent search failure when the agent converts a narrow text result into a broad behavioral conclusion. The correction is to narrow the conclusion or expand the evidence surface.

Geoffrey Huntley’s Ralph account documents this class of failure: an agent used ripgrep, concluded functionality was absent, and created duplicate code. The lesson is not that ripgrep behaves unpredictably. The lesson is that absence of a string is weak evidence about absence of behavior.

Repeated loops magnify the issue when each iteration starts with the same query and no durable record of the earlier search boundary. The next attempt may see a clean context but inherit the same task wording. Without a better retrieval plan, fresh context reproduces the same blind spot.

Implementation details matter too. Snarktank’s loop starts a new Amp or Claude process per iteration, while the Ralph Wiggum Claude Code plugin continues inside the current session through a Stop hook. Neither process model automatically supplies semantic repository search.

Where Text Search Breaks Down

A coding agent search failure is often a mismatch between the engineering question and the evidence a text query can return. ripgrep is deterministic, line-oriented, and built around regular-expression matches. By default it respects ignore rules and skips hidden and binary files. Those are documented boundaries, not nondeterminism.

Problems arise when the task asks about a relationship that text does not encode directly. A call may cross an interface, an import may be renamed, a framework may register handlers by configuration, or a generated client may expose a different symbol from its schema. Searching for one spelling cannot prove that none of those paths exists.

The search scope can also be wrong. Running from a subdirectory, respecting an ignore file, choosing a file-type filter, or excluding generated paths changes the evidence set. Reviewers need the query, working directory, flags, and relevant exclusions before accepting a negative result.

A query such as “Ralph Wiggum Claude Code” may identify the loop implementation, but it still does not identify repository aliases, generated symbols, or indirect callers. Product vocabulary and code vocabulary remain separate search surfaces.

Text matches may also be too broad. Common names return tests, fixtures, comments, vendored files, and unrelated packages. An agent can select the closest-looking match without establishing ownership. High recall is not the same as structural relevance.

Aliases, Generated Code, and Indirect Calls

A broad query such as “Ralph Wiggum Claude Code” identifies a workflow, not the aliases used by a particular repository. A package can re-export a symbol, a module resolver can rewrite a path, or a local adapter can wrap a vendor client. Search may find the definition but not the path used by the application, or find the call site without revealing which implementation is injected at runtime.

Generated code creates another authority problem. The runtime consumer may call a generated client, while the durable contract lives in an OpenAPI file, protobuf schema, or code generator configuration. Editing the generated file can pass a local search check and still be overwritten later. Retrieval needs to connect output to its source.

Indirect calls appear in event systems, dependency injection, reflection, plugin registries, route tables, and framework hooks. Some relationships can be resolved statically; others require configuration or runtime evidence. A structure-aware index should expose uncertainty instead of inventing a precise call edge.

Tests can reveal these paths, but only if the agent knows which behavior to run. A test named after a ticket may not mention the implementation symbol. Search across test descriptions, fixtures, and module imports, then confirm that the test actually exercises the path rather than merely sharing vocabulary.

How Structure-Aware Search Helps

Structure-aware retrieval begins with entities and relationships: definitions, references, imports, implementations, callers, callees, modules, and tests. A query can ask, “Which implementations satisfy this interface, which entry points reach them, and which tests cover those paths?” That is closer to the engineering question than a list of matching lines.

A code graph can provide this layer. Graphify is one possible codebase graph system that may return a task-sized subgraph with file and symbol provenance. It should complement exact text search: text is useful for literals, configuration values, comments, and dynamic registration strings that a static graph may miss.

Results remain candidates. The agent should open the cited source, verify the active commit, inspect configuration or generation boundaries, and run relevant checks. Dynamic behavior, conditional imports, macro expansion, and incomplete language support can all produce missing or misleading edges.

This graph capability is not native to the Ralph pattern or the cited implementations. Claude Code can connect to external services through MCP, but each service must document its indexing, freshness, permissions, and failure modes.

Verification and Debugging Limits

Treat every negative search result as a bounded statement: no match was found for this query, in this scope, under these exclusions, at this commit. Before concluding a feature is absent, vary the vocabulary, inspect likely owners and entry points, follow imports or interfaces, and check schemas, generated surfaces, and tests.

Log false negatives with enough detail to improve retrieval. Record the original task phrase, command or graph query, scope, exclusions, expected entity, actual source location, and reason it was missed. Aggregate by cause. A collection of anecdotes cannot tell whether aliases, ignored paths, language support, or task decomposition is the dominant problem.

Verification should scale with impact. A local helper may need source inspection and unit tests. A security check, migration, or public API requires broader consumer analysis and human review. Passing tests are necessary backpressure, but a narrow suite cannot prove that every indirect path was found.

Finally, do not force one retrieval system to answer every question. Exact search, symbol navigation, code graphs, build metadata, runtime traces, and human ownership knowledge cover different evidence surfaces. A reliable loop chooses among them and preserves the retrieval trail.

FAQ

When should search results be distrusted?

Distrust the conclusion, not the tool, when the query vocabulary differs from repository vocabulary, the scope or exclusions are unclear, aliases or generation are likely, or the task asks about behavior rather than text. Re-run with explicit scope and add structural or runtime evidence.

What evidence should reviewers request?

Ask for the exact query, working directory, flags, excluded paths, commit, files inspected after the search, and tests or checks run. For graph results, also request the index version, relationship type, and source provenance. The evidence should make a negative result reproducible.

How should teams log false negatives?

Store the task wording, retrieval query, expected result, missed file or symbol, root cause, and corrective action. Separate tool limitations from poor query formulation and stale indexes. Review the log periodically to improve task templates, indexes, and repository conventions.

How do we find errors in a code?

Use layered evidence: reproduce the behavior, read the relevant source, search exact values and symbols, follow structural relationships, run static checks and targeted tests, then review the diff and logs. No single search command or graph can establish correctness for every repository.

Conclusion

Ralph code search problems are usually mismatches between the question and the retrieval model. Text search can establish whether text matches exist in a defined scope. It cannot, by itself, prove that behavior, callers, implementations, or test coverage are absent.

Make negative results reproducible, add relationship-aware retrieval where the repository needs it, and verify every candidate in current source. For the implementation playbook, see how to stop Ralph rereading the repository. For the structural option, see Ralph knowledge graph integration.

An agent opens the router, searches for the service, reads the same interface, then repeats the sequence in the next iteration. The loop looks busy, but much of the work is repository orientation. On a large codebase, that repeated scan can consume more attention than the edit itself.

The goal is not to stop Ralph from reading source. Current source is the final authority. The goal is to stop Ralph rereading repository roots when a smaller, verifiable context slice would answer the task. That requires an index with provenance, scoped queries, durable findings, and clear reasons to fall back to a full scan.

Before You Optimize the Loop

Before you try to stop Ralph rereading repository roots, confirm which loop you are running. Geoffrey Huntley’s original Ralph pattern describes an outer loop driven by a plan and executable feedback. The snarktank implementation launches a new Amp or Claude process for each iteration. Anthropic’s official plugin continues through a Stop hook inside the current Claude Code session. These reset boundaries create different reasons for repeated scanning.

Then measure the behavior. Record which files and directories are opened per iteration, which searches recur, how often review finds a missed consumer, and whether the active task actually changed. A repeated read can be correct after a commit or branch change. It is wasteful when the repository state is unchanged and the agent is reconstructing the same verified relationships.

This baseline turns coding agent repeated scanning into an observable retrieval problem. Optimize only the repeated orientation steps whose repository state and answer remained unchanged.

Do not optimize by injecting a full repository summary into every prompt. Summaries drift, hide uncertainty, and can be larger than the discovery they replace. Define the target instead: the smallest source-backed context that lets an iteration locate the owner, understand affected relationships, respect write scope, and choose the right checks.

Build a Module and Dependency Map

Start with a lightweight map of modules and boundaries. This reduces coding agent repeated scanning by preserving only the orientation facts that can be checked against the active revision. For each module, capture its path, public entry points, owned symbols, direct dependencies, primary consumers, and associated tests. Add generated or schema-derived surfaces only if the task can affect them. Every item should point back to a file and commit, not merely repeat an architectural label.

The map does not need to model every runtime behavior. It needs to answer common orientation questions reliably. A package index plus import graph may be enough for a conventional service. A monorepo with generated clients, dependency injection, and cross-language schemas may need symbol, call, and generation edges.

Queries such as “Stop Ralph rereading repository Reddit” usually express frustration with the symptom, not a request for a particular cache. The implementation choice should follow observed failure modes. If the loop repeatedly forgets module ownership, build an ownership index. If it misses indirect consumers, model dependency and call relationships. If it reruns the same commands, fix the task handoff or repository instructions.

Text search stays in the workflow. ripgrep is deterministic and line-oriented. By default it respects ignore rules and skips hidden and binary files. An index should complement that retrieval model by representing relationships; it should not be sold as a repair for imaginary randomness.

Query by Task Instead of Repository Root

Translate the acceptance criteria into retrieval questions before opening directories. A search such as “Stop Ralph rereading repository Reddit” names a symptom; the task query still needs to name the owner, behavior, and evidence required. For “add retry handling to outbound billing calls,” ask which module owns the client, which entry points call it, where retry policy is configured, and which tests exercise failure responses. Begin with those results and expand only when current source exposes another dependency.

A task query should include the active commit, allowed write paths, and expected behavior. Results should include file, symbol, relationship type, provenance, and confidence or limitations. The agent then opens the cited source and confirms that the path still exists and the relationship means what the task assumes.

Graphify is one possible codebase graph layer for this retrieval step. It may help return a task-sized subgraph containing modules, dependencies, definitions, and tests. It is not necessary for every repository, and it should not replace exact search, directory inspection, or executable checks. A simple module manifest may be the better tool when repository structure is already explicit.

Keep results small. Ranking twenty likely files can be useful; dumping thousands of graph nodes recreates root-level scanning in another format. Prefer a staged query: owner and entry point first, direct dependents second, tests and generated surfaces third, broader traversal only after evidence shows it is required.

Persist Useful Findings Between Iterations

Persist findings that are expensive to rediscover and likely to remain relevant for the active task. Examples include the verified owner module, the actual entry point behind an alias, required tests, an unexpected generated artifact, and a rejected path with evidence. Attach the commit and source locations so the next loop can check freshness.

Keep that task handoff separate from durable project rules. In snarktank’s implementation, the prompt tells the agent to read Git history and progress.txt, work on one story, run checks, commit, and append useful information. Its README says progress.txt resets for a new branch. Those file semantics are specific to snarktank, but the broader principle is portable: active findings need a lifecycle tied to the task.

Project-wide commands and conventions can live in scoped instructions such as AGENTS.md, whose specification allows directory-level rules. Do not promote a one-off discovery into permanent guidance without review. Derived graph facts should remain read-only to the loop and be refreshed from source rather than manually rewritten.

A useful handoff is short enough to inspect. Label verified facts, hypotheses, failed attempts, and pending checks. Archive the longer event history if audit requires it, but do not force every iteration to reread it.

Risks, Drift, and Review Habits

Caching the wrong fact makes the loop faster in the wrong direction. Invalidate module and graph results when the commit, branch, index schema, generated code, or dependency lock state changes in a relevant way. If provenance cannot be compared with the active checkout, retrieve again from current source.

Access boundaries matter as much as freshness. A shared index may expose code or paths outside an agent’s task. Apply repository permissions to retrieval, and keep write scope independent from read access. A result that mentions another module is not permission to edit it.

Reviewers should request a retrieval trail for high-impact changes: initial task query, source files opened, edges followed, excluded paths, tests selected, and assumptions left unresolved. The purpose is not surveillance. It is to distinguish a safe narrow search from a narrow search that simply missed the real consumer.

Use full rescans deliberately. They are appropriate after major refactors, branch switches, index corruption, uncertain generation pipelines, or evidence that scoped retrieval produced false negatives. They are also useful as periodic audits. The optimization succeeds when broad scans become evidence-driven exceptions, not when they disappear.

Finally, compare the indexed path with a baseline on representative tasks. Look for missed consumers, stale facts, unnecessary context, and review corrections. Do not publish a universal speed or token claim from a small internal sample.

FAQ

What should not be cached?

Do not cache secrets, volatile runtime values, unverified hypotheses presented as facts, or structural results without provenance. Avoid making generated output authoritative when its source schema is available. Short-lived test failures can be recorded in task state, but they should expire when the environment or commit changes.

How should teams test retrieval quality?

Build a set of real repository tasks with known owners, consumers, tests, and edge cases. Compare scoped retrieval with source inspection and review findings. Track false negatives, stale results, irrelevant context, and how often the agent must broaden the query. Re-run the set after index or repository changes.

When should a full rescan happen?

Rescan after a major branch or commit change, structural refactor, index-version change, generation update, or evidence that returned relationships are incomplete. A full scan is also justified when the task crosses unfamiliar boundaries or affects security, migrations, or a public interface whose consumers are uncertain.

What is the Ralph loop in Claude Code?

Anthropic’s Ralph Loop plugin uses a Stop hook to keep the same prompt active until a completion condition or iteration limit is reached. It operates inside the current Claude Code session. That differs from shell implementations that launch a new process for every iteration, so context and persistence behavior should be documented separately.

Conclusion

To stop Ralph rereading repository roots, first identify the repeated orientation question. Build only the module, dependency, or test map needed to answer it. Query by task, open the cited source, persist verified findings for the active scope, and invalidate them when repository state changes.

The result should be a more disciplined reading path, not less verification. Text search, source inspection, type checks, tests, and review remain the backpressure that keeps a loop honest. For a deeper diagnosis of retrieval failures, see Ralph code search problems. For the structural model behind task-sized context, see knowledge graphs for AI coding assistants.

A long agent session can become an unreliable map of the repository. It contains earlier file contents, rejected hypotheses, transient failures, and instructions that may no longer match the current task. Resetting the conversation appears to solve that problem, but a clean window can also erase the reasoning that prevented a dangerous edit.

Ralph fresh context is useful only when durable project artifacts carry the right knowledge forward. The engineering question is not whether old chat is good or bad. It is which information should be re-read from current source, which should persist outside the conversation, and which should disappear at the next iteration.

What Fresh Context Solves

In a Ralph fresh context loop, a reset reduces commitment to an obsolete narrative. The next iteration can inspect the current plan, source, Git history, and test output without also weighing every abandoned approach from the previous session. In Geoffrey Huntley’s original Ralph description, each loop receives a new context window and works through a stable plan with tests, builds, or static analysis providing backpressure.

The snarktank loop creates a concrete process boundary by launching a new Amp or Claude process for each iteration. That can make failures easier to isolate and encourage the agent to rely on repository artifacts rather than an expanding chat transcript.

A coding agent context reset also creates an inspection point. Teams can define exactly what the next iteration receives: a task specification, applicable repository rules, a short progress handoff, current source, and recent validation results. If that set is too large or too vague, the problem is visible before the next prompt begins.

What It Can Lose Between Iterations

A coding agent context reset can discard useful observations that are not already in the code. An iteration may discover that a generated client must be refreshed, a flaky integration test needs a particular fixture, or a symbol with an obvious name is not the real entry point. If the observation remains only in conversation, a clean reset can force the next loop to relearn it.

The more serious loss is rationale. Source shows what exists, but not always why a constrained choice was made or why a plausible alternative failed. Git history may help, yet commit messages are rarely a complete operational handoff. A concise task note can preserve the evidence and scope of a decision without carrying the full transcript.

Fresh context can also hide an unresolved assumption. The previous iteration may have decided that a search result proved a feature was missing. If that inference is summarized as fact, the reset removes the uncertainty while preserving the conclusion. Handoffs should distinguish verified facts, hypotheses, failed attempts, and pending checks.

A Ralph fresh context review should record which observations were lost, which were promoted into durable artifacts, and which still require verification. That review makes reset quality inspectable instead of treating a clean window as success by itself.

Persistent Memory vs Conversation Carryover

Conversation carryover is easy but weakly structured. Its lifetime is tied to a session, its scope can be unclear, and later turns may treat old statements as current. Persistent memory can be smaller and more explicit: task status, reviewed repository rules, committed code, test results, and structural findings with provenance.

The distinction is implementation-specific. Anthropic’s official Ralph Loop plugin uses a Stop hook to continue inside the current Claude Code session. That is not the same reset boundary as snarktank’s new process. Teams should test their actual tool rather than infer session behavior from the Ralph name.

Persistence also needs ownership. An agent can update branch-local progress, but durable project rules should require review. Derived code relationships should be rebuilt or checked against current source. Secrets and private prompt content should not flow into a shared log merely because it is convenient.

A practical Ralph fresh context review asks three questions: what artifact will survive, what makes it authoritative, and what event makes it expire? If any persisted item lacks those answers, it is likely to become stale context in a different form.

Repository Knowledge That Should Survive

The task specification and acceptance criteria should survive unchanged unless the authorized owner revises them. Current code and commits should remain the primary implementation record. The next iteration also needs the applicable build, test, and formatting commands, plus directory-scoped rules such as those supported by the AGENTS.md specification.

Verified structural knowledge may also deserve persistence: module ownership, interface implementations, downstream consumers, test mappings, and entry points. A code graph can provide that orientation layer if each result cites the file, symbol, commit SHA, and index version. Graphify is one possible codebase graph layer; its output should be treated as candidate context and confirmed in source.

Short-lived experience can survive in an active task handoff. Record the failed command, the observed result, and the next check rather than a broad conclusion. Once a lesson is shown to recur and its scope is understood, it may be promoted into reviewed project guidance.

The full conversation usually should not survive by default. Retain it for audit when required, but feed the next iteration a curated set of durable artifacts. A smaller handoff makes contradictions easier to see.

Cost, Drift, and Review Risks

Resets are not free. Re-reading files, rerunning discovery, and reconstructing architecture consume time and context. If several iterations open the same modules before every edit, the team has probably under-specified the durable orientation layer. Measure that repetition before adding a large memory system.

Persistence creates the opposite risk: drift. A progress note can outlive its branch, a project instruction can stop matching the build, and a graph can describe an earlier commit. Tie active task state to task or branch identity, review instructions when they are contradicted, and invalidate structural results when provenance no longer matches.

Reviewers should inspect what crossed the reset boundary, not only the final diff. Ask whether each carried statement is fact, inference, or instruction; whether its source is current; and whether it grants more write scope than the task allows. This is especially important for security boundaries, migrations, and public APIs.

Finally, avoid treating passing tests as complete proof. Tests are essential backpressure, but they only cover what the suite exercises. Source inspection, scoped search, type checks, and human review remain necessary when the change affects relationships that the test suite may not encode.

FAQ

What should survive a reset?

Keep the authorized task, current repository state, applicable reviewed rules, relevant test results, and verified findings that the next iteration would otherwise have to rediscover. Include provenance and expiration for structural or operational notes. Do not preserve every hypothesis merely because it appeared in the earlier session.

How should teams inspect carried memory?

Use a small, typed handoff. Label facts, hypotheses, decisions, failures, and pending checks. For each material fact, cite current source, a commit, test output, or another authoritative artifact. Review who can write each layer and reject entries whose scope or freshness is unknown.

When is a clean reset safer?

It is safer when the current session is dominated by stale file contents, contradictory instructions, repeated failed approaches, or an unrelated prior task. Before resetting, persist only the verified state needed to continue. If critical rationale cannot be reconstructed from durable artifacts, repair the handoff first.

What is the Ralph method of AI?

Ralph is a repeated coding-agent workflow in which a stable task or plan drives successive implementation attempts and executable checks provide feedback. It is a pattern with multiple implementations, not a single required session model. Fresh-process, fresh-window, and same-session hook loops should not be conflated.

Conclusion

Ralph fresh context is a control over attention, not a substitute for memory design. It can reduce old-chat pollution and loosen attachment to a failed approach. It can also erase architecture, rationale, and unresolved uncertainty when those exist only in the conversation.

Define the reset boundary for the implementation you actually run. Preserve a small set of typed, scoped, and verifiable artifacts; let temporary hypotheses expire; and check current source before acting on carried knowledge. For the structural layer, see knowledge graphs for AI coding assistants. For a practical response to repeated discovery, see how to stop Ralph rereading the repository.

An autonomous loop does not need one giant memory file. It needs several kinds of state with different owners, lifetimes, and validation rules. Mixing a current task status, a repository-wide convention, an unverified debugging note, and a dependency relationship into the same document turns convenience into ambiguity.

Ralph Loop memory is therefore better treated as a layered design problem. The original Ralph pattern emphasizes durable plans, repository changes, and executable feedback. Particular implementations add their own state surfaces. The job for a team is to decide what each surface means, who may update it, and when it expires.

What Ralph Loop Memory Includes

At least four layers usually matter:

The purpose of Ralph Loop memory is to preserve those layers without granting temporary task notes the authority of reviewed project rules or current source.

• Task state: what is being attempted, what is complete, what failed, and what remains.
• Project rules: stable commands, conventions, boundaries, and review requirements that apply beyond one task.
• Experience: observations from an iteration, including failed approaches and useful paths, which may or may not deserve promotion into a project rule.
• Code structure: current modules, symbols, dependencies, call paths, and test relationships derived from source.

These layers overlap, but they are not interchangeable. “Run the API tests after changing the schema” may become a durable rule. “Test 17 failed because my fixture was stale” is task history. “Package B imports interface A” is a structural claim that should be regenerated or verified when the code changes.

The names of the storage files are implementation details. Huntley’s original Ralph description discusses a plan file, repository work, and feedback from builds or tests. The snarktank implementation uses prd.json, progress.txt, Git history, and prompt guidance.

Task State vs Project Rules

Task state is scoped and mutable. It can record the selected story, acceptance criteria, incomplete checks, and a concise note for the next iteration. It should reset or archive when the task or branch changes. If task state accumulates indefinitely, the next loop must distinguish relevant evidence from historical noise.

A search for Ralph progress.txt is useful only after the team has confirmed that it is discussing the snarktank implementation rather than Ralph as a general pattern.

Project rules are broader and more stable. They include build commands, style constraints, package ownership, security requirements, and known repository-specific traps. They should change through review because a mistaken rule can misdirect every later task. The AGENTS.md specification supports scoped instruction files: instructions apply to a directory tree, and a more deeply nested file can refine or override them within its own scope.

That hierarchy is useful because many “global” rules are not global. A frontend package and a data migration directory may have different validation commands and write constraints. Putting both in a root note forces every loop to carry irrelevant instructions. Scoped project rules reduce context while making ownership visible.

The boundary is promotion. An iteration may discover a recurring repository fact, but it should not silently convert a one-off observation into a permanent rule. Promotion should require evidence, a clear scope, and an owner. Otherwise the memory layer becomes a collection of confident anecdotes.

Progress Files, AGENTS.md, and Git History

In snarktank’s loop, progress.txt is an append-oriented handoff between iterations. The prompt template tells the agent to read it, use Git history, work on one story, run quality checks, commit, and append useful information. The README says the file is archived and reset when a new branch starts. Those are properties of that implementation, not of every Ralph loop.

A team searching for a Ralph loop Codex workflow should design the memory layers first rather than copying those filenames without their semantics.

Git history serves a different purpose. It records durable changes and their sequence, but a commit message is not necessarily a complete task handoff. The next loop may need current test failures or a reason an attempted approach was abandoned. That short-lived operational context belongs in task state, while the code itself remains the primary record of implementation.

AGENTS.md should hold reusable instructions, not a transcript of the current story. A useful entry explains a command, invariant, or directory convention that future tasks will need. Story-specific steps should remain in the task plan or progress file. This division prevents a temporary workaround from becoming permanent policy.

No layer should be trusted merely because it persisted. Read the current source, inspect recent changes, and use tests or static checks as backpressure. Memory narrows where to look; it does not supersede the repository.

Where Code Graphs Store Structural Knowledge

Structural knowledge has a different update model from prose memory. Imports, calls, implementations, schema references, and test coverage can change with a single commit. A code graph can index those relationships and answer a task-scoped query, but the returned facts should include file, symbol, commit SHA, and index version.

For a Ralph loop, this creates a read-mostly orientation layer. The task can ask which modules depend on a changed interface or which tests touch a call path, then verify the cited source before editing. Graphify is one possible codebase graph layer for this use case. It should complement exact text search and source inspection, not replace them.

This is an extension to the Ralph pattern. The cited Huntley, snarktank, and Anthropic Ralph implementations do not define a native code graph. Claude Code supports external integrations through MCP, but a graph service still needs its own freshness, access, and provenance controls.

Structural facts should rarely be hand-edited as prose. If the graph disagrees with source at the active commit, source wins and the index should be repaired. Human annotations may explain an architectural intent, but they should be stored separately from derived edges so reviewers know which assertions were computed and which were authored.

Failure Modes and Cleanup Notes

The first failure mode is stale authority. An old note may describe a module that moved, a command that changed, or a task that was abandoned. Every layer needs an expiration policy: task state resets at a task boundary, project rules are reviewed when contradicted, and structural indexes invalidate on commit or schema drift.

The second is conflict. A root instruction, nested instruction, progress note, and current source may disagree. Resolve the conflict by scope and authority: current source and executable checks establish behavior; the most specific reviewed instruction governs process; task notes explain intent but do not override verified reality. Record the resolution so the next iteration does not repeat it.

The third is uncontrolled growth. Append-only logs are useful for audit, but poor as an active prompt once they become long. Archive completed episodes, summarize only verified lessons, and keep the active handoff small. Do not delete history that is required for review; remove it from the hot context.

Finally, prevent sensitive data from entering shared memory. Progress logs and graph indexes can outlive a session and reach more agents than the original prompt. Store secrets in approved secret systems, restrict indexed paths, and review access separately for task, policy, and structural layers.

FAQ

What memory should be read-only?

Treat derived structural indexes, approved project rules, and finalized task specifications as read-only to an implementation loop unless an explicit workflow authorizes updates. The loop can propose changes, but another check or owner should validate them. Active task status can be writable within its branch and scope.

When should progress files reset?

Reset or archive them when the branch, feature, or task identity changes, or when a completed episode no longer belongs in active context. Preserve an auditable copy if the work requires it. Snarktank documents a new-branch reset, but other implementations can choose a different boundary if they state it clearly.

Who resolves memory conflicts?

The owner of the affected scope should decide process or architecture disputes. Before escalation, the agent should gather current source, applicable instructions, commit history, and test evidence. Conflicts involving security, public APIs, or cross-team ownership should not be resolved by an autonomous loop alone.

What is the Ralph loop pattern?

It is a repeated agent-development cycle driven by a stable task or plan and constrained by feedback such as tests, builds, or static analysis. Some implementations start a new process per iteration; Anthropic’s official plugin continues through a Stop hook in the current Claude Code session. Memory surfaces therefore vary by implementation.

Conclusion

Good Ralph Loop memory is less about remembering everything and more about preserving the right evidence at the right layer. Task state should be small and resettable. Project rules should be scoped and reviewed. Experience should be promoted cautiously. Code structure should be derived from current source and carry provenance.

When those boundaries are explicit, a fresh iteration can recover what it needs without treating an old conversation as architecture. For the structural retrieval layer, see knowledge graphs for AI coding assistants. For the reset boundary that makes these layers necessary, see Ralph fresh context trade-offs.

A loop can keep an agent moving without keeping it oriented. On a small repository, reopening a few files may be enough. On a large codebase, the agent must repeatedly recover module ownership, call paths, test boundaries, generated surfaces, and local conventions before it can make a safe edit. That recovery cost is easy to mistake for implementation work.

The Ralph pattern makes this tension visible because it deliberately repeats an implementation cycle. Geoffrey Huntley’s original description uses a simple outer loop, a stable plan, one task per iteration, and tests or builds as backpressure. It does not prescribe a universal repository-memory system. A practical Ralph Loop large codebase workflow therefore needs a separate answer to a narrower question: what repository context should each iteration recover, and how should it verify that context before writing?

Why Ralph Loops Repeat Repository Search

Each iteration begins with an information deficit. The task may be durable, but the agent still needs to locate the relevant implementation and understand how it fits the repository. In Huntley’s formulation, each loop receives a new context window. In the snarktank implementation, each iteration launches a new Amp or Claude process. That makes rediscovery an expected property of those implementations, not proof that the loop is broken.

In a Ralph Loop large codebase workflow, that information deficit should be treated as an orientation problem with a bounded evidence target.

The problem becomes expensive when discovery restarts from the repository root. A broad text search can find exact names, but a task often arrives in behavioral language: “preserve the import contract,” “update every consumer,” or “find the test that protects this path.” The relevant code may use aliases, wrappers, dependency injection, generated clients, or a name that differs from the task wording. An agent can spend several iterations reconstructing the same relationships.

What Fresh Context Helps With

Fresh context can reduce attachment to a failed approach. The next iteration reads the current repository rather than relying on a long conversational narrative about what the repository used to contain. If the previous attempt changed code, tests, or the plan, the new iteration can inspect those artifacts directly. This supports Ralph’s core bias toward durable work products and executable feedback.

It also limits the amount of incidental discussion competing with the task. A concise specification, current source, and test result are usually better inputs than a transcript containing several abandoned hypotheses. For long-running work, that reset can improve attention and make the loop easier to inspect.

Useful Ralph repository context is therefore the smallest set of durable artifacts that lets the iteration verify the current task without inheriting every abandoned hypothesis.

But “fresh” is implementation-specific. The official Anthropic Ralph Loop plugin uses a Stop hook to continue inside the current Claude Code session. It does not create the same clean-process boundary as the snarktank script. Teams should document the actual reset boundary instead of assuming that the word Ralph guarantees one.

What Large Codebases Need Beyond Search

Large repositories need a compact structural orientation layer. At minimum, an iteration should be able to answer:

This is also why the phrase “Ralph loop GitHub” is ambiguous. Huntley’s pattern, snarktank’s shell scripts, Anthropic’s Claude Code plugin, and Ralph Orchestrator make different choices about process lifetime and persisted state. Treating one repository’s files as properties of every Ralph loop creates false assumptions before repository search even begins.

• Which module owns the behavior?
• Which public entry points reach it?
• Which modules depend on the symbols likely to change?
• Which tests, schemas, migrations, or generated artifacts constrain the edit?
• Which repository rules apply in this directory?

Text search remains part of the answer. ripgrep is a deterministic, line-oriented regular-expression search tool. Its default treatment of ignored, hidden, and binary files matters, and text matches alone do not encode call or dependency relationships. The safe conclusion is not that search is unreliable. It is that search has a defined retrieval model, and the task may require evidence outside that model.

Repository rules should also follow scope. An AGENTS.md file can carry instructions for a tree, with more deeply nested files taking precedence for their subdirectories, as described by the AGENTS.md specification. That is useful policy context, but it is different from code structure. Combining policy, architecture, task status, and observations into one undifferentiated note makes every layer harder to validate.

Where Code Graphs Fit the Loop

A code graph can serve as one possible repository-orientation layer. It can index modules, definitions, imports, calls, inheritance, and test relationships, then return a task-sized subgraph instead of a repository-wide dump. For example, an iteration changing an authentication interface could request the definition, direct and indirect consumers, related tests, and paths where the interface crosses a package boundary.

That result should be treated as candidate context, not truth. The agent still needs to open the cited files, confirm symbol resolution, and run the repository’s tests or static checks. Graph data can be stale, incomplete, or blind to dynamic behavior. It is most useful when every returned relationship includes provenance such as file path, symbol, commit SHA, and index version.

Graphify is one possible codebase graph layer for this role. The relevant product claim is modest: structure-aware retrieval may reduce repeated orientation work when a repository’s relationships are difficult to recover from isolated text matches. It does not make every repository easier, replace source inspection, or remove the need for backpressure.

This integration is an editorial extension to the Ralph pattern. Neither Huntley’s original loop nor the cited snarktank and Anthropic implementations include a native code-graph bridge. Claude Code can connect to external tools through MCP, but the existence and behavior of any graph service must be verified separately.

Limits and Verification Notes

The first limit is drift. A graph built at one commit can mislead an agent working at another. Pin retrieval to the active commit when possible, reject results with mismatched provenance, and rebuild or incrementally update the index after structural edits. If a relationship cannot be traced to current source, it should not authorize a change.

The second limit is task scope. Retrieving every caller in a monorepo can recreate the same context overload as reading the repository root. Queries should begin with the task’s expected behavior and write scope, then expand only when evidence exposes an additional dependency. The output needs ranking and boundaries, not merely more nodes.

The third limit is verification quality. Tests are backpressure, not a proof that the retrieved architecture is complete. Reviewers should ask which files were searched, which graph edges were followed, what assumptions remain, and whether generated or runtime-only relationships were inspected. A change that passes a narrow unit test can still violate an external contract.

Finally, teams should measure the orientation layer against real failures. Useful signals include repeated opening of the same files, missed consumers found in review, unnecessary full-repository scans, and stale results rejected by provenance checks. Those observations are more defensible than a generic promise of faster agents.

FAQ

What should persist between loops?

Persist durable task state, accepted repository rules, committed code, test results, and verified structural findings with provenance. Keep short-lived hypotheses separate. The exact files depend on the implementation: snarktank uses prd.json, Git, and progress.txt, while Huntley describes a plan file and repository artifacts. Do not treat those names as a universal Ralph contract.

Who reviews recovered architecture assumptions?

The agent should verify them against current source and tests first. A human reviewer or designated code owner should review assumptions that affect public interfaces, security boundaries, data models, migrations, or multiple teams. The review should cite paths and symbols so disagreement can be resolved from evidence rather than summaries.

When should search results be ignored?

Do not ignore them merely because they are incomplete. Treat them as one evidence source. Reject or qualify results when they come from the wrong commit, excluded paths, generated output that is not authoritative, ambiguous symbols, or an index with unknown freshness. Then use another retrieval method and inspect the source.

What is Ralph in AI coding?

Ralph is a development pattern in which an agent repeatedly works from a stable task or plan, changes the repository, and receives feedback from tests, builds, or other checks. Implementations differ in session lifetime, memory files, stopping conditions, and concurrency, so the name describes a family of loops rather than one fixed tool.

Conclusion

The central challenge in a Ralph Loop large codebase workflow is not preserving the entire previous conversation. It is recovering the smallest trustworthy slice of repository context for the next task. Fresh iterations help when durable artifacts and executable feedback carry the work forward, but they can waste time when architecture must be rediscovered from scratch.

Start with scoped text search, repository rules, current source, and tests. Add structure-aware retrieval when repeated failures show that relationships are the missing layer. Keep every result tied to current code, and let the loop expand context only when the task requires it. For the broader retrieval model, see knowledge graphs for AI coding assistants; for the state layers between iterations, see Ralph Loop memory.

CodeWhale Fleet context sharing should give every worker the same revision-bound repository evidence while keeping instructions, writable scope, hypotheses, and execution state task-specific. Codewhale Fleet supports task-level input_files and extra context, plus durable ledgers, bounded artifacts, and receipts. Its v0.9.0 documentation does not describe a native code graph, repository index, or Fleet-wide shared repository memory.

The distinction prevents a common multi-agent failure: several workers independently scan the same repository, create incompatible summaries, and return conclusions that cannot be traced to the same source revision. A shared layer should reduce that duplication without merging worker transcripts or turning one agent’s guess into a fleet fact.

The Fleet Worker Context Problem

Codewhale describes Agent Fleet as a local-first control plane for durable multi-worker runs. A Fleet worker is a headless codewhale exec run launched and tracked by the fleet, not a separate execution engine. Fleet is designed for work that needs retries, restart survival, receipts, or a ledgered audit trail.

Durability solves lifecycle problems. It does not solve evidence selection by itself.

When four workers investigate a large repository without a common map, they may use different terms for the same subsystem, choose different entry points, or rely on different revisions. One worker may infer that a handler is unused after a text search. Another may find it through configuration. A third may examine only the nearby unit tests. Their summaries can all sound reasonable while describing different slices of the system.

Codewhale gives a Fleet task useful scoping fields. The v0.9.0 task specification can declare a workspace, required files, writable paths, input_files, extra context, budgets, timeouts, expected artifacts, and verification scorers. Those fields let a manager send a compact evidence packet to a worker. They do not automatically build or synchronize repository knowledge.

Short-lived subagents have another relevant boundary. The agent path starts fresh by default and receives its role prompt plus the assigned task. fork_context: true explicitly carries the parent request prefix when continuation is necessary. Teams should not assume a child has absorbed the parent’s repository analysis unless the task or fork includes it.

Shared Read-Only Knowledge Layer

The shared layer should be an external, read-only view of repository facts for a pinned revision. Workers query it; they do not casually rewrite it during task execution.

Useful contents include:

• module, package, service, and entry-point boundaries;
• symbols, imports, calls, registration paths, and schema flows;
• related unit, integration, contract, and end-to-end tests;
• generated-code sources and downstream artifacts;
• owners, architecture decisions, and external contracts;
• provenance, confidence, and the commit used to derive each relationship.

This can be implemented with a versioned repository map, a code graph, a generated report, or a combination. The format matters less than the contract: every load-bearing claim must lead back to current evidence. An inferred call edge should not look identical to a parsed import. A manually documented design intention should name its owner and decision record.

The manager then builds a task packet from that layer. Fleet’s input_files field can name the relevant source set, while context can state the objective, revision, retrieved relationship paths, acceptance criteria, and unresolved risks. The worker should still read the current source before changing it.

This design is not a hidden Codewhale feature. It is an external repository-context pattern connected to documented Fleet task inputs. For a broader architecture, Agent Swarm Codebase Context explains how shared evidence, task packets, isolated execution, and controlled fan-in work together.

Separate Worker State From Repo Facts

Repository facts and worker state have different lifetimes and approval paths.

Record	Scope	Examples	Promotion rule
Shared repository evidence	Revision-bound, cross-task	imports, callers, owners, test links	refreshed from source and reviewed
Task packet	One assignment	objective, selected files, constraints, acceptance tests	discarded or archived with task
Worker state	One run	plan, tool results, hypotheses, partial findings	never treated as shared fact automatically
Fleet evidence	One durable run	ledger events, artifacts, receipt, scorer result	retained for audit and fan-in
Personal memory	User-level, opt-in	durable preferences across sessions	not a repository fact store

Codewhale’s user memory is intentionally user-scoped and disabled by default. When enabled, subagents can inherit the user memory file. That does not make it a Fleet repository map. The memory documentation explicitly distinguishes personal preferences from repo-specific project instructions.

Worktree isolation also needs precise language. Codewhale documents worktree: true for the agent or subagent launch path: it creates a child branch and checkout and runs that child from the isolated path. The Fleet task schema lists workspace, files, and writable paths, but the cited v0.9.0 Fleet guide does not present worktree as a general Fleet task field. Do not promise Fleet worktrees unless the exact launch path and installed release support them.

The safest rule is that a worker may propose new shared knowledge, but it cannot ratify it. The proposal should include the source revision, evidence locations, derivation method, and confidence. A repository owner or an automated refresh pipeline decides whether the shared layer changes.

Prevent Conflicting Summaries

Conflicting summaries become manageable when workers cite evidence instead of copying prose from one another.

Codewhale Fleet already provides useful audit primitives. Workers write bounded artifact files under .codewhale/fleet/; the ledger stores artifact references with path, checksum, MIME type, and size. Receipts can report pass, fail, partial, skip, or timeout, and deterministic scorers can check exit codes, file existence, regular expressions, or JSON paths.

Use those primitives to enforce an evidence-rich output contract:

1. State the revision. Every summary names the commit or immutable workspace snapshot.
2. Cite source locations. Architecture or impact claims point to files and symbols.
3. Name the retrieval path. Record the graph query, index lookup, or search command.
4. Separate observation from inference. “File imports type” is not the same as “runtime uses behavior.”
5. Attach verification. Include test commands, results, artifact checksums, and scorer status.
6. Report disagreement. Do not flatten two incompatible findings into a confident compromise.

Fan-in should belong to a manager or workflow owner. Codewhale’s Fleet documentation makes this explicit: when one combined result is needed, an owner aggregates, verifies, and synthesizes worker receipts. Dispatch is not completion.

If two workers disagree, re-run the smallest query or test that decides the issue. Prefer live source and tool evidence over old handoffs. The shared map should record the resolved fact only after the supporting source is identified.

Safe Rollout Pattern

Adopt shared Fleet context in a narrow subsystem before applying it across a monorepo.

• Choose one subsystem with known owners and reliable tests.
• Pin the repository revision and generate a minimal module, dependency, and test map.
• Review graph edges and label parsed, generated, documented, and inferred facts.
• Define one read-only role and one small change or audit task.
• Supply only the relevant input_files, relationship paths, constraints, and expected artifacts.
• Keep each worker’s writable paths and task notes separate.
• Require receipts to cite source locations and verification artifacts.
• Let a manager reconcile conflicts and reject unsupported claims.
• Refresh the map after accepted source changes, then rerun affected queries.
• Compare search duplication, startup time, missed dependencies, and review corrections against a baseline.

Do not begin by copying full transcripts into a global memory file. That preserves noise, assumptions, secrets, and stale task state. Start with source-derived relationships that reviewers can reproduce.

The related CodeWhale Context Optimization Guide focuses on measurement and reducing repeated reads. This article owns the narrower design of what Fleet workers share and what remains isolated.

FAQ

How should worker outputs cite shared context?

Each output should name the repository revision, shared-context version, query or retrieval path, direct source locations, and any low-confidence edges used. The worker’s Fleet artifact should carry a checksum, while the receipt reports verification status. A reviewer should be able to reconstruct the conclusion without trusting the worker transcript.

Who updates the shared repository map?

A repository owner or reviewed automation pipeline should update it from accepted source changes. Workers can submit proposed additions with provenance, but they should not silently promote their own summaries. Ownership should follow the affected subsystem, with a maintainer responsible for graph-generation rules and freshness checks.

What should stay outside shared memory?

Keep secrets, credentials, raw prompts, private reasoning, speculative diagnoses, transient logs, unreviewed summaries, task-specific write plans, and provider-specific behavior outside the shared repository layer. Codewhale’s opt-in user memory should remain a personal-preference surface, not a substitute for revision-bound repo evidence.

Conclusion

Codewhale Fleet provides durable workers, scoped task inputs, ledgers, artifacts, and receipts. Those are strong coordination primitives, but they do not create shared repository understanding automatically.

Build a read-only, revision-bound evidence layer outside Fleet. Retrieve a small packet into each task, isolate worker state, and require source-linked receipts. When workers disagree, let current source, tests, and a named fan-in owner decide. Shared context is safe only when every worker can cite it and no worker can quietly redefine it.

Supacode agent context optimization reduces repeated repository discovery by preparing a revision-bound project map, dependency and test indexes, and a small task-specific evidence packet before each worktree starts. Keep plans and terminal state isolated, verify retrieved facts in current source, and measure correctness alongside tokens and startup time.

Supacode itself should stay in its documented role. As of July 23, 2026, its official docs cover real Git worktrees, managed local storage, per-worktree terminal state, and configurable run, setup, and archive commands. They do not document a built-in repository index, shared memory, or knowledge graph. The optimization layer described here is a team-owned companion workflow.

Why Parallel Agents Repeat the Same Search

Every new coding session begins with uncertainty. An agent needs to find the repository layout, entry points, dependency manifests, relevant symbols, tests, and local instructions. Parallel worktrees isolate those sessions, so they often repeat the same searches independently.

Repeated scanning has several causes:

• repository knowledge remains in a previous terminal transcript or model session;
• onboarding documents describe directories but not current symbol relationships;
• agents receive a broad task without likely entry points or a write boundary;
• search failures disappear, so the next agent tries the same weak query;
• cached summaries lack a commit and cannot be trusted after the branch moves;
• task-specific conclusions are mixed with stable repository facts.

The cost shows up as more than input tokens. Agents take longer to produce a defensible plan, open irrelevant files, choose overly broad tests, and sometimes miss indirect dependencies. Reducing reads without improving evidence quality merely hides the problem.

Supacode’s per-worktree terminal state can preserve tabs, splits, and focused surfaces within that worktree. It does not transfer repository understanding to another worktree. Optimize the evidence supplied to each agent, not just the shell it launches in.

Map the Repository Before Tasks Start

Create a compact project map from an approved base commit. The map should help an agent answer where to look, not pretend to summarize the entire system.

Include:

1. top-level modules, packages, applications, and deployable units;
2. public entry points and main configuration files;
3. generated directories and the commands that produce them;
4. authoritative architecture and contribution documents;
5. ownership and review boundaries;
6. the indexed commit, generator version, exclusions, and failed parses.

Use stable identifiers such as repository-relative paths and qualified symbols. Avoid copying large file bodies into the map. A short description with a source citation is easier to refresh and audit.

At task start, retrieve only the relevant slice. The evidence packet should name the goal, branch, base commit, likely modules, cited source paths, permitted write scope, expected tests, and unknowns. The agent must verify those paths in its own checkout before editing.

Supacode Shared Context Across Worktrees describes how multiple worktrees can query this map without sharing task state.

Use Dependency and Test Indexes

A directory map improves orientation, but dependency and test indexes reduce the most expensive repeated reasoning. Build relationships that support impact analysis:

• symbol definition to direct callers;
• interface to implementations;
• package to imports and consumers;
• schema to producers and readers;
• generated output to generator;
• feature, symbol, or endpoint to relevant tests;
• configuration key to code paths that read it.

Every relationship should cite source and revision. Mark whether an edge was parsed, configured, or inferred. Static indexes cannot reliably see every dynamic registry, reflection path, environment-controlled branch, or external consumer. Agents should confirm high-impact edges through current search, focused tests, and responsible reviewers.

Test indexing should emphasize why a test is relevant. Filename proximity is a weak signal. Record the behavior, public boundary, fixture, or source unit connected to the test. Also distinguish fast focused tests from slower integration or environment-dependent checks.

When a task changes a public interface, dependency manifest, schema, code generator, or package boundary, refresh the affected index slice before another agent relies on it. A known stale flag is safer than a silently outdated graph.

The 1M Context vs Knowledge Graph comparison explains why more prompt capacity does not remove the need for fresh relationship selection.

Keep Task Context Separate

Optimization fails when shared context becomes a dump of every agent’s activity. Separate neutral repository facts from task-local state.

Shared context may contain modules, symbols, dependency edges, related tests, approved decisions, owners, source citations, and coverage gaps. Task context should contain the plan, assumptions, terminal output, failed experiments, uncommitted diff, temporary environment settings, and provisional conclusions.

This separation improves both safety and retrieval quality. Credentials and sensitive logs stay out of the common index. Search results are not polluted by abandoned plans. A task agent cannot silently redefine a repository fact for every other worktree.

Supacode supports repeatable repository commands. Use a reviewed setup script to prepare dependencies or launch an agent, a run command for the standard development or test process, and an archive command for cleanup. These values may be stored in repository-root supacode.json or Supacode’s local settings. Keep secrets outside command files and keep context generation explicit.

For a broader worktree boundary, Git Worktree vs Knowledge Graph separates per-worktree Git state from revision-bound structural context.

Measure Token and Startup Savings

Measure optimization against a baseline on representative tasks. Do not promise a fixed percentage: repository languages, task type, agent, tool calls, cache state, and context format all affect the result.

Track:

• time from worktree creation to an evidence-backed plan;
• input tokens before the first edit;
• repeated searches and files reopened across agents;
• relevant versus irrelevant files inspected;
• stale-context corrections;
• missed dependencies found during review;
• focused and integration test selection;
• patch rework and integration conflicts.

A useful trial runs the same class of task under two controlled conditions. The baseline agent uses ordinary repository search. The optimized agent receives a revision-bound map and task evidence packet. Record model, tool configuration, repository commit, prompt, date, and outcome. Compare correctness first, then resource use.

Token reduction counts only when evidence quality is preserved. If an agent opens fewer files but misses a caller, the workflow is worse. If startup is faster but stale context causes rework, the apparent saving moves downstream.

Review measurements by task class instead of combining them into one average. A narrow bug fix, cross-module refactor, and unfamiliar-service investigation have different discovery costs and freshness risks. Preserve search traces for representative failures so a shorter startup can be distinguished from a packet that simply omitted the evidence an agent needed.

Review failed searches as data. Record the query, task, missing entity, expected source, result, and eventual resolution. Repeated failures can reveal missing aliases, unsupported languages, generated-code gaps, or a poor test taxonomy.

FAQ

What signals show context is stale?

The worktree commit differs materially from the indexed commit; cited paths or symbols no longer exist; dependency manifests, schemas, generators, or public interfaces changed; query results conflict with current search; parser coverage fell; or tests reference relationships absent from the index. Surface these signals with the result rather than hiding them.

How should failed searches be recorded?

Record the original query, timestamp, repository and commit, task intent, expected entity, filters used, result, and the source path eventually found. Classify the cause—terminology mismatch, missing parser, generated code, dynamic behavior, stale index, or user error—so maintainers can improve retrieval without storing private task reasoning.

When is a full rescan still necessary?

Run a full rescan after a large rebase, package reorganization, parser or schema upgrade, widespread code generation, major dependency migration, or unexplained coverage loss. It is also appropriate when targeted refreshes cannot reconcile the index with current source. Pin the new result to a commit before reuse.

Conclusion

Supacode agent context optimization is a repository-evidence workflow around isolated worktrees. Map the project once per meaningful revision, index dependencies and tests, retrieve a small task packet, and keep plans and terminal output local.

Measure time and tokens, but gate success on correct impact paths, relevant tests, and review outcomes. Supacode can make worktree commands and terminals repeatable. Fresh source citations, explicit coverage gaps, and verification make the context trustworthy.

Supacode shared context should be a team-designed, read-only repository knowledge layer that every worktree can query without sharing branch, terminal, plan, or write state. Bind that layer to a Git revision, cite source paths, keep task conclusions separate, and require agents to verify retrieved facts in their own checkout.

This is an architecture pattern, not a claim that Supacode includes shared memory or a code knowledge graph. Supacode’s official documentation describes real Git worktrees, managed local storage, per-worktree terminal state, and repository run, setup, and archive commands. Those features provide a useful shell for multiple agents. Your team must supply and govern the shared repository context.

The Multi-Worktree Context Problem

Each Supacode worktree gives an agent a separate branch and directory. That is valuable because tasks can modify different checkouts without mixing uncommitted files. Yet every agent still enters the same repository with limited knowledge.

Without a shared context layer, agents repeat the same discovery work:

• inventorying top-level modules and package manifests;
• searching for entry points, callers, schemas, and tests;
• deciding which documentation is current;
• inferring ownership from filenames or recent commits;
• producing local summaries that conflict with one another.

The resulting cost is not only token use. Parallel agents can reach incompatible conclusions about the same architecture. One may treat a generated client as editable source. Another may miss a feature flag. A third may base a change on an obsolete design note. Separate worktrees keep their files apart while their misunderstandings multiply.

The goal of Supacode shared context is therefore modest: reuse stable, reviewable repository facts so each task begins with a better evidence shortlist. It should not attempt to merge the agents’ reasoning or make every task see every other task’s terminal.

For the large-repository boundary behind this problem, see Supacode Large Codebase Worktrees.

What Should Be Shared vs Isolated

Share repository facts that can be tied to current source. Isolate state that is provisional, sensitive, or specific to one task.

Share read-only	Keep isolated by task
Module and package boundaries	Branch, HEAD, index, and uncommitted files
Symbol definitions and source citations	Agent plan and intermediate reasoning
Direct imports, calls, and schema references	Terminal tabs, output, and notifications
Test-to-feature and test-to-symbol links	Failed experiments and temporary patches
Approved architecture decisions	Task credentials and environment overrides
Owners and review boundaries	Provisional impact conclusions
Indexed commit and coverage gaps	Write permissions and integration authority

Git worktrees already separate selected Git state. Git documents HEAD and the index as per-worktree while most refs and repository data remain shared. Supacode adds a managed directory and terminal state for each worktree. That means the context design must not assume that “separate directory” equals complete security or environmental isolation.

External resources need explicit controls. Give worktrees different ports, database names, cache namespaces, disposable credentials, or cloud environments as the task requires. Do not place those secrets into shared repository context.

The general Share Repo Context Across Coding Agents guide expands this contract beyond a single worktree tool.

Build a Read-Only Repository Knowledge Layer

Build the layer from the repository revision agents will actually use. A minimal version can be a generated set of structured files; a richer version can be a queryable graph. The storage technology matters less than provenance and disciplined retrieval.

Start with high-value entities:

1. modules, packages, and public entry points;
2. symbols and their source locations;
3. direct imports, calls, implementations, and schema references;
4. tests linked to behaviors or source units;
5. generated files and their generators;
6. approved design documents, owners, and review rules.

Every result should include the indexed commit, source path, symbol or line anchor where practical, extraction method, and confidence or coverage note. Derived summaries should link back to evidence. If a parser fails or a language is unsupported, expose the gap instead of silently presenting an incomplete map.

Give ordinary agents query access, not mutation rights. Agents can submit proposed corrections through a review queue. This prevents a single mistaken task summary from rewriting what every other worktree sees.

Keep retrieval narrow. A task packet should contain the likely entry points, consumers, tests, and constraints—not a full graph export. Require the receiving agent to confirm critical relationships through source search, file reading, and tests in its current worktree. Static relationships can miss runtime registration, reflection, generated behavior, or external services.

Version Context With the Codebase

Context without a revision label is unsafe in an active repository. Record the exact Git commit used to generate it, plus generator version, timestamp, configuration, exclusions, and failed parses.

When a worktree starts, compare its base commit with the indexed commit. There are three reasonable outcomes:

• Exact match: use the context as a candidate map and verify important edges.
• Small known delta: refresh affected modules or mark potentially stale results.
• Material divergence: rebuild before relying on impact paths.

Define refresh triggers from repository behavior. Public-interface changes, dependency-manifest edits, schema migrations, code generation, package moves, renames, and test-layout changes usually deserve targeted refresh. Large rebases or parser upgrades may justify a full rebuild.

Versioning also makes disputes resolvable. If two agents report different callers, reviewers can ask which commit and extraction version each result describes. Without that provenance, “shared context” becomes another undocumented opinion.

The distinction in Git Worktree vs Knowledge Graph is useful here: the worktree identifies the current source view; the graph identifies the source view from which its relationships were derived.

Rollout Pattern for Multiple Agents

Roll out shared context gradually so missing coverage and unsafe assumptions appear before the workflow scales.

Begin with one repository and two low-risk tasks from the same base commit. Build only a module map, dependency slice, and related-test index. Ask both agents to cite retrieved evidence and record missing or incorrect relationships.

Next, add explicit task packets. Each packet should state:

• goal, non-goals, and permitted write paths;
• branch, base commit, and context revision;
• candidate entry points and impact paths;
• relevant tests and required verification;
• known unknowns and escalation owner;
• external resources assigned to the worktree.

Supacode repository commands can support the operational side. A reviewed setup script can prepare dependencies or launch the agent in the new worktree. A run command can start the standard dev or test process. An archive command can stop local services. These commands can live in supacode.json at the repository root or in Supacode’s local settings, according to the official documentation. They do not create or validate the knowledge layer.

Add metrics after the baseline is stable: time to first defensible plan, repeated searches, stale-context corrections, missed dependencies, irrelevant files opened, test-selection changes, and integration conflicts. Do not claim savings from token totals alone; a shorter run that misses a consumer is not an improvement.

Finally, separate approval roles. Repository-context maintainers approve shared fact changes. Task owners approve branch decisions. Code owners review affected contracts. An integrator evaluates combined behavior across worktrees.

The same separation makes handoffs predictable. A new worktree receives the approved evidence packet and its explicit task scope; it does not inherit unreviewed reasoning just because another terminal inspected the repository first. That boundary improves auditability when parallel changes later converge at the merge point.

FAQ

How often should shared context refresh?

Refresh on meaningful repository changes rather than a fixed clock alone. Dependency updates, public API edits, schemas, generated artifacts, package moves, and large rebases are strong triggers. Also run scheduled checks for repositories with steady activity. A query should always reveal its indexed commit so an agent can reject stale results.

What context should stay private to each task?

Keep the task plan, intermediate reasoning, terminal transcript, failed experiments, unreviewed conclusions, credentials, environment overrides, and uncommitted diff private to the task. Share an outcome only after review turns it into an approved repository fact, decision record, or source change.

Who approves shared knowledge changes?

A named repository-context owner should approve changes, ideally with the relevant code owner for architecture or public-contract facts. Automated updates may publish low-risk structural edges only when validation and rollback are defined. Agent reports should enter a review queue rather than changing shared context directly.

Conclusion

Supacode shared context across worktrees works best as a neutral evidence service around Supacode, not as shared agent memory inside it. Supacode isolates Git workspaces and preserves terminal workflows. A separate, revision-bound knowledge layer helps agents locate the same repository facts.

Share modules, relationships, tests, approved decisions, provenance, and coverage gaps. Isolate branch state, plans, terminal output, credentials, and provisional conclusions. Then require every worktree to verify important claims against current source and tests before editing or integration.

A Supacode large-codebase workflow can isolate each coding task in a real Git worktree, but the worktree does not explain architecture, call paths, design intent, or cross-module dependencies. Give every agent a narrow branch and directory plus a revision-bound repository evidence packet, then verify its plan against current source and tests.

This guidance reflects Supacode’s documented boundary as of July 23, 2026. Supacode v0.10.6 is a macOS worktree command center with per-worktree terminal state and reusable repository commands. The reviewed documentation does not present Supacode as a shared-memory system, code index, or knowledge graph. Those capabilities must come from your repository process or a separate context layer.

What Supacode Worktrees Solve

Supacode gives each task a concrete Git workspace. Its documentation says a new worktree is a real Git worktree backed by its own branch and directory, created under ~/.supacode/repos/<repository-name>/. Supacode selects the worktree, opens terminal state associated with it, and can run a configured setup script once.

For large repositories, that operating model solves several practical problems:

• one agent’s uncommitted files do not appear in another agent’s working directory;
• developers can keep multiple branches checked out without switching the main checkout;
• each worktree can retain its own terminal tabs, splits, notifications, and focused surface;
• setup commands can install dependencies, generate local artifacts, or launch an agent;
• run commands can repeat common development or test actions;
• archive commands can stop local infrastructure before the worktree is put away.

These controls reduce accidental interference and make task state easier to inspect. They also create a useful review boundary: branch, diff, terminal, and tests can be associated with one worktree.

Git itself still shares important repository data across linked worktrees. Most refs are shared, even though HEAD, the index, and other selected files are per-worktree. Services outside Git—ports, databases, caches, cloud environments, credentials, and queues—need their own isolation. A new directory is not a new infrastructure account.

The comparison in Git Worktree vs Knowledge Graph explains this division between write isolation and relationship-aware repository context.

Why Isolation Is Not Repository Understanding

An isolated checkout answers “where may this agent work?” It does not answer “which parts of the system govern this change?”

In a large codebase, behavior may span a public API, implementation package, generated client, database schema, feature flag, deployment configuration, and integration tests. An agent entering a clean worktree still has to locate those pieces. If it starts with broad recursive searches, it may spend tokens rediscovering the same layout another agent already mapped. Worse, it may stop after finding the first plausible match.

Repository understanding requires evidence about relationships and authority:

• which module owns the behavior;
• which callers and consumers depend on its current contract;
• which files are generated rather than directly edited;
• which design record explains an unusual constraint;
• which tests exercise the behavior at the correct boundary;
• which facts are observed and which remain hypotheses.

Supacode’s per-worktree terminal helps an agent run searches, tools, and tests in the right directory. Its repository commands make repeatable actions convenient. Neither feature establishes that the selected files are complete or that an architectural conclusion is correct.

The general Agent Swarm Codebase Context pattern is relevant even if you run only a few agents: shared evidence needs a revision, task packets need boundaries, and integration needs an owner.

Large Codebase Failure Modes

Parallel worktrees amplify existing repository weaknesses. Watch for failure modes that look like progress inside one branch but fail at integration.

False locality happens when the agent edits the closest file and misses an indirect caller, configuration gate, or generated artifact. The patch passes a narrow unit test but violates a wider contract.

Duplicate discovery happens when every agent scans the same top-level directories, dependency manifests, and test tree. Isolation makes the scans independent; it does not make them efficient.

Logical overlap occurs when agents modify different files that implement the same public behavior. Git may show no textual conflict, yet the combined changes disagree.

Base drift appears when long-running worktrees begin from different commits. A context packet built for one base can mislead an agent working from another.

Shared-resource collision appears when isolated directories point at the same database, development port, cache namespace, or cloud environment.

Unreviewed summaries become a problem when one agent’s inference is copied into shared context as fact. The next agent may treat a tentative conclusion as repository truth.

Mitigation starts before the first agent launches. Pin the base commit, identify public-contract ownership, enumerate external resources, and define the expected verification surface. Then make uncertainty visible rather than encouraging an agent to complete a confident narrative.

Where Code Knowledge Graphs Fit

A code knowledge graph or structured repository map fits between task assignment and source inspection. It can return candidate modules, symbols, dependency edges, tests, documents, and owners for a task. This makes repository context reusable without merging each agent’s branch or terminal state.

The graph should be read-only for ordinary task agents and labeled with the commit it represents. It should also expose coverage limits: unsupported languages, failed parses, excluded generated code, or edges inferred from configuration. Retrieval is a starting point, not proof.

A useful query packet might include:

1. the task and permitted write paths;
2. the indexed commit and current worktree commit;
3. entry points and likely implementation symbols;
4. direct callers and relevant transitive consumers;
5. related tests, schemas, configuration, and documents;
6. missing evidence that requires manual search.

The agent then confirms each important relationship in its own worktree. Dynamic registrations, reflection, runtime flags, and external systems often require tests or operational evidence beyond a static graph.

For teams designing this layer specifically around Supacode worktrees, Supacode Shared Context Across Worktrees provides a release-order companion architecture.

Practical Setup Pattern

Use a setup pattern that separates Git state, repository facts, and task decisions.

First, add the repository to Supacode and verify the actual Git binary, base branch, and managed worktree location. Supacode currently documents macOS 26.0 or newer as a requirement. Pin the app release during a controlled rollout; v0.10.6 was the latest first-party GitHub release when this article was verified.

Second, define repository commands conservatively. A setup script may install dependencies, generate required local artifacts, or start the chosen coding agent. A run command may launch the standard test watcher or development server. An archive script may stop task-local infrastructure. Because these commands execute in worktree terminal context, keep them reviewable and avoid embedding secrets.

Third, build a read-only context artifact for an approved base commit. It may be a module map, symbol index, dependency graph, test map, or a combination. Store provenance and generation failures. Do not store task-terminal output or unreviewed conclusions in the repository-facts layer.

Fourth, assign each task a branch, write scope, owner, service namespace, and evidence packet. Require a plan before edits and focused tests before broad tests. If two packets touch the same public contract, sequence the tasks or give one integrator authority.

Fifth, integrate deliberately. Update the branch from the approved base, rerun impact queries when the diff changes a public boundary, execute combined tests, and review the final diff independently of each worktree’s local success.

FAQ

Who should maintain shared repo context?

Assign a named team or role that already owns developer infrastructure, architecture documentation, or code intelligence. Task agents may report missing or stale evidence, but reviewed automation or responsible maintainers should approve changes to shared repository facts. Ownership should include refresh policy, access control, coverage monitoring, and incident correction.

What should be verified before running parallel agents?

Verify the base commit, worktree branch, write scope, shared-contract ownership, context revision, setup command, test command, ports, data stores, credentials, generated files, and integration order. Confirm that every agent can distinguish observed source evidence from inferred relationships and knows when to escalate uncertainty.

When should teams avoid parallel worktrees?

Avoid parallel execution when tasks change the same public contract, depend on an unsettled architecture decision, require one scarce mutable environment, or cannot be tested independently. Sequential work is also safer when the context map is materially stale or the integration owner cannot review combined behavior.

Conclusion

Supacode large-codebase worktrees are an effective isolation surface, not an automatic understanding layer. They organize branches, directories, terminals, and repeatable commands so multiple tasks can proceed with clearer operational boundaries.

Add repository understanding separately. Bind a read-only context map to the base commit, keep task reasoning private until reviewed, verify relationships in current source, and test the combined result. That layered workflow preserves what worktrees do well without asking them to solve architecture discovery.

Qoder Subagents do not automatically share the main session's full context or one another's intermediate work. Give each role an explicit evidence packet containing the repository revision, task boundary, relevant paths, architecture constraints, approved findings, expected output, and verification commands. Treat the final handoff as a reviewable artifact, not as shared memory.

This design lets planning, implementation, testing, and review agents use consistent repository facts without loading the same raw conversation into every context. It also preserves isolation: each Subagent receives only what it needs and operates within its own tool, permission, runtime, and workspace boundaries.

Why Subagents Rebuild Context

Qoder CLI defines a Subagent as a specialized agent with its own conversation context, system prompt, tool registry, transcript, and compression flow. Its intermediate search and reasoning do not directly enter the main conversation. The main session coordinates the task and receives the Subagent's result.

Isolation keeps exploration details from crowding the coordinator's context, but it creates an information-transfer problem. A planner may discover that an API handler is generated, yet an implementation agent will not know that fact unless the handoff says so. A tester may find an undocumented consumer, while a reviewer sees only the patch unless that evidence is carried forward.

The same problem appears when a Subagent starts from a broad instruction such as “review this migration.” It may have to rediscover:

• the repository commit and working-tree state;
• which package owns the behavior;
• the approved architecture boundary;
• callers, schemas, generated outputs, and external consumers;
• commands that produce a representative test result;
• decisions already made and questions that remain open.

Repeated discovery consumes tool calls and increases inconsistency. Two agents can inspect different files, trust different documents, and produce individually plausible but incompatible recommendations.

Qoder's optional auto-memory is not a substitute for a handoff. It is enabled separately, stores selected local Markdown facts, and can become stale. Project AGENTS.md and rules provide durable guidance, but they do not contain every task finding. A reliable Qoder subagent context workflow therefore distinguishes stable repository knowledge from temporary evidence and role-specific reasoning.

Define Shared Repository Knowledge

Shared repository knowledge should be a small, versioned contract that every role can verify.

A useful evidence packet contains:

Field	What to record	Why it matters
Revision	Commit, branch, and relevant uncommitted-state note	Prevents agents from reasoning over different snapshots
Objective	Requested outcome and explicit non-goals	Limits scope expansion
Relevant paths	Entry points, likely owners, tests, and documents	Reduces duplicate scanning without hiding source
Architecture constraints	Approved boundaries and decision records	Preserves design intent
Relationship evidence	Callers, imports, schemas, generators, and consumers	Supports impact analysis
Permissions	Allowed tools, paths, commands, and network access	Keeps each role inside its authority
Verification	Focused tests, broader checks, and acceptance conditions	Gives every role the same definition of done
Open questions	Uncertain, stale, dynamic, or cross-repository facts	Stops inference from becoming a silent decision

Store durable commands, conventions, ownership, and review requirements in maintained project memory. Qoder CLI supports project AGENTS.md, machine-local AGENTS.local.md, and focused .qoder/rules files. Store the active task packet separately so temporary paths, logs, and hypotheses do not become permanent instructions.

When relationships are expensive to rediscover, a separately maintained repository index or knowledge graph can supply a shared query layer. The graph is external evidence, not automatic Qoder AI agent memory. Every important edge should identify its source and indexed revision, and the receiving agent should inspect current code before acting.

The broader shared-context workflow for coding agents explains how to keep common evidence portable across tools. The Qoder CLI context-engineering guide owns the underlying memory and document layers.

Split Planning, Implementation, Testing, and Review Context

Give every Qoder agent one responsibility and the least context needed to fulfill it.

Role	Receives	Produces	Recommended boundary
Planning	Objective, revision, architecture records, relationship leads	Impact map, candidate files, risks, test plan, unresolved questions	Read and search tools; no source edits
Implementation	Approved plan, exact paths, constraints, acceptance conditions	Focused patch, changed-path list, deviations, local validation	Edit only approved areas; isolated worktree for parallel edits
Testing	Patch or commit, impact map, test commands, known risks	Reproducible results, uncovered paths, failures, environment notes	Read plus approved test commands; no product-code changes by default
Review	Original objective, approved plan, diff, test evidence, open risks	Findings, evidence links, approval or required revisions	Read-only source and diff inspection

Qoder CLI supports project-level Subagent definitions under .qoder/agents/*.md and user definitions under ~/.qoder/agents/*.md. The current /agents interface and qodercli agents list show what the installed version discovered. Built-in roles can vary by version and enabled features, so a workflow should refer to verified role names instead of assuming a universal list.

The role prompt should say what information the Subagent receives and what its response must contain. For example, an implementation handoff should require changed files, decisions made, assumptions, commands run, failures, and any departure from the approved plan. A final answer that says only “done” is not a usable context transfer.

Do not pass the planner's private reasoning as authority. Pass its cited findings, unresolved questions, and approved plan. This keeps downstream work auditable and gives another agent enough information to challenge an incorrect conclusion.

Reduce Duplicate Scans and Conflicting Changes

The coordinator should perform one evidence preflight, then distribute role-specific views of the same packet.

Start by locking the revision, objective, ownership, and acceptance criteria. Ask a read-only planning role to locate evidence and mark uncertainty. After approval, freeze a plan identifier or digest so implementation and review can confirm they are evaluating the same scope.

For parallel work, divide by non-overlapping ownership rather than by arbitrary file count. Qoder Subagents can use isolation: worktree, which gives an editing role a separate Git worktree. Worktree isolation reduces accidental file collisions; it does not make two architectural decisions compatible. Assign one integration owner to order changes, resolve overlapping contracts, and decide which result becomes canonical.

A compact handoff log should record:

1. task and plan identifiers;
2. source and output revisions;
3. agent role and effective tool boundary;
4. evidence inspected and key findings;
5. files changed or tests executed;
6. assumptions, failures, and unresolved questions;
7. next owner and required decision.

Reuse verified relationship queries rather than copying large tool transcripts. A graph result can identify a dependency path, while the packet records the path, provenance, and files checked. The next agent can validate the claim without repeating the entire scan.

For a product-neutral design across many parallel workers, see agent swarm codebase context. The Qoder-specific workflow remains smaller: use discovered Subagents, explicit packets, scoped tools, and one accountable coordinator.

Permission and Drift Risks

Shared evidence reduces repeated work, but it can also spread a wrong assumption faster.

Use these safeguards:

• Pin the snapshot. Put the repository revision and packet timestamp in every handoff.
• Mark authority. Separate current source, approved decisions, generated graph findings, test output, and model inference.
• Limit tools. Configure each Subagent with the tools required for its role; do not give a reviewer write access by habit.
• Check permission inheritance. If a Subagent omits its permission mode, Qoder documents that it inherits the current parent mode. Inspect the effective boundary rather than trusting a prompt label.
• Protect parallel edits. Use worktrees for independent implementation tasks and inspect every returned diff before integration.
• Expire task context. Close or refresh packets when the source revision, architecture, ownership, or acceptance criteria change.
• Re-run evidence. Test output and graph paths should be reproducible from the recorded revision.
• Escalate decisions. Security, data, public contracts, deployment, and cross-team boundaries need the responsible human owner.

Qoder permissions control whether tools can act; they do not prove the correctness of a plan or patch. Likewise, an AGENTS.md instruction is context rather than enforcement. Put mandatory path, command, and tool restrictions in permission rules or Hooks, then verify behavior with tests and review.

Avoid putting secrets, customer data, credentials, or unrelated private material into a shared packet. The coordinator should also exclude speculative reasoning that downstream agents could mistake for an approved fact.

FAQ

What should subagents not share?

Do not share secrets, credentials, customer data, unrestricted environment dumps, private reasoning, unrelated source, or stale conclusions. Keep role-specific scratch output isolated. Share only evidence and decisions needed for the next role, with provenance, revision, authority, and explicit uncertainty.

How should teams log handoffs?

Use a structured record tied to the task and repository revision. Include the role, effective tools and permissions, evidence inspected, findings, changed files, commands and results, assumptions, deviations, open risks, and next owner. Store durable decisions in approved project documentation rather than leaving them only in a conversation transcript.

When should one agent own a decision?

Use one decision owner when parallel tasks touch the same public contract, schema, package boundary, migration order, generated artifact, or deployment sequence. Specialized agents can provide evidence, but the coordinator or responsible human owner should select the canonical plan and integration order.

Conclusion

Qoder Subagents provide useful context isolation, configurable tools and permissions, parallel execution, and optional worktree separation. Those capabilities help divide repository work, but they do not create automatic shared repository knowledge.

Build Qoder subagent context around explicit, revision-locked evidence packets. Give planning, implementation, testing, and review roles different inputs and authority. Log every handoff, refresh stale evidence, inspect worktree diffs, and keep one owner accountable for decisions that cross boundaries.

The decision rule is straightforward: share verified facts and approved constraints, not entire transcripts. If the next role cannot reproduce a claim from the recorded source, it should treat that claim as unresolved.