|
8 | 8 |
|
9 | 9 | This file provides guidance to models when working with code in this repository. |
10 | 10 |
|
| 11 | +## Code Comments: Document the "Why", Briefly |
| 12 | + |
| 13 | +When writing or modifying code driven by a design doc or non-obvious constraint, add a comment explaining **why** the code behaves the way it does. |
| 14 | + |
| 15 | +Keep comments short — one or two lines. Capture only the non-obvious reason (safety constraint, compatibility shim, design-doc rule). Don't restate what the code does, narrate the mechanism, cite design-doc sections verbatim, or explain adjacent API choices unless they're the point. |
| 16 | + |
| 17 | +## File and Module Naming |
| 18 | + |
| 19 | +Never use vague names like `helpers`, `utils`, `common`, `misc`, or `shared-stuff` for files, folders, or modules. They carry zero information and tend to become dumping grounds. Name files after what they *actually* contain — prefer the concrete domain concept (e.g. `tab-group-state.ts`, `terminal-orphan-cleanup.ts`) over the generic role (`tabs-helpers.ts`, `terminal-utils.ts`). If you find yourself reaching for `helpers`, the file probably has more than one responsibility and should be split, or there's a better name hiding in the code that describes what the functions operate on. |
| 20 | + |
11 | 21 | ## GOLDEN RULE: Docs & AGENTS.md |
12 | 22 |
|
13 | 23 | Update corresponding Docs in [CrewCode Docs](/docs/), and [AGENTS.md](/AGENTS.md/) when major changes were made and or every time i add a feature. Create or update docs file for it |
14 | 24 |
|
| 25 | +## Agent Notes |
| 26 | + |
| 27 | +The context usage meter must prefer the active provider's reported full context |
| 28 | +window over model-catalog metadata and static limits. Codex app-server usage |
| 29 | +reports `modelContextWindow` as an effective prompt budget; when a known full |
| 30 | +model window is larger, show that as the meter denominator and label the Codex |
| 31 | +prompt budget separately. Claude SDK `getContextUsage()` reports the active |
| 32 | +window. Claude occupancy must come from active SDK context categories, not |
| 33 | +cumulative result billing or cache-read counts. Keep static window values as |
| 34 | +fallbacks only. Read Claude context during the active query; if control fails, |
| 35 | +use only the latest individual assistant request's context counts, never |
| 36 | +aggregate result usage. Use SDK category `kind` and full detail for the |
| 37 | +measured Claude meter; summary detail is approximate. See |
| 38 | +`docs/context-usage-meter.md`. |
| 39 | + |
| 40 | +The context popover stays compact. Its Token logs action opens the full |
| 41 | +provider breakdown in a scrollable right sidebar, including for crew chats; |
| 42 | +keep the row data out of the small popover. See `docs/context-usage-meter.md`. |
| 43 | +Codex, OpenCode, Grok, and CrewCoder token logs may show only observed request, |
| 44 | +turn, or session counters. Label them separately from Claude's context categories and never |
| 45 | +present overlapping cache or cumulative counts as additive occupancy. Keep |
| 46 | +Token logs directly reachable when counters exist but no context percentage is |
| 47 | +available; show unknown occupancy instead of a fabricated zero. |
| 48 | + |
| 49 | +Confirmed native auto-compaction must invalidate old context occupancy in the |
| 50 | +bridge, persisted session snapshot, and latest visible usage strip. Refill only |
| 51 | +from a new provider reading; never replay pre-compaction usage at turn end. |
| 52 | +Claude `compact_boundary`, Codex app-server `contextCompaction`, CrewCoder's |
| 53 | +namespaced update, and OpenCode's active-session `session.compacted` are native |
| 54 | +signals. Allow high-water-to-large-drop inference only for providers with an |
| 55 | +observed absolute context reading. See `docs/context-usage-meter.md`. |
| 56 | + |
| 57 | +Plugin panels receive a fixed allowlist of semantic theme tokens from the host through `crewcode:theme` messages. Keep the iframe boundary intact, send updated tokens after theme changes, and document token changes in `docs/plugins.md`. |
| 58 | + |
15 | 59 | Git Workspace changed-file rows support stage/unstage controls and a context |
16 | 60 | menu for stage, stage-all, unstage, and explicitly confirmed discard actions. |
17 | 61 |
|
@@ -66,6 +110,16 @@ reconciliation, startup, or session switching. Preserve global delivery for |
66 | 110 | newly appended live errors and active-scope delivery for live agent-exit |
67 | 111 | warnings. See `docs/notifications.md`. |
68 | 112 |
|
| 113 | +Provider questions use the shared `AgentRequestCard` overlay: option buttons for |
| 114 | +choice questions (short Yes/No sets on one row), toggles for multi-select, and an |
| 115 | +input plus send-reply button whenever free text is allowed. Map only structured |
| 116 | +provider requests (Claude `AskUserQuestion` with its implicit "Other", Codex |
| 117 | +`item/tool/requestUserInput`, OpenCode `question`, Pi extension UI, CrewCoder |
| 118 | +clarify reply box); never infer questions from assistant prose. Cancel/empty |
| 119 | +answers are explicit failures, never empty answers, and provider-side resolution |
| 120 | +withdraws the card through the `RequestUserFn` abort signal. See |
| 121 | +`docs/agent-activity-overlay.md`. |
| 122 | + |
69 | 123 | Thinking-log headers use the shared outlined thought-bubble icon; keep the |
70 | 124 | streaming shimmer and separate disclosure chevron behavior intact. |
71 | 125 | Turn Work Log headers use the shared outlined work-log icon alongside the |
@@ -315,8 +369,12 @@ optional capability probe into a throwing function. See |
315 | 369 |
|
316 | 370 | Continuity catalogue hydration must merge desktop-only session/tab identities into a |
317 | 371 | Brain catalogue without replacing genuine identities the Brain already owns, once |
318 | | -desktop catalogue authority exists. Until that marker is present, or while the Brain |
319 | | -still contains transcript-derived recovered rows, Electron reseeds the exact desktop |
| 372 | +desktop catalogue authority exists. An explicit Background Brain enable is a new |
| 373 | +owner-observed handoff: before the enable-triggered reload, seed the exact foreground |
| 374 | +desktop chat/session catalogue even when an older authority marker exists. Reconcile |
| 375 | +the current desktop workspace registry first for matching ids/paths and preserve |
| 376 | +genuine Brain-only/browser-created workspaces. Until that marker is present, or while |
| 377 | +the Brain still contains transcript-derived recovered rows, Electron reseeds the exact desktop |
320 | 378 | names, active selection, tab-key order, and per-tab session order; drop unmatched |
321 | 379 | recovered navigation rows while preserving transcript shards, and retain genuine |
322 | 380 | web-created sessions. If catalogue records are missing, recover only |
@@ -503,3 +561,19 @@ CrewCoder Codex turn must not pass that parent turn's private `CODEX_HOME`, |
503 | 561 | thread identity, or managed-launch metadata into the standalone usage probe. |
504 | 562 | Legacy CrewCoder sessions with an unprefixed `gpt-*` model use the Codex usage |
505 | 563 | bucket; current namespaced `provider:model` selections remain authoritative. |
| 564 | +CrewCoder ACP context usage treats `lastInputTokens` as an authoritative live |
| 565 | +measurement, including decreases after native provider compaction. Scope every |
| 566 | +usage snapshot to the ACP prompt that produced it; never replay a prior turn's |
| 567 | +percentage when a later prompt fails or omits usage metadata. |
| 568 | +Provider-native compaction must reach the existing compaction meter. Prefer |
| 569 | +Codex app-server `contextCompaction`/`thread/compacted`, Claude |
| 570 | +`compact_boundary`, and CrewCoder `_crewcoder/compaction_update` boundaries; |
| 571 | +use a verified high-water-to-large-drop usage fallback only when no native |
| 572 | +boundary was observed for that turn, and never render both for one compaction. |
| 573 | +CrewCoder's nested Codex app-server must receive CrewCoder's resolved context |
| 574 | +window and computed auto-compaction limit as process-scoped configuration. Keep |
| 575 | +all built-in GPT-5.6 Sol/Terra/Luna variants at 1.05M with the normal 60% |
| 576 | +boundary (630k); never let app-server's smaller default silently compact first. |
| 577 | +CrewCoder must declare a positive context window for every shipped built-in |
| 578 | +model, disable Claude SDK-native auto-compaction, and treat an ACP provider's |
| 579 | +runtime context-window report as authoritative for threshold recalculation. |
0 commit comments