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:
- modules, packages, and public entry points;
- symbols and their source locations;
- direct imports, calls, implementations, and schema references;
- tests linked to behaviors or source units;
- generated files and their generators;
- 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.
Leave a Reply