Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
feat(context): budget the bundle in tokens, not characters
KageBinary7bc83d2aa3f9
diff --git a/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts b/ix-cli/src/cli/__tests__/context-evidence-locations.test.tsindex 97ab0685..503bac22 100644--- a/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts+++ b/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts@@ -57,7 +57,7 @@ function bundle(opts: {metadata: { query: "", seedEntities: [], hopsExpanded: 1, asOfRev: 1 },} as never,provenance: opts.provenance ?? {},- budgets: { maxEntities: opts.maxEntities ?? 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },+ budgets: { maxEntities: opts.maxEntities ?? 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },isStale: () => false,});}@@ -131,7 +131,7 @@ describe("ix context evidence says where things are", () => {metadata: { query: "", seedEntities: [], hopsExpanded: 1, asOfRev: 1 },} as never,provenance: {},- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },isStale: () => false,});diff --git a/ix-cli/src/cli/__tests__/context-investigation.test.ts b/ix-cli/src/cli/__tests__/context-investigation.test.tsindex 7a3f60e4..8fbf9c40 100644--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts@@ -208,7 +208,7 @@ function bundleWith(claims: ScoredClaim[], stale = false) {provenance: { sourceType: "source", extractor: "tree-sitter", observedAt: "2026-01-01T00:00:00Z" },asOfRev: undefined,depth: undefined,- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },});}@@ -405,7 +405,7 @@ describe("ix context investigation state", () => {provenance: { sourceType: "source", extractor: "tree-sitter", observedAt: "2026-01-01T00:00:00Z" },asOfRev: undefined,depth: undefined,- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },});const diff = diffInvestigations(stored, fresh);@@ -487,14 +487,14 @@ describe("ix context investigation state", () => {// fresh bundle in front of it had been built with 50/100/25/12000 -- a// budget neither side of the comparison had used together.const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);- saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 };+ saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxTokens: 1500, maxChars: 12000 };saveInvestigation("widget-check", saved);const stored = loadInvestigation("widget-check")!;const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);- expect(fresh.budgets).toEqual({ maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 });+ expect(fresh.budgets).toEqual({ maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 });const baselineDiff = diffInvestigations(stored, fresh);- expect(baselineDiff.budgets.saved).toEqual({ maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 });+ expect(baselineDiff.budgets.saved).toEqual({ maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxTokens: 1500, maxChars: 12000 });expect(baselineDiff.budgets.requested).toBeUndefined();expect(baselineDiff.budgets.effective).toEqual(fresh.budgets);expect(baselineDiff.budgets.requestedApplied).toBe(false);@@ -545,7 +545,7 @@ describe("ix context investigation state", () => {// future refactor flattens renderInvestigationDiff back to "entities/-// +", the budget block disappears and the silent ignore comes back.const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);- saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 };+ saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxTokens: 1500, maxChars: 12000 };saveInvestigation("widget-check", saved);const stored = loadInvestigation("widget-check")!;const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);@@ -583,9 +583,9 @@ describe("ix context investigation state", () => {// Records, not the prose block with the colons moved. `scope=requested`// carries `applied=` so the precedence rule — saved budgets govern// --diff — is a field an agent can test rather than a sentence to read.- expect(llm.lines).toContain("budgets scope=saved entities=5 relationships=1 evidence=2 chars=12000");+ expect(llm.lines).toContain("budgets scope=saved entities=5 relationships=1 evidence=2 tokens=1500 chars=12000");expect(llm.lines).toContain("budgets scope=requested evidence=25 applied=false");- expect(llm.lines).toContain("budgets scope=effective entities=50 relationships=100 evidence=25 chars=12000");+ expect(llm.lines).toContain("budgets scope=effective entities=50 relationships=100 evidence=25 tokens=1500 chars=12000");// And none of the prose survives into the record stream.expect(llm.lines.some((l) => l.includes(":") && l.startsWith(" "))).toBe(false);@@ -686,7 +686,7 @@ describe("ix context investigation state", () => {provenance: { sourceType: "source", extractor: "tree-sitter", observedAt: "2026-01-01T00:00:00Z" },asOfRev: undefined,depth: undefined,- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },});const lines = captureLog(() => renderInvestigationDiff(stored, fresh, "llm"));diff --git a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts b/ix-cli/src/cli/__tests__/context-mode-conflict.test.tsindex 9acfaa71..3b26540d 100644--- a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts+++ b/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts@@ -242,7 +242,7 @@ describe("mode-flag coverage does not drift from the command", () => {*/const CONTEXT_BUILD_FLAGS = ["kind", "path", "pick", "depth", "asOfRev",- "maxEntities", "maxRelationships", "maxEvidence", "maxChars",+ "maxEntities", "maxRelationships", "maxEvidence", "maxTokens", "maxChars",];/** Meaningful to every mode, so in neither group. */const CONTEXT_UNIVERSAL_FLAGS = ["format"];diff --git a/ix-cli/src/cli/__tests__/context-pick-validation.test.ts b/ix-cli/src/cli/__tests__/context-pick-validation.test.tsindex 9741e1ec..96ea368f 100644--- a/ix-cli/src/cli/__tests__/context-pick-validation.test.ts+++ b/ix-cli/src/cli/__tests__/context-pick-validation.test.ts@@ -117,7 +117,7 @@ describe("ix context --max-* validation", () => {["--max-entities", "Maximum entities in the bundle", 50, 1, 500],["--max-relationships", "Maximum relationships in the bundle", 100, 1, 1000],["--max-evidence", "Maximum evidence items in the bundle", 25, 1, 200],- ["--max-chars", "Maximum characters of evidence output", 12000, 1000, 1000000],+ ["--max-tokens", "Maximum tokens of evidence output", 1500, 500, 200000],] as const) {// One assertion per flag, so a failure names which one lost its default// rather than reporting that some string was missing from a wall of help.@@ -125,6 +125,13 @@ describe("ix context --max-* validation", () => {`${flag} <n> ${text} (default: ${fallback}, clamped to ${min}-${max})`,);}++ // `--max-chars` is the exception, and says so instead of naming a default+ // it no longer has: its absence produces whatever --max-tokens works out+ // to, not 12000.+ expect(flat, "help for --max-chars").toContain(+ "--max-chars <n> Maximum characters of evidence output (overrides --max-tokens; clamped to 1000-1000000)",+ );});});diff --git a/ix-cli/src/cli/__tests__/context-token-budget.test.ts b/ix-cli/src/cli/__tests__/context-token-budget.test.tsnew file mode 100644index 00000000..651dc1c1--- /dev/null+++ b/ix-cli/src/cli/__tests__/context-token-budget.test.ts@@ -0,0 +1,58 @@+// Copyright 2026 Ix Infrastructure Inc.++import { Command } from "commander";+import { describe, expect, it } from "vitest";++import {+ BUNDLE_CHARS_PER_TOKEN,+ clampBudgets,+ detectContextModeConflict,+ registerContextCommand,+} from "../commands/context.js";++describe("--max-tokens", () => {+ it("is what bounds a default bundle, not 12,000 characters", () => {+ const budgets = clampBudgets({});+ expect(budgets.maxTokens).toBe(1500);+ expect(budgets.maxChars).toBe(Math.round(1500 * BUNDLE_CHARS_PER_TOKEN));+ // The old default was nearly four times this.+ expect(budgets.maxChars).toBeLessThan(12_000);+ });++ it("moves the character budget with it", () => {+ expect(clampBudgets({ maxTokens: 3000 }).maxChars).toBe(Math.round(3000 * BUNDLE_CHARS_PER_TOKEN));+ expect(clampBudgets({ maxTokens: 500 }).maxChars).toBe(1070);+ });++ it("is clamped to its range before it is converted", () => {+ expect(clampBudgets({ maxTokens: 1 }).maxTokens).toBe(500);+ expect(clampBudgets({ maxTokens: 10_000_000 }).maxTokens).toBe(200_000);+ // And the derived character budget still lands inside --max-chars' range.+ expect(clampBudgets({ maxTokens: 10_000_000 }).maxChars).toBeLessThanOrEqual(1_000_000);+ expect(clampBudgets({ maxTokens: 1 }).maxChars).toBeGreaterThanOrEqual(1000);+ });++ it("gives way to an explicit --max-chars", () => {+ const budgets = clampBudgets({ maxChars: 40_000 });+ expect(budgets.maxChars).toBe(40_000);+ // The token field still reports what it would have been, so --diff can say+ // which budget the caller had in force.+ expect(budgets.maxTokens).toBe(1500);+ });++ it("is refused alongside --max-chars rather than silently losing to it", () => {+ const message = detectContextModeConflict({ maxTokens: 2000, maxChars: 40_000 });+ expect(message).toContain("--max-tokens and --max-chars cannot be combined");+ expect(detectContextModeConflict({ maxTokens: 2000 })).toBeUndefined();+ expect(detectContextModeConflict({ maxChars: 40_000 })).toBeUndefined();+ });++ it("is registered, and refuses a value that is not a positive integer", () => {+ const program = new Command().name("ix").exitOverride();+ registerContextCommand(program);+ const context = program.commands.find((c) => c.name() === "context")!;+ const option = context.options.find((o) => o.long === "--max-tokens");+ expect(option).toBeDefined();+ expect(() => option!.parseArg!("1e3", undefined)).toThrow(/positive integer/);+ });+});diff --git a/ix-cli/src/cli/__tests__/context.test.ts b/ix-cli/src/cli/__tests__/context.test.tsindex e0c02487..442c8be0 100644--- a/ix-cli/src/cli/__tests__/context.test.ts+++ b/ix-cli/src/cli/__tests__/context.test.ts@@ -103,7 +103,7 @@ function input() {provenance: { sourceType: "source", extractor: "tree-sitter", observedAt: "2026-01-01T00:00:00Z" },asOfRev: undefined,depth: undefined,- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },};}@@ -135,7 +135,7 @@ describe("ix context bundle", () => {it("enforces budgets and reports explicit truncation", () => {const bundle = buildBundle({...input(),- budgets: { maxEntities: 1, maxRelationships: 0, maxEvidence: 2, maxChars: 12000 },+ budgets: { maxEntities: 1, maxRelationships: 0, maxEvidence: 2, maxTokens: 1500, maxChars: 12000 },});expect(bundle.entities).toHaveLength(1);@@ -172,7 +172,7 @@ describe("ix context bundle", () => {...input(),context: makeContext({ nodes, edges }),// Room for the target plus a couple of entities, not all four.- budgets: { maxEntities: 3, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },+ budgets: { maxEntities: 3, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },});const kept = new Set(bundle.entities.map((e) => e.id));@@ -287,7 +287,7 @@ describe("ix context bundle", () => {buildBundle({...input(),context: makeContext({ nodes }),- budgets: { maxEntities: 5, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },+ budgets: { maxEntities: 5, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },isStale: () => { probes += 1; return false; },});@@ -341,7 +341,7 @@ describe("ix context bundle", () => {it("bounds evidence by the exact serialized representation, not an estimate", () => {const claims = Array.from({ length: 60 }, (_, i) => makeClaim(`statement number ${i} with some padding text`, 0.5));- const budgets = { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 500 };+ const budgets = { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 500 };const bundle = buildBundle({ ...input(), context: makeContext({ claims }), budgets });diff --git a/ix-cli/src/cli/__tests__/mcp.test.ts b/ix-cli/src/cli/__tests__/mcp.test.tsindex b611b968..c3b75ceb 100644--- a/ix-cli/src/cli/__tests__/mcp.test.ts+++ b/ix-cli/src/cli/__tests__/mcp.test.ts@@ -56,7 +56,7 @@ function contextBundle() {provenance: { historyLength: 0, stale: false },freshness: { stale: false, classification: "current" },evidence: [],- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },truncation: { entitiesTruncated: 0, relationshipsTruncated: 0, evidenceTruncated: 0, charactersTruncated: 0 },metadata: { rankingRule: "deterministic-tier" },};diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex 979f8726..ef284ee0 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -26,17 +26,18 @@ import { resolveFileOrReport } from "../resolve.js";import { createStaleProbe, hasCompletedSourceGraphBaseline } from "../stale.js";import { renderNote, renderSection, renderWarning, renderWarningErr, reportFailure } from "../ui.js";-/** The four `--max-*` knobs that bound a bundle. */+/** The `--max-*` knobs that bound a bundle. */interface BudgetSnapshot {maxEntities: number;maxRelationships: number;maxEvidence: number;+ maxTokens: number;maxChars: number;}/**- * The four budgets, described once: flag key, output label, clamp range, and- * the default applied when the flag is absent.+ * The budgets, described once: flag key, output label, clamp range, and the+ * default applied when the flag is absent.** These four facts used to live in five hand-maintained places -- the option* registration, the `clampInt` calls, the record fields, the prose formatter@@ -52,6 +53,7 @@ const BUDGETS = [{ key: "maxEntities", flag: "--max-entities", label: "entities", help: "Maximum entities in the bundle", min: 1, max: 500, fallback: 50 },{ key: "maxRelationships", flag: "--max-relationships", label: "relationships", help: "Maximum relationships in the bundle", min: 1, max: 1000, fallback: 100 },{ key: "maxEvidence", flag: "--max-evidence", label: "evidence", help: "Maximum evidence items in the bundle", min: 1, max: 200, fallback: 25 },+ { key: "maxTokens", flag: "--max-tokens", label: "tokens", help: "Maximum tokens of evidence output", min: 500, max: 200_000, fallback: 1_500 },{ key: "maxChars", flag: "--max-chars", label: "chars", help: "Maximum characters of evidence output", min: 1000, max: 1_000_000, fallback: 12_000 },] as const satisfies ReadonlyArray<{key: keyof BudgetSnapshot;@@ -97,13 +99,45 @@ function budgetParser(key: keyof BudgetSnapshot): (value: string) => number {return (value: string) => parseBudgetOption(value, example);}-/** Apply the table's range and default to whatever the caller supplied. */-function clampBudgets(opts: Partial<BudgetSnapshot>): BudgetSnapshot {+/**+ * Characters per token in a real bundle.+ *+ * Measured across 41 recorded bundles whose prompts differed only by the+ * bundle: 2.14, against the ~4 of ordinary English. A bundle is dense+ * `key=value` and JSON with identifiers in it, and identifiers tokenize badly.+ *+ * Conservative on purpose, and it stays conservative as the bundle gets+ * cleaner: pulling identifier-heavy rows out raises the real ratio, so an+ * estimate pinned at 2.14 over-counts tokens and the bundle comes in under its+ * budget rather than over it. Re-measure before lowering it, never raise it to+ * make a bundle fit.+ */+export const BUNDLE_CHARS_PER_TOKEN = 2.14;++/**+ * Apply the table's range and default to whatever the caller supplied, and+ * turn the token budget into the character budget that bounds the evidence.+ *+ * `--max-tokens` is the budget a caller actually has: the thing being spent is+ * a context window, and 12,000 characters is a number nobody can convert in+ * their head into what it costs them. `--max-chars` stays for the caller who+ * needs exact bytes, and wins outright when passed — the two together are+ * refused up front rather than silently ranked, because which one lost is not+ * visible in the output.+ */+export function clampBudgets(opts: Partial<BudgetSnapshot>): BudgetSnapshot {const out = {} as BudgetSnapshot;for (const b of BUDGETS) {const raw = opts[b.key];out[b.key] = raw === undefined ? b.fallback : Math.min(b.max, Math.max(b.min, raw));}+ if (opts.maxChars === undefined) {+ const chars = budgetField("maxChars");+ out.maxChars = Math.min(+ chars.max,+ Math.max(chars.min, Math.round(out.maxTokens * BUNDLE_CHARS_PER_TOKEN)),+ );+ }return out;}@@ -264,7 +298,17 @@ export function registerContextCommand(program: Command): void {.option("--max-entities <n>", budgetHelp("maxEntities"), budgetParser("maxEntities")).option("--max-relationships <n>", budgetHelp("maxRelationships"), budgetParser("maxRelationships")).option("--max-evidence <n>", budgetHelp("maxEvidence"), budgetParser("maxEvidence"))- .option("--max-chars <n>", budgetHelp("maxChars"), budgetParser("maxChars"))+ .option("--max-tokens <n>", budgetHelp("maxTokens"), budgetParser("maxTokens"))+ // Not `budgetHelp`: there is no independent default to name any more. The+ // character budget is derived from `--max-tokens` unless this flag is+ // passed, and printing "(default: 12000)" beside a flag whose absence+ // produces 3,210 would be the kind of drift the BUDGETS table exists to+ // stop.+ .option(+ "--max-chars <n>",+ `${budgetField("maxChars").help} (overrides --max-tokens; clamped to ${budgetField("maxChars").min}-${budgetField("maxChars").max})`,+ budgetParser("maxChars"),+ ).option("--format <fmt>", "Output format (text|json|llm)", "text").option("--out <path>", "Write the JSON bundle to this file instead of stdout").option("--save <id>", "Persist the bundle as a resumable investigation state")@@ -536,6 +580,13 @@ export function detectContextModeConflict(return `${ignored.join(", ")} cannot be combined with --${mode}; ${why}, so ${ignored.length > 1 ? "those flags change" : "that flag changes"} nothing. Drop ${ignored.length > 1 ? "them" : "it"}, or run ix context <target> to build a bundle with ${ignored.length > 1 ? "them" : "it"}.`;}}+ if (opts.maxTokens !== undefined && opts.maxChars !== undefined) {+ // Refused rather than ranked. They bound the same thing — the evidence+ // block — in two units, and whichever one lost does not appear anywhere in+ // the output, so a caller who set both would have no way to tell which+ // budget was applied. Same rule `ix diff` uses for --summary and --limit.+ return "--max-tokens and --max-chars cannot be combined; both bound the evidence block, in different units. Use --max-tokens for a context-window budget, or --max-chars for exact bytes.";+ }if (opts.list && opts.resume) {return "--list and --resume cannot be combined; --list enumerates saved investigations, --resume renders one. Run --list first, then --resume the id you want.";}diff --git a/ix-cli/src/cli/context-bundle-schema.ts b/ix-cli/src/cli/context-bundle-schema.tsindex 6d4ad35d..42394363 100644--- a/ix-cli/src/cli/context-bundle-schema.ts+++ b/ix-cli/src/cli/context-bundle-schema.ts@@ -24,7 +24,7 @@ export const INVESTIGATION_SCHEMA = "ix-investigation/1";** The shapes below mirror the `ContextBundle` and `EvidenceItem` interfaces in* `commands/context.ts`. Fields the renderers and `--diff` dereference by name- * — `evidence[].title`, the four `budgets`, the four `truncation` counters and+ * — `evidence[].title`, the `budgets`, the four `truncation` counters and* the `metadata` values `--diff` re-sends to the backend — are pinned to their* real types rather than left as open records: validation that accepts `{}`* where the code goes on to read `.title` or `.maxEntities` only moves the@@ -106,6 +106,13 @@ export const contextBundleSchema = z.object({maxEntities: z.number().int().positive(),maxRelationships: z.number().int().positive(),maxEvidence: z.number().int().positive(),+ // Optional, and only this one. A bundle built before `--max-tokens`+ // existed carries the other four and nothing else, and zod strips keys it+ // does not declare — so leaving it out here would not have been "tolerant+ // of old files", it would have silently dropped the field from every new+ // one on its way to disk. Required would refuse to load those old files+ // instead, which is a worse answer than reporting `tokens=not-given`.+ maxTokens: z.number().int().positive().optional(),maxChars: z.number().int().positive(),}),truncation: z.object({diff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.mdindex e712c14f..10c4ffd4 100644--- a/skills/ix/references/flags.md+++ b/skills/ix/references/flags.md@@ -47,6 +47,11 @@ surfaces (#575).--limit 50` exits with an error rather than a shorter list. `--detailed`auto-paginates on its own; `--offset` or `--regions` turns that off, and`--limit` only sets the page size.+- **`ix context` budgets the evidence block in tokens, not characters.**+ `--max-tokens` defaults to 1,500 and is converted at 2.14 characters per+ token, measured across 41 recorded bundles. `--max-chars` is still there for+ a caller who needs exact bytes and overrides it; passing both is refused+ rather than silently ranked, because the output does not say which one won.- **`--pick <n>` is 1-based** everywhere it appears, and is how you resolve anambiguous target without re-running with a longer name.- **`--no-recursive` and `--no-open` negate a default-on behaviour**, so their@@ -147,7 +152,8 @@ Build a bounded, deterministic context bundle for a symbol, file, or entity (or| `--max-entities` | `<n>` | — | Maximum entities in the bundle (default: 50, clamped to 1-500) || `--max-relationships` | `<n>` | — | Maximum relationships in the bundle (default: 100, clamped to 1-1000) || `--max-evidence` | `<n>` | — | Maximum evidence items in the bundle (default: 25, clamped to 1-200) |-| `--max-chars` | `<n>` | — | Maximum characters of evidence output (default: 12000, clamped to 1000-1000000) |+| `--max-tokens` | `<n>` | `1500` | Maximum tokens of evidence output (clamped to 500-200000) |+| `--max-chars` | `<n>` | — | Maximum characters of evidence output; overrides `--max-tokens` (clamped to 1000-1000000) || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--out` | `<path>` | — | Write the JSON bundle to this file instead of stdout || `--save` | `<id>` | — | Persist the bundle as a resumable investigation state |