clawprobe 0.6.0 → 0.6.2
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 +185 -253
- package/dist/cli/commands/compacts.d.ts.map +1 -1
- package/dist/cli/commands/compacts.js +5 -1
- package/dist/cli/commands/compacts.js.map +1 -1
- package/dist/cli/commands/context.d.ts.map +1 -1
- package/dist/cli/commands/context.js +1 -0
- package/dist/cli/commands/context.js.map +1 -1
- package/dist/cli/commands/schema.d.ts +9 -0
- package/dist/cli/commands/schema.d.ts.map +1 -0
- package/dist/cli/commands/schema.js +167 -0
- package/dist/cli/commands/schema.js.map +1 -0
- package/dist/cli/commands/session.d.ts.map +1 -1
- package/dist/cli/commands/session.js +5 -1
- package/dist/cli/commands/session.js.map +1 -1
- package/dist/cli/commands/status.d.ts.map +1 -1
- package/dist/cli/commands/status.js +7 -1
- package/dist/cli/commands/status.js.map +1 -1
- package/dist/cli/commands/suggest.d.ts.map +1 -1
- package/dist/cli/commands/suggest.js +8 -0
- package/dist/cli/commands/suggest.js.map +1 -1
- package/dist/cli/format.d.ts +5 -0
- package/dist/cli/format.d.ts.map +1 -1
- package/dist/cli/format.js +9 -1
- package/dist/cli/format.js.map +1 -1
- package/dist/engines/cost.d.ts +4 -0
- package/dist/engines/cost.d.ts.map +1 -1
- package/dist/engines/cost.js +4 -0
- package/dist/engines/cost.js.map +1 -1
- package/dist/engines/rule-engine.js +1 -1
- package/dist/engines/rule-engine.js.map +1 -1
- package/dist/index.js +8 -0
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# clawprobe
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Know exactly what your OpenClaw agent is doing.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Token usage. API cost. Context health. Smart alerts. All in one place — without touching a single line of OpenClaw's internals.
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/clawprobe)
|
|
8
8
|
[](https://www.npmjs.com/package/clawprobe)
|
|
@@ -10,270 +10,245 @@ See what your agent thinks. Track what it forgets. Know what you spend.
|
|
|
10
10
|
[](./LICENSE)
|
|
11
11
|
|
|
12
12
|
[Why clawprobe](#why-clawprobe) •
|
|
13
|
-
[Features](#features) •
|
|
14
13
|
[Quick Start](#quick-start) •
|
|
15
|
-
[
|
|
16
|
-
[
|
|
14
|
+
[Commands](#commands) •
|
|
15
|
+
[Agent Integration](#agent-integration) •
|
|
17
16
|
[Configuration](#configuration) •
|
|
18
|
-
[
|
|
17
|
+
[How It Works](#how-it-works)
|
|
19
18
|
|
|
20
19
|
---
|
|
21
20
|
|
|
22
21
|
## Why clawprobe
|
|
23
22
|
|
|
24
|
-
Your OpenClaw agent
|
|
23
|
+
Your OpenClaw agent lives inside a context window — burning tokens, compacting silently, spending your API budget. But you can't see any of it while it's happening.
|
|
25
24
|
|
|
26
|
-
|
|
25
|
+
clawprobe fixes that. It watches OpenClaw's files in the background and gives you a real-time window into what your agent is actually doing:
|
|
27
26
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
27
|
+
| Problem | clawprobe |
|
|
28
|
+
|---------|-----------|
|
|
29
|
+
| "Is my agent healthy right now?" | `clawprobe status` — one-glance dashboard |
|
|
30
|
+
| "Why is context getting compacted so often?" | `clawprobe context` + `clawprobe suggest` |
|
|
31
|
+
| "What did the agent forget after compaction?" | `clawprobe compacts` |
|
|
32
|
+
| "What is this costing me?" | `clawprobe cost --week` with per-model pricing |
|
|
33
|
+
| "What is my TOOLS.md taking up?" | Truncation detection + token estimates |
|
|
31
34
|
|
|
32
|
-
**
|
|
35
|
+
**No configuration required. Zero side effects. 100% local.**
|
|
33
36
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Quick Start
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
npm install -g clawprobe
|
|
43
|
+
|
|
44
|
+
clawprobe start # Launch background daemon (auto-detects OpenClaw)
|
|
45
|
+
clawprobe status # Instant dashboard
|
|
46
|
+
```
|
|
40
47
|
|
|
41
|
-
|
|
48
|
+
That's it. clawprobe auto-detects your OpenClaw installation at `~/.openclaw`. No API keys, no accounts, no telemetry.
|
|
42
49
|
|
|
43
50
|
---
|
|
44
51
|
|
|
45
|
-
##
|
|
52
|
+
## Commands
|
|
46
53
|
|
|
47
|
-
###
|
|
54
|
+
### `clawprobe status` — Dashboard
|
|
48
55
|
|
|
49
|
-
|
|
56
|
+
Everything you need at a glance: session, model, context utilization, today's cost, and active alerts.
|
|
50
57
|
|
|
51
58
|
```
|
|
52
59
|
$ clawprobe status
|
|
53
60
|
|
|
54
61
|
📊 Agent Status (active session)
|
|
55
62
|
──────────────────────────────────────────────────
|
|
56
|
-
Agent:
|
|
57
|
-
Session:
|
|
58
|
-
Model:
|
|
59
|
-
|
|
60
|
-
This session: 4.6K in / 498 out
|
|
61
|
-
Compacts: 0
|
|
62
|
-
Last active: Today 15:28
|
|
63
|
-
```
|
|
63
|
+
Agent: main
|
|
64
|
+
Session: agent:main:workspace:direct:xxx ●
|
|
65
|
+
Model: moonshot/kimi-k2.5
|
|
66
|
+
Provider: moonshot
|
|
64
67
|
|
|
65
|
-
|
|
68
|
+
Context: 87.3K / 200.0K tokens ███████░░░ 44%
|
|
69
|
+
Input: 72.4K tokens Output: 5.2K tokens
|
|
70
|
+
Compacts: 2 Last active: Today 16:41
|
|
66
71
|
|
|
67
|
-
|
|
72
|
+
Today: $0.12
|
|
68
73
|
|
|
74
|
+
⚠ Context window at 44% capacity
|
|
75
|
+
→ Consider starting a fresh session if nearing limit
|
|
69
76
|
```
|
|
70
|
-
$ clawprobe context
|
|
71
77
|
|
|
72
|
-
|
|
73
|
-
──────────────────────────────────────────────────
|
|
74
|
-
Context used: 14.9K / 256.0K tokens █░░░░░░░░░ 6%
|
|
75
|
-
|
|
76
|
-
Injected workspace files:
|
|
77
|
-
AGENTS.md 7,805 chars ~2.0K tok ✓ ok
|
|
78
|
-
SOUL.md 1,078 chars ~270 tok ✓ ok
|
|
79
|
-
TOOLS.md 851 chars ~213 tok ✓ ok
|
|
78
|
+
---
|
|
80
79
|
|
|
81
|
-
|
|
80
|
+
### `clawprobe cost` — API Cost Tracking
|
|
82
81
|
|
|
83
|
-
|
|
84
|
-
Total in context: 14.9K tokens
|
|
85
|
-
Fixed overhead: ~2.8K tokens (workspace files)
|
|
86
|
-
Conversation est: ~12.2K tokens (messages + system prompt + tools)
|
|
82
|
+
Per-model pricing for 30+ models built-in. Tracks input, output, and cache tokens separately. Day, week, month, or all-time views.
|
|
87
83
|
|
|
88
|
-
Remaining headroom: 241.1K tokens (94%)
|
|
89
84
|
```
|
|
85
|
+
$ clawprobe cost --week
|
|
86
|
+
|
|
87
|
+
💰 Weekly Cost 2026-03-12 – 2026-03-18
|
|
88
|
+
──────────────────────────────────────────────────
|
|
89
|
+
Total: $0.67
|
|
90
|
+
Daily avg: $0.096
|
|
91
|
+
Month est: $2.87
|
|
90
92
|
|
|
91
|
-
|
|
93
|
+
2026-03-12 ██████████████░░ $0.15
|
|
94
|
+
2026-03-16 ████████████████ $0.16
|
|
95
|
+
2026-03-17 █░░░░░░░░░░░░░░░ $0.0088
|
|
96
|
+
2026-03-18 ███░░░░░░░░░░░░░ $0.03
|
|
92
97
|
|
|
93
|
-
|
|
98
|
+
Input: 1.0M tokens $0.65 (97%)
|
|
99
|
+
Output: 47.8K tokens $0.03 (3%)
|
|
94
100
|
|
|
101
|
+
Costs are estimates based on public pricing.
|
|
102
|
+
Verify with your provider's billing dashboard.
|
|
95
103
|
```
|
|
96
|
-
$ clawprobe compacts
|
|
97
104
|
|
|
98
|
-
|
|
99
|
-
|
|
105
|
+
Built-in prices for: OpenAI (GPT-4o, o1, o3, o4-mini), Anthropic (Claude 3/3.5/3.7 Sonnet/Opus/Haiku), Google (Gemini 2.0/2.5 Flash/Pro), Moonshot (kimi-k2.5), DeepSeek (v3, r1), xAI (Grok), and more. Override or add any model via `~/.clawprobe/config.json`.
|
|
106
|
+
|
|
107
|
+
---
|
|
100
108
|
|
|
101
|
-
|
|
109
|
+
### `clawprobe session` — Session Detail
|
|
102
110
|
|
|
103
|
-
|
|
111
|
+
Per-session breakdown with a turn-by-turn cost and token timeline.
|
|
104
112
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
🤖 "Yes, MEMORY.md has been added and is pending commit."
|
|
113
|
+
```
|
|
114
|
+
$ clawprobe session
|
|
108
115
|
|
|
109
|
-
|
|
116
|
+
💬 Session agent:main:workspace:…
|
|
117
|
+
──────────────────────────────────────────────────
|
|
118
|
+
Model: moonshot/kimi-k2.5
|
|
119
|
+
Duration: 2h 14m
|
|
120
|
+
Tokens: In 859.2K Out 29.8K Context 87.3K
|
|
121
|
+
Est. cost: $0.52
|
|
122
|
+
Compacts: 2
|
|
123
|
+
|
|
124
|
+
Turn timeline:
|
|
125
|
+
Turn Time ΔInput ΔOutput Cost
|
|
126
|
+
1 14:02 4.2K 312 $0.003
|
|
127
|
+
2 14:18 12.7K 891 $0.009 ◆ compact
|
|
128
|
+
3 14:41 38.1K 2.4K $0.028
|
|
129
|
+
…
|
|
110
130
|
```
|
|
111
131
|
|
|
112
|
-
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
### `clawprobe context` — Context Window Analysis
|
|
113
135
|
|
|
114
|
-
See
|
|
136
|
+
See what's eating your context window and catch truncation before it silently breaks your agent's tool knowledge.
|
|
115
137
|
|
|
116
138
|
```
|
|
117
|
-
$ clawprobe
|
|
139
|
+
$ clawprobe context
|
|
118
140
|
|
|
119
|
-
|
|
141
|
+
🔍 Context Window agent: main
|
|
120
142
|
──────────────────────────────────────────────────
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
143
|
+
Used: 87.3K / 200.0K tokens ███████░░░ 44%
|
|
144
|
+
|
|
145
|
+
Workspace overhead: ~4.2K tokens (7 injected files)
|
|
146
|
+
Conversation est: ~83.1K tokens (messages + system prompt + tools)
|
|
124
147
|
|
|
125
|
-
|
|
148
|
+
⚠ TOOLS.md: 31% truncated — model never sees this content
|
|
149
|
+
Run: clawprobe context --json or increase bootstrapMaxChars in openclaw.json
|
|
126
150
|
|
|
127
|
-
|
|
128
|
-
Output: 1.2K tokens $0.00 (7%)
|
|
151
|
+
Remaining: 112.7K tokens (56%)
|
|
129
152
|
```
|
|
130
153
|
|
|
131
|
-
|
|
154
|
+
---
|
|
132
155
|
|
|
133
|
-
###
|
|
156
|
+
### `clawprobe compacts` — Compaction Events
|
|
134
157
|
|
|
135
|
-
|
|
158
|
+
Every compaction is captured. See what was discarded and archive key context with `--save`.
|
|
136
159
|
|
|
137
|
-
```bash
|
|
138
|
-
clawprobe memory list # List memory entries
|
|
139
|
-
clawprobe memory search "database" # Search memory
|
|
140
|
-
clawprobe memory add "Prefer snake_case" # Add to memory
|
|
141
|
-
clawprobe memory save-compact 1 # Save from compact event
|
|
142
160
|
```
|
|
161
|
+
$ clawprobe compacts
|
|
143
162
|
|
|
144
|
-
|
|
163
|
+
📦 Compact Events last 5
|
|
164
|
+
──────────────────────────────────────────────────
|
|
145
165
|
|
|
146
|
-
|
|
166
|
+
#3 Today 16:22 [agent:main…] 3 messages
|
|
147
167
|
|
|
168
|
+
👤 "Can you add retry logic to the upload handler?"
|
|
169
|
+
🤖 "Done — added exponential backoff with 3 retries. The key change is in…"
|
|
170
|
+
|
|
171
|
+
→ Archive: clawprobe compacts --save 3
|
|
148
172
|
```
|
|
149
|
-
$ clawprobe suggest
|
|
150
173
|
|
|
151
|
-
|
|
152
|
-
──────────────────────────────────────────────────
|
|
174
|
+
---
|
|
153
175
|
|
|
154
|
-
|
|
155
|
-
```
|
|
176
|
+
### `clawprobe suggest` — Optimization Alerts
|
|
156
177
|
|
|
157
|
-
|
|
178
|
+
Automatic detection of common issues. Fires only when something actually needs your attention.
|
|
158
179
|
|
|
159
180
|
| Rule | What It Detects |
|
|
160
181
|
|------|----------------|
|
|
161
|
-
|
|
|
162
|
-
|
|
|
163
|
-
|
|
|
164
|
-
|
|
|
165
|
-
|
|
|
166
|
-
| Stale workspace files | Files unchanged for 30+ days |
|
|
182
|
+
| `tools-truncation` | TOOLS.md exceeds bootstrap limit — tool descriptions silently cut off |
|
|
183
|
+
| `high-compact-freq` | Context fills and compacts too fast (< 30 min intervals) |
|
|
184
|
+
| `context-headroom` | Context window > 90% full — compaction imminent |
|
|
185
|
+
| `cost-spike` | Today's spend > 2× weekly average |
|
|
186
|
+
| `memory-bloat` | MEMORY.md too large — burning tokens every session |
|
|
167
187
|
|
|
168
|
-
|
|
188
|
+
Dismiss noisy rules with `--dismiss <rule-id>`.
|
|
169
189
|
|
|
170
|
-
|
|
190
|
+
---
|
|
171
191
|
|
|
172
|
-
|
|
192
|
+
## Agent Integration
|
|
173
193
|
|
|
174
|
-
|
|
175
|
-
- OpenClaw installed and configured
|
|
176
|
-
- macOS or Linux (Windows via WSL2)
|
|
194
|
+
clawprobe is designed to be called **by agents**, not just humans. Every command supports `--json` for clean, parseable output. Errors are always JSON too — never coloured text on stderr.
|
|
177
195
|
|
|
178
|
-
###
|
|
196
|
+
### One-shot health check
|
|
179
197
|
|
|
180
198
|
```bash
|
|
181
|
-
|
|
199
|
+
clawprobe status --json
|
|
182
200
|
```
|
|
183
201
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
202
|
+
```json
|
|
203
|
+
{
|
|
204
|
+
"agent": "main",
|
|
205
|
+
"daemonRunning": true,
|
|
206
|
+
"sessionKey": "agent:main:workspace:direct:xxx",
|
|
207
|
+
"model": "moonshot/kimi-k2.5",
|
|
208
|
+
"sessionTokens": 87340,
|
|
209
|
+
"windowSize": 200000,
|
|
210
|
+
"utilizationPct": 44,
|
|
211
|
+
"todayUsd": 0.12,
|
|
212
|
+
"suggestions": [
|
|
213
|
+
{
|
|
214
|
+
"severity": "warning",
|
|
215
|
+
"ruleId": "context-headroom",
|
|
216
|
+
"title": "Context window at 44% capacity",
|
|
217
|
+
"detail": "...",
|
|
218
|
+
"action": "Consider starting a fresh session or manually compacting now"
|
|
219
|
+
}
|
|
220
|
+
]
|
|
221
|
+
}
|
|
189
222
|
```
|
|
190
223
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
---
|
|
194
|
-
|
|
195
|
-
## How It Works
|
|
196
|
-
|
|
197
|
-
clawprobe reads OpenClaw's existing data files and turns them into actionable insights. No code patches, no plugins, no configuration required.
|
|
224
|
+
### Discover the output schema
|
|
198
225
|
|
|
226
|
+
```bash
|
|
227
|
+
clawprobe schema # List all commands with descriptions
|
|
228
|
+
clawprobe schema status # Full field-by-field spec for status --json
|
|
229
|
+
clawprobe schema cost # Field spec for cost --json
|
|
199
230
|
```
|
|
200
|
-
~/.openclaw/ clawprobe
|
|
201
|
-
────────────────────────────────── ────────────────────────────────
|
|
202
|
-
sessions.json → Session metadata, token counts
|
|
203
|
-
*.jsonl transcripts → Compact events, context usage, cost
|
|
204
|
-
workspace/*.md (SOUL, AGENTS, TOOLS…) → File size analysis, truncation detection
|
|
205
|
-
MEMORY.md + memory/*.md → Memory browser & editor
|
|
206
|
-
openclaw.json → Model, provider, config detection
|
|
207
|
-
│
|
|
208
|
-
▼
|
|
209
|
-
~/.clawprobe/probe.db (SQLite)
|
|
210
|
-
│
|
|
211
|
-
▼
|
|
212
|
-
CLI commands + optimization engine
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
### Why It Just Works
|
|
216
231
|
|
|
217
|
-
|
|
218
|
-
- **Zero side effects** — read-only by default; only writes when you explicitly manage memory
|
|
219
|
-
- **No code changes** — reads existing files, never patches OpenClaw internals
|
|
220
|
-
- **Background daemon** — `clawprobe start` launches a watcher that tracks changes in real-time, batching updates with a 300ms debounce
|
|
232
|
+
### Dismiss a suggestion from a script
|
|
221
233
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
| `sessions.json` | Token counts, model, compaction count, session metadata |
|
|
227
|
-
| `*.jsonl` transcripts | Individual messages, compaction events with summaries |
|
|
228
|
-
| `workspace/*.md` | File sizes, token estimates, truncation status |
|
|
229
|
-
| `MEMORY.md` | Memory entries for browsing, searching, and editing |
|
|
230
|
-
| `openclaw.json` | Model config, workspace path, bootstrap limits |
|
|
231
|
-
|
|
232
|
-
---
|
|
234
|
+
```bash
|
|
235
|
+
clawprobe suggest --dismiss context-headroom --json
|
|
236
|
+
# → { "ok": true, "dismissed": "context-headroom" }
|
|
237
|
+
```
|
|
233
238
|
|
|
234
|
-
|
|
239
|
+
### Error responses are always parseable
|
|
235
240
|
|
|
236
241
|
```bash
|
|
237
|
-
#
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
# Status & context
|
|
242
|
-
clawprobe status # Current session (tokens, model, compactions)
|
|
243
|
-
clawprobe context # Context window breakdown
|
|
244
|
-
|
|
245
|
-
# Sessions
|
|
246
|
-
clawprobe session # Active session details + turn timeline
|
|
247
|
-
clawprobe session --list # All sessions
|
|
248
|
-
clawprobe session --list --full # Full session keys (not truncated)
|
|
249
|
-
|
|
250
|
-
# Cost
|
|
251
|
-
clawprobe cost # This week
|
|
252
|
-
clawprobe cost --day # Today
|
|
253
|
-
clawprobe cost --month # This month
|
|
254
|
-
|
|
255
|
-
# Compact events
|
|
256
|
-
clawprobe compacts # Last 5 compact events
|
|
257
|
-
clawprobe compacts --last 10 # Last 10
|
|
258
|
-
|
|
259
|
-
# Memory
|
|
260
|
-
clawprobe memory list # List memory entries
|
|
261
|
-
clawprobe memory search "postgres" # Search memory
|
|
262
|
-
clawprobe memory add "prefer snake_case" # Add to memory
|
|
263
|
-
clawprobe memory save-compact <id> # Save from compact event
|
|
264
|
-
|
|
265
|
-
# Suggestions
|
|
266
|
-
clawprobe suggest # Show optimization suggestions
|
|
267
|
-
|
|
268
|
-
# Diagnostics
|
|
269
|
-
clawprobe config --diag # Full diagnostic dump
|
|
242
|
+
clawprobe session --json # when no session is active
|
|
243
|
+
# → { "ok": false, "error": "no_active_session", "message": "..." }
|
|
244
|
+
# exit code 1
|
|
270
245
|
```
|
|
271
246
|
|
|
272
247
|
---
|
|
273
248
|
|
|
274
249
|
## Configuration
|
|
275
250
|
|
|
276
|
-
Optional config at `~/.clawprobe/config.json
|
|
251
|
+
Optional config at `~/.clawprobe/config.json` (auto-created on first `clawprobe start`):
|
|
277
252
|
|
|
278
253
|
```json
|
|
279
254
|
{
|
|
@@ -284,120 +259,77 @@ Optional config at `~/.clawprobe/config.json`:
|
|
|
284
259
|
},
|
|
285
260
|
"cost": {
|
|
286
261
|
"customPrices": {
|
|
287
|
-
"
|
|
262
|
+
"my-custom-model": { "input": 1.00, "output": 3.00 }
|
|
288
263
|
}
|
|
289
264
|
},
|
|
290
265
|
"alerts": {
|
|
291
266
|
"dailyBudgetUsd": 5.00
|
|
267
|
+
},
|
|
268
|
+
"rules": {
|
|
269
|
+
"disabled": ["memory-bloat"],
|
|
270
|
+
"compactionFreqThresholdMin": 30,
|
|
271
|
+
"memoryBloatThresholdChars": 20000
|
|
292
272
|
}
|
|
293
273
|
}
|
|
294
274
|
```
|
|
295
275
|
|
|
296
|
-
Most users need zero configuration. clawprobe auto-detects everything
|
|
276
|
+
Most users need zero configuration. clawprobe auto-detects everything.
|
|
297
277
|
|
|
298
278
|
---
|
|
299
279
|
|
|
300
|
-
##
|
|
280
|
+
## How It Works
|
|
281
|
+
|
|
282
|
+
clawprobe reads OpenClaw's existing data files — no patches, no plugins, no hooks.
|
|
301
283
|
|
|
302
284
|
```
|
|
303
|
-
clawprobe
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
│
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
│
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
│ │ ├── cost.ts # Token-to-USD cost calculation
|
|
316
|
-
│ │ ├── compact-diff.ts # Compaction analysis engine
|
|
317
|
-
│ │ ├── file-analyzer.ts # Workspace file size & truncation
|
|
318
|
-
│ │ └── rule-engine.ts # Optimization suggestion rules
|
|
319
|
-
│ └── cli/
|
|
320
|
-
│ ├── format.ts # Terminal output formatting
|
|
321
|
-
│ └── commands/ # status, cost, session, compacts, context, suggest, memory
|
|
322
|
-
└── test/ # Unit + integration tests
|
|
285
|
+
~/.openclaw/ clawprobe
|
|
286
|
+
────────────────────────────────── ─────────────────────────────────
|
|
287
|
+
sessions.json → Session metadata, token counts, model
|
|
288
|
+
*.jsonl transcripts → Turn-level costs, compact events, usage
|
|
289
|
+
workspace/*.md → File size analysis, truncation detection
|
|
290
|
+
openclaw.json → Model config, bootstrap limits
|
|
291
|
+
│
|
|
292
|
+
▼
|
|
293
|
+
~/.clawprobe/probe.db (SQLite, local only)
|
|
294
|
+
│
|
|
295
|
+
▼
|
|
296
|
+
CLI + optimization engine
|
|
323
297
|
```
|
|
324
298
|
|
|
325
|
-
|
|
326
|
-
|-------|-----------|-----|
|
|
327
|
-
| Runtime | Node.js ≥ 22 | Matches OpenClaw's requirement |
|
|
328
|
-
| Language | TypeScript | Type-safe, matches OpenClaw ecosystem |
|
|
329
|
-
| File watching | chokidar | Battle-tested, cross-platform |
|
|
330
|
-
| Database | node:sqlite | Built-in, zero dependencies |
|
|
331
|
-
| CLI | commander.js | Standard, well-documented |
|
|
332
|
-
| Terminal UI | chalk + cli-table3 | Clean output, minimal deps |
|
|
299
|
+
**Why it just works:**
|
|
333
300
|
|
|
334
|
-
**
|
|
335
|
-
**
|
|
301
|
+
- **Zero configuration** — auto-detects OpenClaw at `~/.openclaw`
|
|
302
|
+
- **Zero side effects** — read-only; only writes to its own `~/.clawprobe/` directory
|
|
303
|
+
- **Background daemon** — `clawprobe start` launches a watcher with 300ms debounce
|
|
304
|
+
- **4 production dependencies** — chokidar, commander, chalk, cli-table3. No cloud, no telemetry.
|
|
336
305
|
|
|
337
306
|
---
|
|
338
307
|
|
|
339
308
|
## Compatibility
|
|
340
309
|
|
|
341
|
-
clawprobe works
|
|
310
|
+
clawprobe works with any OpenClaw version that writes `sessions.json` and `.jsonl` transcript files to `~/.openclaw/agents/<agent>/sessions/`.
|
|
311
|
+
|
|
312
|
+
**Requirements:** Node.js ≥ 22 · macOS or Linux (Windows via WSL2)
|
|
342
313
|
|
|
343
314
|
---
|
|
344
315
|
|
|
345
316
|
## Privacy
|
|
346
317
|
|
|
347
318
|
- **100% local** — no data ever leaves your machine
|
|
348
|
-
- **Read-only by default** — only writes when you explicitly use `memory add`, `memory edit`, `memory delete`, or `memory save-compact`
|
|
349
319
|
- **No telemetry** — clawprobe collects nothing
|
|
350
|
-
- **No accounts
|
|
351
|
-
|
|
352
|
-
---
|
|
353
|
-
|
|
354
|
-
## Roadmap
|
|
355
|
-
|
|
356
|
-
### v0.3 — Visual
|
|
357
|
-
|
|
358
|
-
- [ ] **Web Dashboard** — Visual timeline, context gauge, cost charts, memory browser at `localhost:4747`
|
|
359
|
-
- [ ] **Session timeline** — Turn-by-turn cost breakdown with compact event markers
|
|
360
|
-
- [ ] **Side-by-side compact diff** — See exactly what was lost vs. what was summarized
|
|
361
|
-
|
|
362
|
-
### v0.4 — OpenClaw Skill
|
|
363
|
-
|
|
364
|
-
- [ ] **In-chat integration** — Ask your agent about its own context, cost, and memory via natural language
|
|
365
|
-
- [ ] **Proactive alerts** — Agent warns you when context is near capacity or cost spikes
|
|
366
|
-
- [ ] **Auto-save on compact** — Automatically preserve important context before compaction discards it
|
|
367
|
-
|
|
368
|
-
### v0.5 — Smarter Analysis
|
|
369
|
-
|
|
370
|
-
- [ ] **ContextEngine adapter** — Hook into the real `assemble()` pipeline for exact token breakdowns
|
|
371
|
-
- [ ] **Retrieval visibility** — See what the memory engine searched and what it returned
|
|
372
|
-
- [ ] **Cross-session analytics** — Compare context patterns and costs across sessions over time
|
|
373
|
-
|
|
374
|
-
### Future
|
|
375
|
-
|
|
376
|
-
- [ ] **Multi-agent support** — Monitor and compare multiple agents side by side
|
|
377
|
-
- [ ] **Export & share** — Portable analysis bundles for debugging agent behavior with others
|
|
378
|
-
- [ ] **Custom rules** — Define your own optimization rules and alert thresholds
|
|
320
|
+
- **No accounts, no API keys** — install and run
|
|
379
321
|
|
|
380
322
|
---
|
|
381
323
|
|
|
382
324
|
## Contributing
|
|
383
325
|
|
|
384
|
-
Contributions
|
|
326
|
+
MIT licensed. Contributions welcome.
|
|
385
327
|
|
|
386
328
|
```bash
|
|
387
329
|
git clone https://github.com/seekcontext/ClawProbe
|
|
388
|
-
cd ClawProbe
|
|
389
|
-
npm install
|
|
390
|
-
npm run dev
|
|
391
|
-
```
|
|
392
|
-
|
|
393
|
-
Run tests:
|
|
394
|
-
|
|
395
|
-
```bash
|
|
396
|
-
npm test
|
|
330
|
+
cd ClawProbe && npm install && npm run dev
|
|
397
331
|
```
|
|
398
332
|
|
|
399
333
|
---
|
|
400
334
|
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
[MIT](./LICENSE) — Use it however you want.
|
|
335
|
+
[MIT License](./LICENSE)
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"compacts.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/compacts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAMtD,UAAU,eAAe;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,
|
|
1
|
+
{"version":3,"file":"compacts.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/compacts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAMtD,UAAU,eAAe;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA4G3F"}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import path from "path";
|
|
2
2
|
import { openDb, getCompactEvents, getCompactEventById } from "../../core/db.js";
|
|
3
3
|
import { saveCompactedMessages } from "../../core/memory-editor.js";
|
|
4
|
-
import { header, fmtDate, fmtTokens, roleIcon, outputJson, severity, divider, printSuccess, printError } from "../format.js";
|
|
4
|
+
import { header, fmtDate, fmtTokens, roleIcon, outputJson, outputJsonError, severity, divider, printSuccess, printError } from "../format.js";
|
|
5
5
|
export async function runCompacts(cfg, opts) {
|
|
6
6
|
const agent = opts.agent ?? cfg.probe.openclaw.agent;
|
|
7
7
|
const db = openDb(cfg.probeDir);
|
|
@@ -9,11 +9,15 @@ export async function runCompacts(cfg, opts) {
|
|
|
9
9
|
if (opts.save !== undefined) {
|
|
10
10
|
const compactId = parseInt(opts.save, 10);
|
|
11
11
|
if (isNaN(compactId)) {
|
|
12
|
+
if (opts.json)
|
|
13
|
+
outputJsonError("invalid_id", `Invalid compact ID: ${opts.save}`);
|
|
12
14
|
printError(`Invalid compact ID: ${opts.save}`);
|
|
13
15
|
process.exit(1);
|
|
14
16
|
}
|
|
15
17
|
const event = getCompactEventById(db, compactId);
|
|
16
18
|
if (!event) {
|
|
19
|
+
if (opts.json)
|
|
20
|
+
outputJsonError("not_found", `Compact event #${compactId} not found.`);
|
|
17
21
|
printError(`Compact event #${compactId} not found.`);
|
|
18
22
|
process.exit(1);
|
|
19
23
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"compacts.js","sourceRoot":"","sources":["../../../src/cli/commands/compacts.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;
|
|
1
|
+
{"version":3,"file":"compacts.js","sourceRoot":"","sources":["../../../src/cli/commands/compacts.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAStD,UAAU,cAAc;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,
|
|
1
|
+
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAStD,UAAU,cAAc;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAwFzF"}
|