CodeWhale Context Optimization Guide

CodeWhale context optimization should reduce repeated repository discovery, not hide evidence from the agent. Build a revision-bound module and dependency map, link tests and entry points, retrieve a small packet for each task, and measure search and startup behavior against a baseline. Keep current source and verification available whenever cached context is stale or incomplete.

Codewhale v0.9.0 provides model and provider routing, saved sessions, compaction, task-scoped Fleet inputs, and subagents. It does not document a native repository index, code graph, or Fleet-wide shared repository memory. In this guide, indexing is an external Graphify-style evidence layer connected to Codewhale’s documented tools and context inputs.

Why CodeWhale Agents Re-Read Repos

Repeated reading is often a rational response to missing or untrusted context. A new worker must discover where the subsystem lives, which symbols matter, what calls them, and which tests establish behavior. If no reusable evidence identifies those paths, searching again is safer than trusting an old summary.

Codewhale’s subagent behavior makes the boundary explicit. The agent path starts fresh by default with the role prompt and assigned task. Context is carried only when fork_context: true is requested. Fresh sessions are appropriate for independent exploration, but several fresh agents can repeat the same rg, file-open, and dependency-tracing steps.

Provider switching creates a related cost. Codewhale can select models and providers through a common runtime, and Fleet profiles can pin a route. The incoming model can receive saved transcript text, configured instructions, or an explicit task packet. It does not inherit another provider’s hidden reasoning. Rebuilding repository understanding from current evidence may therefore dominate startup.

Saved sessions and /compact help with transcript continuity. The user guide describes compaction as a way to recover context budget by summarizing long history. That is useful inside a session, but a compacted transcript is not an automatically refreshed architecture index.

Optimization begins by classifying repeated work:

• necessary rereads validate changed or high-risk source;
• avoidable discovery repeatedly locates stable module boundaries and entry points;
• stale-context recovery corrects an old map or summary;
• provider-specific interpretation compares how models reason over the same evidence.

The target is the second category. Removing the first would make the workflow faster but less trustworthy.

Build a Module and Dependency Map

Generate a small, queryable repository map from a pinned commit. Start with information that is expensive to rediscover and likely to be useful across tasks:

• packages, services, libraries, generated areas, and their owners;
• public and internal entry points;
• import, call, registration, schema, event, and configuration relationships;
• build and deployment boundaries;
• architecture records linked to affected code;
• cross-repository contracts and the location of their source of truth.

Every record should contain provenance. A parsed import can point to a file and line. A generated-client edge should name its generator. An inferred runtime relationship should carry lower confidence and an explanation. The complete map should identify its repository revision and generation method.

Do not load the whole graph into every prompt. Query it by task. For “change retry behavior in the queue consumer,” retrieve the consumer, its configuration, retry scheduler, error types, telemetry path, owners, and tests. Let Codewhale open those current files and expand only when evidence indicates another dependency.

Codewhale’s v0.9.0 configuration also documents an optional cache-maximal working-set mode that materializes the full current contents of top active files to stabilize provider prefix caching. That is a prompt-cache optimization for selected files, not a repository map. Use it only after evidence selection; it cannot tell the task which files were missed.

The CodeWhale Large Codebase Context guide explains the model-independent evidence contract behind this map.

Index Related Tests and Entry Points

A module map saves search time only if it leads to behavior-relevant verification. Link each important entry point and relationship path to the tests that exercise it.

Useful test-index fields include:

Field	Purpose
test path and command	makes verification reproducible
behavior or contract covered	prevents “nearby test” selection
environment and fixtures	exposes database, network, or service dependencies
source relationship	explains why the test belongs to the task
last successful revision	signals possible drift without promising current success
owner and known limitations	routes failures and prevents false confidence

Entry points require the same care. Record CLI commands, server routes, background jobs, plugin registrations, migrations, and generated interfaces. A symbol search may find a function but miss the configuration that activates it.

Fleet task specs can carry input_files, additional context, required files, and expected artifacts. Use those fields to give a worker the selected source and test paths, not an unbounded request to “understand the repository.” The worker’s receipt should return the commands and artifact evidence needed to verify the result.

Rebuild or incrementally update the index when source changes affect mapped relationships. A checksum or commit match is necessary, but high-impact work should still read the relevant current files.

Retrieve Context by Task

The smallest useful context packet answers seven questions:

1. What behavior must change?
2. Which revision and workspace are authoritative?
3. Which modules and entry points are in scope?
4. Which dependency paths justify that scope?
5. Which rules and decisions apply?
6. Which tests and reviewers verify the result?
7. Which relationships remain uncertain?

Keep temporary state outside the shared map. A worker’s plan, tool output, debugging hypothesis, and provider-specific conclusion belong to its task record. If a finding should become shared knowledge, require source locations, revision, derivation method, and review.

Codewhale’s opt-in memory is not the place for repository indexing. Its v0.9.0 memory documentation calls the file user-scoped and intended for durable personal preferences across repositories and sessions. Repo conventions belong in project instructions; structural facts belong in a versioned evidence layer.

For Fleet workflows, the related CodeWhale Fleet Context Sharing guide explains how read-only repo evidence and isolated worker state fit together.

Validate Savings Without Hiding Risk

Measure optimization with controlled, repeatable tasks. Do not promise a fixed token reduction: provider token accounting, repository shape, task complexity, caching, and model behavior differ.

Choose several representative tasks and run each with and without the external context layer at the same revision. Record:

• time until the agent proposes a source-linked plan;
• search and file-read actions before the first edit;
• provider-reported input and output tokens when available;
• repeated reads of unchanged files;
• number of graph expansions or fallback full-text searches;
• missed dependencies found during review;
• relevant test selection and pass/fail results;
• reviewer corrections and unsupported claims.

Savings are meaningful only when quality holds. A task that uses fewer tokens but misses a generated consumer is not optimized. Add guardrails: stale context triggers a targeted refresh; disagreement with current source invalidates the cached edge; security, migration, public API, and incident tasks default to broader verification.

Compare medians across several tasks rather than promoting one successful run. Keep the provider, model, revision, task brief, permissions, and verification commands stable so the comparison measures context retrieval instead of an unrelated route change.

FAQ

When should CodeWhale ignore cached context?

Ignore or bypass it when the commit differs, mapped files changed, generation failed, a live source check contradicts an edge, or the task touches dynamic registration, generated code, migrations, security controls, incident response, or external contracts not represented in the map. A provider change alone does not invalidate source-derived facts, but it does require model-specific conclusions to be reconsidered.

How should provider-specific notes be labeled?

Store the provider, model, date, task, revision, and evidence used. Mark the note as observation, hypothesis, or measured result. Do not promote it into shared repository knowledge unless current source or repeatable tests support it. Keep pricing, context-window, and token-accounting notes tied to the concrete route because those attributes can vary by provider.

What evidence proves optimization helped?

Use a matched baseline showing fewer redundant searches or reads, lower startup time, or lower provider-reported token use while preserving dependency recall, test selection, reviewer acceptance, and task correctness. Report the task set and measurement method. One fast run or a smaller prompt does not prove safer repository understanding.

Conclusion

Codewhale context optimization works best when it removes repeated discovery while retaining current evidence. Build an external revision-bound module, dependency, entry-point, and test index. Retrieve only the slice a task needs, keep worker state separate, and fall back to source inspection whenever freshness or coverage is uncertain.

Measure search actions, time, tokens, dependency recall, test quality, and reviewer corrections together. If a smaller context packet makes a risk harder to see, it is compression—not optimization.