Supacode Agent Context Optimization Guide

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.