driftguard-mcp 0.1.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/README.md +146 -0
- package/dist/bin.js +2205 -0
- package/dist/mcp-server.js +1864 -0
- package/package.json +45 -0
package/README.md
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# DriftCLI
|
|
2
|
+
|
|
3
|
+
Real-time AI conversation drift monitor for Claude Code.
|
|
4
|
+
|
|
5
|
+
Reads your Claude Code session directly, scores it across 7 factors, and exposes the result as MCP tools you can call mid-session. No browser, no API keys, no UI — just a score when you need it.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install -g driftguard-mcp
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Then add DriftCLI to your Claude Code MCP config at `~/.claude.json`:
|
|
16
|
+
|
|
17
|
+
```json
|
|
18
|
+
{
|
|
19
|
+
"mcpServers": {
|
|
20
|
+
"driftcli": {
|
|
21
|
+
"command": "driftguard-mcp"
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Restart Claude Code. The `get_drift`, `get_handoff`, and `get_trend` tools are now available in every session.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Usage
|
|
32
|
+
|
|
33
|
+
Call the tools directly from any Claude Code session:
|
|
34
|
+
|
|
35
|
+
- **`get_drift()`** — check the current drift score
|
|
36
|
+
- **`get_handoff()`** — generate a handoff prompt when drift is high
|
|
37
|
+
- **`get_trend()`** — see the full score history for this session
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## What is drift?
|
|
42
|
+
|
|
43
|
+
Long AI sessions degrade. The model starts repeating itself, losing track of the original goal, hedging more, and producing inconsistent code. DriftCLI measures this in real time across 7 factors:
|
|
44
|
+
|
|
45
|
+
| Factor | What it measures |
|
|
46
|
+
|--------|-----------------|
|
|
47
|
+
| Context Saturation | How full the context window is getting |
|
|
48
|
+
| Topic Scatter | How far the conversation has wandered from its starting topics |
|
|
49
|
+
| Uncertainty Signals | Hedging language density |
|
|
50
|
+
| Code Inconsistency | Conflicting patterns across code blocks |
|
|
51
|
+
| Repetition | Rehashing of earlier content |
|
|
52
|
+
| Goal Distance | Drift from the original user intent |
|
|
53
|
+
| Confidence Drift | Declining confidence over the session |
|
|
54
|
+
|
|
55
|
+
Score thresholds: **fresh** 0–29 | **warming** 30–60 | **drifting** 61–80 | **polluted** 81–100
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Tools
|
|
60
|
+
|
|
61
|
+
### `get_drift()`
|
|
62
|
+
|
|
63
|
+
Returns the current drift score and factor breakdown for the active session. When drift exceeds the warn threshold, a handoff prompt is included automatically so you can start fresh without a separate call.
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
Drift Score: 59 WARMING
|
|
67
|
+
Messages: 42
|
|
68
|
+
|
|
69
|
+
Factor breakdown:
|
|
70
|
+
contextSaturation: 72.0
|
|
71
|
+
topicScatter: 50.0
|
|
72
|
+
uncertaintySignals: 31.0
|
|
73
|
+
codeInconsistency: 12.0
|
|
74
|
+
repetition: 0.0
|
|
75
|
+
goalDistance: 44.0
|
|
76
|
+
confidenceDrift: 2.0
|
|
77
|
+
|
|
78
|
+
Context is healthy.
|
|
79
|
+
Trend (last 8): ▁▃▅▆▇ +12 over 8 checks ↗
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### `get_handoff()`
|
|
83
|
+
|
|
84
|
+
Generates a structured handoff prompt. Summarises top topics, recent messages, and the last code block. Paste it into a new session to continue without losing context.
|
|
85
|
+
|
|
86
|
+
### `get_trend()`
|
|
87
|
+
|
|
88
|
+
Shows the full drift history for the current session — sparkline, score sequence, peak, average, and trajectory.
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Configuration
|
|
93
|
+
|
|
94
|
+
DriftCLI looks for config in two places, merged together:
|
|
95
|
+
|
|
96
|
+
- **Global:** `~/.driftclirc`
|
|
97
|
+
- **Per-project:** `.driftcli` in the project root
|
|
98
|
+
|
|
99
|
+
Both are plain JSON. All fields are optional.
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"preset": "coding",
|
|
104
|
+
"warnThreshold": 60
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Presets
|
|
109
|
+
|
|
110
|
+
| Preset | Best for |
|
|
111
|
+
|--------|----------|
|
|
112
|
+
| `coding` | Focused coding sessions — weights code consistency and repetition |
|
|
113
|
+
| `research` | Research or planning — weights topic stability and goal alignment |
|
|
114
|
+
| `brainstorm` | Brainstorming — relaxed topic scatter penalty |
|
|
115
|
+
| `strict` | Equal weight across all seven factors |
|
|
116
|
+
|
|
117
|
+
### All options
|
|
118
|
+
|
|
119
|
+
| Key | Default | Description |
|
|
120
|
+
|-----|---------|-------------|
|
|
121
|
+
| `preset` | — | Named weight preset (see above) |
|
|
122
|
+
| `weights` | — | Per-factor weight overrides, applied on top of preset |
|
|
123
|
+
| `warnThreshold` | `60` | Score at which `get_drift()` warns and includes a handoff prompt |
|
|
124
|
+
| `storage.enabled` | `true` | Persist drift snapshots for `get_trend()` and sparklines |
|
|
125
|
+
| `storage.directory` | `~/.driftcli/history` | Override snapshot storage path |
|
|
126
|
+
| `sessionResolution.cacheTtlMs` | `5000` | How long to cache the resolved session file (ms) |
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## CLI watcher
|
|
131
|
+
|
|
132
|
+
For a live terminal dashboard that polls every 3 seconds, open a separate terminal and run:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
driftguard-mcp watch
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Supported CLIs
|
|
141
|
+
|
|
142
|
+
| CLI | Status |
|
|
143
|
+
|-----|--------|
|
|
144
|
+
| Claude Code | Supported |
|
|
145
|
+
| Gemini CLI | Supported |
|
|
146
|
+
| Codex CLI | Supported |
|