@comfanion/usethis_todo 0.1.7-dev.3 โ 0.1.8
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/README.md +58 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -19,6 +19,64 @@ An OpenCode plugin that transforms TODO lists into **intelligent task graphs**:
|
|
|
19
19
|
|
|
20
20
|
---
|
|
21
21
|
|
|
22
|
+
## ๐งน Context Leak Problem & Auto-Pruning
|
|
23
|
+
|
|
24
|
+
### The Problem
|
|
25
|
+
|
|
26
|
+
Every time an AI agent calls a TODO tool, the **full output** (task list, graph, stats) is appended to the conversation history. In a typical session, an agent may call TODO tools **dozens of times** โ creating tasks, updating statuses, reading the list, checking what's next.
|
|
27
|
+
|
|
28
|
+
Without cleanup, this is what happens to your context window:
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
Call 1: usethis_todo_write โ +800 tokens (full graph output)
|
|
32
|
+
Call 2: usethis_todo_update โ +800 tokens (full graph output)
|
|
33
|
+
Call 3: usethis_todo_read โ +800 tokens (full graph output)
|
|
34
|
+
Call 4: usethis_todo_update โ +800 tokens (full graph output)
|
|
35
|
+
...
|
|
36
|
+
Call 20: usethis_todo_update โ +800 tokens (full graph output)
|
|
37
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
38
|
+
Total TODO overhead: ~16,000 tokens โ wasted on stale snapshots
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Only the **last** call result matters. The other 19 are stale data sitting in the context window, pushing out useful code, conversation, and reasoning. This is the **context leak** โ silent, cumulative, and it degrades agent performance as the session progresses.
|
|
42
|
+
|
|
43
|
+
The problem compounds with larger task lists. A 30-task graph with dependencies can produce 2,000+ tokens per call. After 15 updates, that's **30,000 tokens** of dead weight โ roughly 10-15% of a typical context window, gone.
|
|
44
|
+
|
|
45
|
+
### The Solution: Auto-Pruning
|
|
46
|
+
|
|
47
|
+
This plugin hooks into `experimental.chat.messages.transform` to automatically clean up old TODO results **before each LLM call**:
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
Call 1: usethis_todo_write โ [TODO pruned] โ cleaned
|
|
51
|
+
Call 2: usethis_todo_update โ [TODO pruned] โ cleaned
|
|
52
|
+
Call 3: usethis_todo_read โ [TODO pruned] โ cleaned
|
|
53
|
+
Call 4: usethis_todo_update โ (full graph output) โ only latest kept
|
|
54
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
55
|
+
Total TODO overhead: ~800 tokens โ constant, not cumulative
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**How it works:**
|
|
59
|
+
|
|
60
|
+
1. **Track last call** โ after each TODO tool execution, the plugin records the `callID` in a per-session state
|
|
61
|
+
2. **Transform messages** โ before each LLM inference, the plugin scans all messages and replaces old TODO tool outputs with `[TODO pruned]`, clearing both `output` and `input` fields
|
|
62
|
+
3. **Keep latest** โ only the most recent TODO call result is preserved in full, giving the agent current state
|
|
63
|
+
4. **Prune snapshots** โ the plugin also publishes TODO state as user messages (for UI display); old snapshot messages are removed, keeping only the latest
|
|
64
|
+
5. **Complete cleanup** โ when all tasks are marked `done`, even the last result is pruned โ the TODO list served its purpose and no longer needs context space
|
|
65
|
+
|
|
66
|
+
**Result:** TODO tool overhead is **O(1)** instead of **O(n)** โ constant ~800 tokens regardless of how many times the agent interacts with the task list.
|
|
67
|
+
|
|
68
|
+
### What Gets Pruned
|
|
69
|
+
|
|
70
|
+
| Content | Pruned? | Why |
|
|
71
|
+
|---------|---------|-----|
|
|
72
|
+
| Old `todo_write` / `todo_update` outputs | Yes | Stale state |
|
|
73
|
+
| Old `todo_read` / `todo_read_five` outputs | Yes | Stale snapshots |
|
|
74
|
+
| Old `## TODO` snapshot messages | Yes | Duplicate of tool output |
|
|
75
|
+
| Latest tool call output | **No** | Agent needs current state |
|
|
76
|
+
| All outputs when all tasks are done | **Yes** | Work is finished, free the context |
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
22
80
|
## ๐ Quick Start
|
|
23
81
|
|
|
24
82
|
### Installation
|