config and docs

Author: spoons-and-mirrors

README.md

@@ -28,6 +28,13 @@ DCP implements two complementary strategies:
 **Deduplication** — Fast, zero-cost pruning that identifies repeated tool calls (e.g., reading the same file multiple times) and keeps only the most recent output. Runs instantly with no LLM calls.
 
 **AI Analysis** — Uses a language model to semantically analyze conversation context and identify tool outputs that are no longer relevant to the current task. More thorough but incurs LLM cost.
+
+## Context Pruning Tool
+
+When `strategies.onTool` is enabled, DCP exposes a `context_pruning` tool to Opencode that the AI can call to trigger pruning on demand. To help the AI use this tool effectively, DCP also injects guidance.
+
+When `nudge_freq` is enabled, injects reminders (every `nudge_freq` tool results) prompting the AI to consider pruning when appropriate.
+
 ## How It Works
 
 DCP is **non-destructive**—pruning state is kept in memory only. When requests go to your LLM, DCP replaces pruned outputs with a placeholder; original session data stays intact.
@@ -46,6 +53,7 @@ DCP uses its own config file (`~/.config/opencode/dcp.jsonc` or `.opencode/dcp.j
 | `showModelErrorToasts` | `true` | Show notifications on model fallback |
 | `strictModelSelection` | `false` | Only run AI analysis with session or configured model (disables fallback models) |
 | `pruning_summary` | `"detailed"` | `"off"`, `"minimal"`, or `"detailed"` |
+| `nudge_freq` | `5` | Remind AI to prune every N tool results (0 = disabled) |
 | `protectedTools` | `["task", "todowrite", "todoread", "context_pruning"]` | Tools that are never pruned |
 | `strategies.onIdle` | `["deduplication", "ai-analysis"]` | Strategies for automatic pruning |
 | `strategies.onTool` | `["deduplication", "ai-analysis"]` | Strategies when AI calls `context_pruning` |

index.ts

@@ -77,9 +77,9 @@ const plugin: Plugin = (async (ctx) => {
 
                     let modified = false
 
-                    // Inject periodic nudge every 5 tool results
-                    if (config.strategies.onTool.length > 0) {
-                        if (injectNudge(body.messages, toolTracker, NUDGE_INSTRUCTION)) {
+                    // Inject periodic nudge every N tool results
+                    if (config.strategies.onTool.length > 0 && config.nudge_freq > 0) {
+                        if (injectNudge(body.messages, toolTracker, NUDGE_INSTRUCTION, config.nudge_freq)) {
                             logger.debug("fetch", "Injected tool-result nudge", {
                                 toolResultCount: toolTracker.toolResultCount
                             })

lib/config.ts

@@ -15,6 +15,7 @@ export interface PluginConfig {
     showModelErrorToasts?: boolean
     strictModelSelection?: boolean
     pruning_summary: "off" | "minimal" | "detailed"
+    nudge_freq: number
     strategies: {
         onIdle: PruningStrategy[]
         onTool: PruningStrategy[]
@@ -33,6 +34,7 @@ const defaultConfig: PluginConfig = {
     showModelErrorToasts: true,
     strictModelSelection: false,
     pruning_summary: 'detailed',
+    nudge_freq: 5,
     strategies: {
         onIdle: ['deduplication', 'ai-analysis', "strip-reasoning"],
         onTool: ['deduplication', 'ai-analysis', "strip-reasoning"]
@@ -47,6 +49,7 @@ const VALID_CONFIG_KEYS = new Set([
     'showModelErrorToasts',
     'strictModelSelection',
     'pruning_summary',
+    'nudge_freq',
     'strategies'
 ])
 
@@ -118,6 +121,8 @@ function createDefaultConfig(): void {
   },
   // Summary display: "off", "minimal", or "detailed"
   "pruning_summary": "detailed",
+  // How often to nudge the AI to prune (every N tool results, 0 = disabled)
+  "nudge_freq": 5,
   // Tools that should never be pruned
   "protectedTools": ["task", "todowrite", "todoread", "context_pruning"]
 }
@@ -196,7 +201,8 @@ export function getConfig(ctx?: PluginInput): ConfigResult {
                     showModelErrorToasts: globalConfig.showModelErrorToasts ?? config.showModelErrorToasts,
                     strictModelSelection: globalConfig.strictModelSelection ?? config.strictModelSelection,
                     strategies: mergeStrategies(config.strategies, globalConfig.strategies as any),
-                    pruning_summary: globalConfig.pruning_summary ?? config.pruning_summary
+                    pruning_summary: globalConfig.pruning_summary ?? config.pruning_summary,
+                    nudge_freq: globalConfig.nudge_freq ?? config.nudge_freq
                 }
                 logger.info('config', 'Loaded global config', { path: configPaths.global })
             }
@@ -226,7 +232,8 @@ export function getConfig(ctx?: PluginInput): ConfigResult {
                     showModelErrorToasts: projectConfig.showModelErrorToasts ?? config.showModelErrorToasts,
                     strictModelSelection: projectConfig.strictModelSelection ?? config.strictModelSelection,
                     strategies: mergeStrategies(config.strategies, projectConfig.strategies as any),
-                    pruning_summary: projectConfig.pruning_summary ?? config.pruning_summary
+                    pruning_summary: projectConfig.pruning_summary ?? config.pruning_summary,
+                    nudge_freq: projectConfig.nudge_freq ?? config.nudge_freq
                 }
                 logger.info('config', 'Loaded project config (overrides global)', { path: configPaths.project })
             }

lib/synth-instruction.ts

@@ -38,21 +38,22 @@ function countToolResults(messages: any[], tracker: ToolTracker): number {
 }
 
 /**
- * Counts new tool results and injects nudge instruction every 5th tool result.
+ * Counts new tool results and injects nudge instruction every N tool results.
  * Returns true if injection happened.
  */
 export function injectNudge(
     messages: any[],
     tracker: ToolTracker,
-    nudgeText: string
+    nudgeText: string,
+    freq: number
 ): boolean {
     const prevCount = tracker.toolResultCount
     const newCount = countToolResults(messages, tracker)
 
     if (newCount > 0) {
-        // Check if we crossed a multiple of 5
-        const prevBucket = Math.floor(prevCount / 5)
-        const newBucket = Math.floor(tracker.toolResultCount / 5)
+        // Check if we crossed a multiple of freq
+        const prevBucket = Math.floor(prevCount / freq)
+        const newBucket = Math.floor(tracker.toolResultCount / freq)
         if (newBucket > prevBucket) {
             // Inject at the END of messages so it's in immediate context
             return appendNudge(messages, nudgeText)