antigravity-plugin-context-mode 1.3.2 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +29 -0
- package/README.md +4 -4
- package/hooks/pre-invocation.js +84 -0
- package/hooks/pre-tool-use.js +129 -24
- package/hooks/session-start.js +75 -7
- package/hooks.json +7 -0
- package/lib/store.js +415 -66
- package/lib/tools.js +83 -68
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/rules/AGENTS.md +18 -5
- package/server.js +11 -17
- package/skills/context-mode/SKILL.md +27 -18
package/lib/tools.js
CHANGED
|
@@ -3,7 +3,7 @@ import path from "node:path";
|
|
|
3
3
|
import http from "node:http";
|
|
4
4
|
import https from "node:https";
|
|
5
5
|
import { executeCode, runProcess, OUTPUT_CAP } from "./executor.js";
|
|
6
|
-
import { SNIPPET_MAX_BYTES } from "./store.js";
|
|
6
|
+
import { SNIPPET_MAX_BYTES, resolveFilePath } from "./store.js";
|
|
7
7
|
|
|
8
8
|
const EXEC_PREVIEW_BYTES = 4096;
|
|
9
9
|
|
|
@@ -76,17 +76,19 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
|
|
|
76
76
|
const fullOutput = (result.stdout ? result.stdout : "") + (result.stderr ? "\n" + result.stderr : "");
|
|
77
77
|
const fullBytes = Buffer.byteLength(fullOutput, "utf8");
|
|
78
78
|
|
|
79
|
-
let
|
|
79
|
+
let outputPath = null;
|
|
80
80
|
if (fullBytes > 0) {
|
|
81
|
+
outputPath = file ? `${file}.output.log` : `ctx_execute_${Date.now()}.log`;
|
|
81
82
|
const indexed = store.indexContent({
|
|
82
83
|
sessionId,
|
|
83
84
|
worktree: cwd,
|
|
84
85
|
agent: "antigravity",
|
|
85
86
|
kind: "execution",
|
|
86
87
|
label: intent || `${language} script (${elapsedMs}ms)`,
|
|
88
|
+
path: outputPath,
|
|
87
89
|
content: fullOutput
|
|
88
90
|
});
|
|
89
|
-
|
|
91
|
+
outputPath = indexed.path;
|
|
90
92
|
}
|
|
91
93
|
|
|
92
94
|
const cutoffBytes = store.getCutoff(sessionId);
|
|
@@ -109,7 +111,7 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
|
|
|
109
111
|
kind: "execution",
|
|
110
112
|
tool: "ctx_execute",
|
|
111
113
|
key: language,
|
|
112
|
-
path: file || null,
|
|
114
|
+
path: file || outputPath || null,
|
|
113
115
|
ok: result.ok ? 1 : 0,
|
|
114
116
|
exitCode: result.exitCode,
|
|
115
117
|
bytes: fullBytes,
|
|
@@ -120,7 +122,7 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
|
|
|
120
122
|
|
|
121
123
|
let responseText = returnedText;
|
|
122
124
|
if (truncated) {
|
|
123
|
-
responseText += `\n\n... [${formatBytes(fullBytes - returnedBytes)} truncated to protect context window; full output indexed into ${
|
|
125
|
+
responseText += `\n\n... [${formatBytes(fullBytes - returnedBytes)} truncated to protect context window; full output indexed into ${outputPath}. Use ctx_search(queries: [...], path: "${outputPath}") to query it]`;
|
|
124
126
|
}
|
|
125
127
|
|
|
126
128
|
return {
|
|
@@ -129,7 +131,7 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
|
|
|
129
131
|
elapsedMs,
|
|
130
132
|
language,
|
|
131
133
|
intent: intent || null,
|
|
132
|
-
|
|
134
|
+
path: outputPath,
|
|
133
135
|
rawBytes: fullBytes,
|
|
134
136
|
returnedBytes,
|
|
135
137
|
output: responseText
|
|
@@ -153,12 +155,14 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
|
|
|
153
155
|
}
|
|
154
156
|
|
|
155
157
|
const combined = outputs.join("\n");
|
|
158
|
+
const batchPath = `ctx_batch_${Date.now()}.log`;
|
|
156
159
|
const indexed = store.indexContent({
|
|
157
160
|
sessionId,
|
|
158
161
|
worktree: cwd,
|
|
159
162
|
agent: "antigravity",
|
|
160
163
|
kind: "batch",
|
|
161
164
|
label: `batch: ${cmdList.length} commands`,
|
|
165
|
+
path: batchPath,
|
|
162
166
|
content: combined
|
|
163
167
|
});
|
|
164
168
|
|
|
@@ -166,7 +170,7 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
|
|
|
166
170
|
if (queries && queries.length > 0) {
|
|
167
171
|
const searchRes = store.search({
|
|
168
172
|
queries,
|
|
169
|
-
|
|
173
|
+
path: indexed.path,
|
|
170
174
|
sessionId,
|
|
171
175
|
limit: 10
|
|
172
176
|
});
|
|
@@ -174,7 +178,7 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
|
|
|
174
178
|
} else {
|
|
175
179
|
returnedContent = combined.slice(0, EXEC_PREVIEW_BYTES);
|
|
176
180
|
if (totalRawBytes > EXEC_PREVIEW_BYTES) {
|
|
177
|
-
returnedContent += `\n\n... [truncated. Use ctx_search(queries: [...],
|
|
181
|
+
returnedContent += `\n\n... [truncated. Use ctx_search(queries: [...], path: "${indexed.path}") to search full batch output]`;
|
|
178
182
|
}
|
|
179
183
|
}
|
|
180
184
|
|
|
@@ -194,89 +198,66 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
|
|
|
194
198
|
|
|
195
199
|
return {
|
|
196
200
|
commandsRun: cmdList.length,
|
|
197
|
-
|
|
201
|
+
path: indexed.path,
|
|
198
202
|
rawBytes: totalRawBytes,
|
|
199
203
|
returnedBytes,
|
|
200
204
|
content: returnedContent
|
|
201
205
|
};
|
|
202
206
|
},
|
|
203
207
|
|
|
204
|
-
// 3.
|
|
205
|
-
async
|
|
208
|
+
// 3. ctx_search (Just-In-Time auto-indexing for files, directories, and URLs)
|
|
209
|
+
async ctx_search({ queries = [], path: targetPath = null, scope = "session", limit = 5, offset = 0, reverse = false } = {}) {
|
|
206
210
|
const cwd = getCwd();
|
|
207
211
|
const sessionId = getSessionId();
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
212
|
+
const effectivePath = targetPath || null;
|
|
213
|
+
|
|
214
|
+
if (effectivePath && /^https?:\/\//i.test(effectivePath)) {
|
|
215
|
+
try {
|
|
216
|
+
const rawText = await fetchUrlText(effectivePath);
|
|
217
|
+
store.indexContent({
|
|
218
|
+
sessionId,
|
|
219
|
+
worktree: cwd,
|
|
220
|
+
agent: "antigravity",
|
|
221
|
+
kind: "web",
|
|
222
|
+
label: effectivePath,
|
|
223
|
+
path: effectivePath,
|
|
224
|
+
content: rawText
|
|
225
|
+
});
|
|
226
|
+
} catch (err) {
|
|
227
|
+
throw new Error(`Failed to fetch URL for search: ${err.message}`);
|
|
219
228
|
}
|
|
220
|
-
rawText = fs.readFileSync(absPath, "utf8");
|
|
221
229
|
}
|
|
222
230
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
const indexed = store.indexContent({
|
|
231
|
+
const res = store.search({
|
|
232
|
+
queries,
|
|
233
|
+
path: effectivePath,
|
|
228
234
|
sessionId,
|
|
229
235
|
worktree: cwd,
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
236
|
+
scope,
|
|
237
|
+
limit,
|
|
238
|
+
offset,
|
|
239
|
+
reverse: Boolean(reverse)
|
|
234
240
|
});
|
|
235
241
|
|
|
236
|
-
const
|
|
237
|
-
sourceId: indexed.sourceId,
|
|
238
|
-
label: indexed.label,
|
|
239
|
-
bytesTotal: indexed.bytesTotal,
|
|
240
|
-
chunkCount: indexed.chunkCount,
|
|
241
|
-
message: `Indexed ${formatBytes(indexed.bytesTotal)} into ${indexed.chunkCount} chunks. Query with ctx_search.`
|
|
242
|
-
};
|
|
243
|
-
|
|
244
|
-
const returnedBytes = Buffer.byteLength(JSON.stringify(returnObj), "utf8");
|
|
245
|
-
|
|
242
|
+
const returnedBytes = Buffer.byteLength(JSON.stringify(res), "utf8");
|
|
246
243
|
store.recordEvent({
|
|
247
244
|
sessionId,
|
|
248
245
|
worktree: cwd,
|
|
249
246
|
agent: "antigravity",
|
|
250
|
-
kind: "
|
|
251
|
-
tool: "
|
|
252
|
-
path:
|
|
247
|
+
kind: "search",
|
|
248
|
+
tool: "ctx_search",
|
|
249
|
+
path: res.path || effectivePath,
|
|
253
250
|
ok: 1,
|
|
254
|
-
bytes:
|
|
255
|
-
body:
|
|
256
|
-
sandboxBytes:
|
|
251
|
+
bytes: returnedBytes,
|
|
252
|
+
body: `ctx_search: ${res.returned} hits`,
|
|
253
|
+
sandboxBytes: 0,
|
|
257
254
|
returnedBytes
|
|
258
255
|
});
|
|
259
256
|
|
|
260
|
-
return returnObj;
|
|
261
|
-
},
|
|
262
|
-
|
|
263
|
-
// 4. ctx_search
|
|
264
|
-
async ctx_search({ queries = [], sourceId = null, scope = "session", limit = 5, offset = 0 } = {}) {
|
|
265
|
-
const cwd = getCwd();
|
|
266
|
-
const sessionId = getSessionId();
|
|
267
|
-
|
|
268
|
-
const res = store.search({
|
|
269
|
-
queries,
|
|
270
|
-
sourceId,
|
|
271
|
-
sessionId,
|
|
272
|
-
worktree: cwd,
|
|
273
|
-
scope,
|
|
274
|
-
limit,
|
|
275
|
-
offset
|
|
276
|
-
});
|
|
277
|
-
|
|
278
257
|
return {
|
|
279
258
|
queries,
|
|
259
|
+
path: res.path,
|
|
260
|
+
reverse: Boolean(reverse),
|
|
280
261
|
totalMatches: res.totalMatches,
|
|
281
262
|
returned: res.returned,
|
|
282
263
|
offset: res.offset,
|
|
@@ -317,6 +298,14 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
|
|
|
317
298
|
}
|
|
318
299
|
|
|
319
300
|
const s = store.getStats(sessionId);
|
|
301
|
+
const cutoffBytes = store.getCutoff(sessionId);
|
|
302
|
+
const cutoffStr = cutoffBytes === 0 ? "Disabled (unlimited)" : `${formatBytes(cutoffBytes)} (${cutoffBytes.toLocaleString()} bytes)`;
|
|
303
|
+
const autoIndexBytes = store.getMaxAutoIndexBytes(sessionId);
|
|
304
|
+
const autoIndexStr = autoIndexBytes === 0 ? "Disabled (off)" : `${formatBytes(autoIndexBytes)} (${autoIndexBytes.toLocaleString()} bytes)`;
|
|
305
|
+
const exemptCats = store.getExemptCategories(sessionId);
|
|
306
|
+
const exemptExts = store.getExemptExtensions(sessionId);
|
|
307
|
+
const customExts = store.getCustomExemptExtensions(sessionId);
|
|
308
|
+
|
|
320
309
|
const report = [
|
|
321
310
|
"────────────────────────────────────────────────────────────────────────────────",
|
|
322
311
|
` Antigravity context-mode stats [session: ${sessionId}]`,
|
|
@@ -327,22 +316,48 @@ export function createTools({ store, getCwd = () => process.cwd(), getSessionId
|
|
|
327
316
|
` Tokens Kept Out: ~${s.tokensKeptOut.toLocaleString()} tokens (${formatBytes(s.keptOutBytes)})`,
|
|
328
317
|
` Reduction Rate: ${s.savingsPercent}% saved`,
|
|
329
318
|
"",
|
|
319
|
+
` Active Read Cutoff: ${cutoffStr} (tool read cutoff, NOT LLM context window)`,
|
|
320
|
+
` Auto-Index Ceiling: ${autoIndexStr} (auto-indexes files on block)`,
|
|
321
|
+
` Exempt Categories: ${exemptCats.join(", ")}`,
|
|
322
|
+
` Exempt Extensions: ${exemptExts.length} extensions (e.g. .png, .pdf, .docx, .zip; never blocked)`,
|
|
323
|
+
...(customExts.length > 0 ? [` Custom Exemptions: ${customExts.join(", ")}`] : []),
|
|
324
|
+
"",
|
|
330
325
|
` Without context-mode ${renderBar(1.0)} ${formatBytes(s.totalRawBytes)}`,
|
|
331
326
|
` With context-mode ${renderBar(s.totalRawBytes > 0 ? s.totalReturnedBytes / s.totalRawBytes : 0)} ${formatBytes(s.totalReturnedBytes)}`,
|
|
332
327
|
"────────────────────────────────────────────────────────────────────────────────"
|
|
333
328
|
].join("\n");
|
|
334
329
|
|
|
335
330
|
return {
|
|
336
|
-
stats:
|
|
331
|
+
stats: {
|
|
332
|
+
...s,
|
|
333
|
+
activeCutoffBytes: cutoffBytes,
|
|
334
|
+
activeCutoffFormatted: cutoffStr,
|
|
335
|
+
maxAutoIndexBytes: autoIndexBytes,
|
|
336
|
+
maxAutoIndexFormatted: autoIndexStr,
|
|
337
|
+
exemptCategories: exemptCats,
|
|
338
|
+
exemptExtensions: exemptExts,
|
|
339
|
+
customExemptExtensions: customExts
|
|
340
|
+
},
|
|
337
341
|
report
|
|
338
342
|
};
|
|
339
343
|
},
|
|
340
344
|
|
|
341
345
|
// 7. ctx_doctor
|
|
342
346
|
async ctx_doctor() {
|
|
347
|
+
const sessionId = getSessionId();
|
|
343
348
|
const doc = store.doctor();
|
|
349
|
+
const cutoffBytes = store.getCutoff(sessionId);
|
|
350
|
+
const exemptCats = store.getExemptCategories(sessionId);
|
|
351
|
+
const exemptExts = store.getExemptExtensions(sessionId);
|
|
352
|
+
|
|
344
353
|
return {
|
|
345
|
-
doctor:
|
|
354
|
+
doctor: {
|
|
355
|
+
...doc,
|
|
356
|
+
activeCutoffBytes: cutoffBytes,
|
|
357
|
+
activeCutoffFormatted: cutoffBytes === 0 ? "Disabled (unlimited)" : `${formatBytes(cutoffBytes)} (${cutoffBytes.toLocaleString()} bytes)`,
|
|
358
|
+
exemptCategories: exemptCats,
|
|
359
|
+
exemptExtensionsCount: exemptExts.length
|
|
360
|
+
},
|
|
346
361
|
runtimes: {
|
|
347
362
|
node: process.version,
|
|
348
363
|
platform: process.platform,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "antigravity-plugin-context-mode",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.0",
|
|
4
4
|
"description": "Native Antigravity plugin for context-mode: SQLite FTS5 indexing, sandboxed execution, and lifecycle hook protection against context window bloat",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
package/plugin.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"name": "antigravity-plugin-context-mode",
|
|
3
3
|
"displayName": "Context Mode",
|
|
4
4
|
"description": "Context window protection for Antigravity: local SQLite FTS5 search, sandboxed execution, and lifecycle hook gating against token bloat.",
|
|
5
|
-
"version": "1.
|
|
5
|
+
"version": "1.5.0",
|
|
6
6
|
"author": "Phillip Webber <github@webbsense.com>",
|
|
7
7
|
"repository": {
|
|
8
8
|
"type": "git",
|
package/rules/AGENTS.md
CHANGED
|
@@ -1,8 +1,21 @@
|
|
|
1
1
|
# Context Mode Behavioral Standards
|
|
2
2
|
|
|
3
|
-
When `antigravity-plugin-context-mode` is active, agents MUST adhere to context budgeting laws:
|
|
3
|
+
When `antigravity-plugin-context-mode` is active, agents MUST adhere to context budgeting laws while understanding active limits:
|
|
4
4
|
|
|
5
|
-
1. **
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
1. **Active Read Cutoff vs LLM Context Window**:
|
|
6
|
+
- The active cutoff limit (default 8 KB per file/command, or as configured per session) is a **single-operation tool read/command cutoff** enforced by `PreToolUse` to prevent accidental token bloat.
|
|
7
|
+
- It is **NOT your LLM context window**. Your LLM context window is vastly larger. Do NOT assume your context window is 8 KB.
|
|
8
|
+
- Files or command outputs within the active cutoff limit can always be read directly.
|
|
9
|
+
|
|
10
|
+
2. **Intra-File & Directory Searches (Prioritize `ctx_search`)**:
|
|
11
|
+
- **Always prioritize `ctx_search(queries: [...], path: "path/to/target")`** whenever you need to search for specific functions, symbols, error patterns, or text inside any file or directory.
|
|
12
|
+
- `ctx_search` automatically indexes and updates files Just-In-Time based on file modification timestamps—you do NOT need to read files into context first or run any manual indexing.
|
|
13
|
+
- **Log & Chronological Files**: When searching logs, traces, or events, pass `reverse: true` (e.g. `ctx_search(queries: ["error"], path: "Logs/app.log", reverse: true)`) to inspect the newest lines and most recent errors at the tail of the file first.
|
|
14
|
+
- **Line Slices**: Read files directly with `StartLine` and `EndLine` only when you already know the specific lines needed (within the active line limit).
|
|
15
|
+
- **Script Filtering**: Or inspect/filter with short scripts via `ctx_execute`.
|
|
16
|
+
|
|
17
|
+
3. **Zero Raw Log Dumps**: Never run unbounded terminal commands (`cat`, `Get-Content`, `type`, unpaged `git log`, direct `curl`/`wget` to stdout). Pipe to limiters for only the specific lines needed (e.g. `| Select-Object -First <lines>` or `| head -n <lines>`) or run via `ctx_execute`.
|
|
18
|
+
|
|
19
|
+
4. **Token Verification & Active Status**:
|
|
20
|
+
- The active cutoff limit and currently active exempt file types are dynamically announced in the session status message and on configuration changes.
|
|
21
|
+
- To inspect live token savings, the active cutoff, and live exemption status at any time, run `ctx_stats` or `ctx_doctor`.
|
package/server.js
CHANGED
|
@@ -166,35 +166,29 @@ const TOOL_DEFINITIONS = [
|
|
|
166
166
|
required: ["commands"]
|
|
167
167
|
}
|
|
168
168
|
},
|
|
169
|
-
{
|
|
170
|
-
name: "ctx_index",
|
|
171
|
-
description: "Index a file, URL, or raw text into SQLite FTS5 for fast BM25/trigram searching.",
|
|
172
|
-
inputSchema: {
|
|
173
|
-
type: "object",
|
|
174
|
-
properties: {
|
|
175
|
-
path: { type: "string", description: "Path to local file to index" },
|
|
176
|
-
url: { type: "string", description: "HTTP/HTTPS URL to fetch and index" },
|
|
177
|
-
content: { type: "string", description: "Raw string content to index" },
|
|
178
|
-
label: { type: "string", description: "Descriptive label for this source" }
|
|
179
|
-
}
|
|
180
|
-
}
|
|
181
|
-
},
|
|
182
169
|
{
|
|
183
170
|
name: "ctx_search",
|
|
184
171
|
description:
|
|
185
|
-
"Search the local SQLite FTS5 database across indexed logs, tool outputs, and documentation using
|
|
172
|
+
"Search the local SQLite FTS5 database across indexed logs, files, tool outputs, and documentation using BM25 + Trigram RRF. If path is a file, directory, or URL, it is automatically indexed Just-In-Time if unindexed or modified.",
|
|
186
173
|
inputSchema: {
|
|
187
174
|
type: "object",
|
|
188
175
|
properties: {
|
|
189
176
|
queries: { type: "array", items: { type: "string" }, description: "Search queries or tokens to match" },
|
|
190
|
-
|
|
177
|
+
path: {
|
|
178
|
+
type: "string",
|
|
179
|
+
description: "Path to a file, directory, or URL to search (auto-indexed Just-In-Time if unindexed or changed). Omit to search active session."
|
|
180
|
+
},
|
|
191
181
|
scope: {
|
|
192
182
|
type: "string",
|
|
193
183
|
enum: ["session", "worktree", "all"],
|
|
194
|
-
description: "Search scope (default: session)"
|
|
184
|
+
description: "Search scope when path is omitted (default: session)"
|
|
195
185
|
},
|
|
196
186
|
limit: { type: "integer", description: "Max number of snippets to return (default 5)" },
|
|
197
|
-
offset: { type: "integer", description: "Offset for pagination" }
|
|
187
|
+
offset: { type: "integer", description: "Offset for pagination" },
|
|
188
|
+
reverse: {
|
|
189
|
+
type: "boolean",
|
|
190
|
+
description: "Search in reverse order (tail-first), prioritizing the newest lines/entries at the end of log files (default: false)"
|
|
191
|
+
}
|
|
198
192
|
},
|
|
199
193
|
required: ["queries"]
|
|
200
194
|
}
|
|
@@ -10,12 +10,23 @@ Instead of dumping megabytes of text into the conversation, Context Mode indexes
|
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
13
|
+
## Active Read Cutoff vs LLM Context Window
|
|
14
|
+
|
|
15
|
+
Context Mode enforces a single-operation read/command cutoff (default 8 KB, configurable per session or globally).
|
|
16
|
+
|
|
17
|
+
* **Tool-Level Read Cutoff**: This threshold applies strictly to individual `read_file` calls or terminal dump commands (`cat`, `Get-Content`, `type`) on non-exempt text/code files to protect against accidental bloat.
|
|
18
|
+
* **NOT the LLM Context Window**: The model retains its full, large context window capacity. Do **not** confuse the tool-level read cutoff (e.g. 8 KB) with the model's context window.
|
|
19
|
+
* **Dynamic Active Exemptions**: Active file category exemptions and custom extensions are dynamically loaded from SQLite and injected into your session by the `SessionStart` and `PreInvocation` hooks. Files matching active exemptions bypass cutoff protection. Use `ctx_stats` or `ctx_doctor` to check live exemptions at any time.
|
|
20
|
+
* **Intra-File & Directory Searches (Prioritize `ctx_search`)**: Whenever you need to locate symbols, methods, config values, or error patterns in any file or directory, use `ctx_search(queries: [...], path: "path/to/target")`. If the file is unindexed or has been modified on disk, `ctx_search` automatically indexes or updates it on-demand before searching.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
13
24
|
## When to Use Context Mode
|
|
14
25
|
|
|
15
26
|
| Task | Traditional Tool (High Bloat) | Context Mode Solution (Zero Bloat) |
|
|
16
27
|
| :--- | :--- | :--- |
|
|
28
|
+
| **Searching code, logs, or docs** | Full un-paged `read_file` | `ctx_search(queries: ["..."], path: "path/to/target")` (JIT auto-indexed) |
|
|
17
29
|
| **Analyzing build or server logs** | `run_command("Get-Content Logs/Editor.log")` | `ctx_execute(code: "...", intent: "Find compile errors in Editor.log")` |
|
|
18
|
-
| **Searching huge documentation or code** | Full `read_file` (> 400 lines) | `ctx_index(path: "...")` $\rightarrow$ `ctx_search(queries: ["..."])` |
|
|
19
30
|
| **Processing API JSON responses** | Fetching and dumping 5,000 JSON items | `ctx_execute(language: "javascript", code: "fetch(...)")` |
|
|
20
31
|
| **Running multi-command batches** | Running 10 commands in separate tool calls | `ctx_batch(commands: [...], queries: [...])` |
|
|
21
32
|
| **Session recovery & token stats** | Re-reading entire past conversation | `ctx_resume()` / `ctx_stats()` |
|
|
@@ -35,25 +46,21 @@ Executes a short script in a local sandbox (Node.js, Python, PowerShell, or Shel
|
|
|
35
46
|
}
|
|
36
47
|
```
|
|
37
48
|
|
|
38
|
-
### 2. `
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
"path": "Documentation/Architecture.md",
|
|
43
|
-
"label": "Architecture Guide"
|
|
44
|
-
}
|
|
45
|
-
```
|
|
49
|
+
### 2. `ctx_search` (On-Demand / JIT Search)
|
|
50
|
+
Queries indexed chunks using Reciprocal Rank Fusion (Porter BM25 stemming + Trigram matching). If `path` is specified (file, directory, or URL), Context Mode checks if the target is unindexed or modified, automatically indexes it Just-In-Time, and scopes the search.
|
|
51
|
+
|
|
52
|
+
For log files, pass `"reverse": true` to prioritize tail-first inspection (latest errors and timestamps first):
|
|
46
53
|
|
|
47
|
-
### 3. `ctx_search`
|
|
48
|
-
Queries indexed chunks using Reciprocal Rank Fusion (Porter BM25 stemming + Trigram matching). Returns ranked snippets:
|
|
49
54
|
```json
|
|
50
55
|
{
|
|
51
|
-
"queries": ["
|
|
56
|
+
"queries": ["FATAL", "Exception"],
|
|
57
|
+
"path": "Logs/Editor.log",
|
|
58
|
+
"reverse": true,
|
|
52
59
|
"limit": 5
|
|
53
60
|
}
|
|
54
61
|
```
|
|
55
62
|
|
|
56
|
-
###
|
|
63
|
+
### 3. `ctx_batch`
|
|
57
64
|
Executes multiple shell commands in batch. The combined outputs are indexed and filtered by your queries:
|
|
58
65
|
```json
|
|
59
66
|
{
|
|
@@ -67,18 +74,20 @@ Executes multiple shell commands in batch. The combined outputs are indexed and
|
|
|
67
74
|
```
|
|
68
75
|
|
|
69
76
|
### 5. `ctx_stats`
|
|
70
|
-
Generates a token savings report showing
|
|
77
|
+
Generates a token savings and status report showing active cutoff, exempt categories, raw bytes handled, and estimated tokens kept out of the model's context window:
|
|
71
78
|
```json
|
|
72
79
|
{}
|
|
73
80
|
```
|
|
74
81
|
|
|
75
82
|
### 6. `ctx_doctor`
|
|
76
|
-
Checks SQLite database health, FTS5 availability, and active runtimes.
|
|
83
|
+
Checks SQLite database health, active cutoff limits, exempt categories, FTS5 availability, and active runtimes.
|
|
77
84
|
|
|
78
85
|
---
|
|
79
86
|
|
|
80
87
|
## Best Practices
|
|
81
88
|
|
|
82
|
-
1. **
|
|
83
|
-
2. **
|
|
84
|
-
3. **
|
|
89
|
+
1. **Check Active Limits & Exemptions**: At session start or anytime via `ctx_stats` or `ctx_doctor`, verify the active cutoff limit and active exemptions.
|
|
90
|
+
2. **Read Exempt Media Directly**: Multimodal files (images, audio, video, PDFs, Office files, 3D models) are exempt from cutoff limits and will never be blocked by `read_file`.
|
|
91
|
+
3. **Write focused extraction scripts**: In `ctx_execute`, print only the final data structures or count summaries rather than raw loops.
|
|
92
|
+
4. **Never dump full logs**: If a text log file is > 100 KB, never call un-paged `read_file` or bare `Get-Content`. Route it through `ctx_execute` or `ctx_index`.
|
|
93
|
+
5. **Use Trigram for identifiers**: `ctx_search` matches code symbols, GUIDs, and file paths via trigram indexing even if English stemming does not match.
|