CodeWhale Fleet Context Sharing

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.