@lanegrid/agtrace 0.1.9 β 0.1.10
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 +9 -0
- package/README.md +20 -188
- package/npm-shrinkwrap.json +2 -2
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## [0.1.10] - 2025-12-29
|
|
6
|
+
|
|
7
|
+
### Documentation
|
|
8
|
+
|
|
9
|
+
- Split README into focused documentation structure (motivation, getting-started, commands, architecture, faq, providers)
|
|
10
|
+
- Consolidate provider documentation with accurate log paths
|
|
11
|
+
- Simplify documentation by removing redundant sections
|
|
12
|
+
- Add cargo install option to README
|
|
13
|
+
|
|
5
14
|
## [0.1.9] - 2025-12-29
|
|
6
15
|
|
|
7
16
|
### Bug Fixes
|
package/README.md
CHANGED
|
@@ -1,12 +1,7 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
<img src="https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/images/agtrace-icon.png" width="96" alt="agtrace logo">
|
|
3
3
|
<h1>agtrace</h1>
|
|
4
|
-
<p><strong>
|
|
5
|
-
<p>
|
|
6
|
-
Real-time telemetry and session forensics for Claude Code, Codex, and Gemini.
|
|
7
|
-
Track context window usage, compaction behavior, and regressions β
|
|
8
|
-
<strong>locally</strong>, with <strong>zero overhead</strong>.
|
|
9
|
-
</p>
|
|
4
|
+
<p><strong>top + tail -f for AI Coding Agent Sessions.</strong></p>
|
|
10
5
|
|
|
11
6
|
[](https://www.npmjs.com/package/@lanegrid/agtrace)
|
|
12
7
|
[](https://crates.io/crates/agtrace)
|
|
@@ -14,205 +9,42 @@
|
|
|
14
9
|
|
|
15
10
|
---
|
|
16
11
|
|
|
17
|
-
## π The Problem: No Observability for Context Compaction
|
|
18
|
-
|
|
19
|
-
Modern AI coding agents rely on context window compaction by design. It is a standard mechanism across Claude Code, Codex, and Gemini.
|
|
20
|
-
|
|
21
|
-
The problem is not that compaction happens.
|
|
22
|
-
|
|
23
|
-
The problem is that you cannot:
|
|
24
|
-
- observe *when* compaction occurs
|
|
25
|
-
- measure *how much* context was discarded
|
|
26
|
-
- correlate compaction with regressions, hallucinations, or sudden behavioral shifts
|
|
27
|
-
|
|
28
|
-
In practice, we are running a lossy, stateful system without logs, metrics, or traces for its most critical state transition.
|
|
29
|
-
|
|
30
|
-
## β‘ The Solution: agtrace
|
|
31
|
-
|
|
32
|
-
**agtrace** adds the missing observability layer to AI coding agents.
|
|
33
|
-
|
|
34
|
-
By normalizing provider logs and exposing real-time context usage and compaction behavior, agtrace makes agent state transitions inspectable and debuggable β without sending sensitive data to the cloud.
|
|
35
|
-
|
|
36
12
|
|
|
37
13
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
*The dashboard showing context usage, current turn, and token costs*
|
|
43
|
-
|
|
44
|
-
---
|
|
45
|
-
|
|
46
|
-
## β¨ Key Features
|
|
47
|
-
|
|
48
|
-
### 1) Live Telemetry (`watch`)
|
|
49
|
-
A TUI dashboard that visualizes the health of your active session:
|
|
50
|
-
- remaining context window (before compaction pressure)
|
|
51
|
-
- current turn and recent activity
|
|
52
|
-
- token/cost telemetry (where available)
|
|
53
|
-
|
|
54
|
-
### 2) Provider Normalization
|
|
55
|
-
Whether you use **Claude Code**, **Codex**, or **Gemini**, agtrace converts their events into a consistent internal format so you can reason about sessions the same way across providers.
|
|
56
|
-
|
|
57
|
-
### 3) Local-Only by Default
|
|
58
|
-
Agent logs often contain sensitive code and secrets. **agtrace runs 100% locally** and reads directly from local log files (e.g., `~/.claude`). No data is sent to the cloud.
|
|
59
|
-
|
|
60
|
-
### 4) Always-On Session Tracking
|
|
61
|
-
Keep `watch` running β it automatically detects new sessions and follows the latest one.
|
|
62
|
-
|
|
63
|
-
### 5) Session Forensics (βLabβ)
|
|
64
|
-
Investigate agent behavior across history:
|
|
65
|
-
- search across thousands of past sessions
|
|
66
|
-
- analyze tool usage patterns
|
|
67
|
-
- inspect raw provider events when debugging schema changes (`--raw`)
|
|
68
|
-
|
|
69
|
-
### 6) High-Performance, Minimal Footprint
|
|
70
|
-
Built in **Rust**, agtrace is designed to run continuously without slowing down your machine while you work with heavyweight AI agents.
|
|
71
|
-
|
|
72
|
-
### 7) Instant Log Analysis
|
|
73
|
-
Parse and grep through gigabytes of JSONL logs quickly. The schema-on-read approach plus Rust performance makes historical analysis fast and practical.
|
|
74
|
-
|
|
75
|
-
---
|
|
76
|
-
|
|
77
|
-
## π¦ Installation
|
|
14
|
+
## What it does
|
|
78
15
|
|
|
79
|
-
|
|
16
|
+
- Live dashboard for context pressure, tool activity, and costs
|
|
17
|
+
- Session history you can query and compare
|
|
18
|
+
- Works with Claude Code, Codex, and Gemini
|
|
19
|
+
- 100% local, no cloud
|
|
80
20
|
|
|
81
|
-
|
|
21
|
+
## Install
|
|
82
22
|
|
|
83
23
|
```bash
|
|
84
24
|
npm install -g @lanegrid/agtrace
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
### via npx (no installation)
|
|
88
|
-
|
|
89
|
-
If you prefer not to install globally, run via `npx`.
|
|
90
|
-
|
|
91
|
-
*Note: In the examples below, replace `agtrace` with `npx @lanegrid/agtrace`.*
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
npx @lanegrid/agtrace@latest init
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
### via Cargo (Rust)
|
|
98
|
-
|
|
99
|
-
```bash
|
|
25
|
+
# or
|
|
100
26
|
cargo install agtrace
|
|
101
27
|
```
|
|
102
28
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
## π Quick Start
|
|
106
|
-
|
|
107
|
-
### 0) Initialize Once (Global)
|
|
108
|
-
|
|
109
|
-
Run `agtrace init` **once** on your machine.
|
|
110
|
-
|
|
111
|
-
This creates local configuration and caches under `~/.agtrace`.
|
|
112
|
-
It does **not** modify any project directory, and you do **not** need to run it per project.
|
|
113
|
-
|
|
114
|
-
```bash
|
|
115
|
-
agtrace init
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
### 1) Open Your Project Directory (CWD matters)
|
|
119
|
-
|
|
120
|
-
`agtrace` scopes monitoring by the **current working directory (cwd)**.
|
|
121
|
-
|
|
122
|
-
To ensure `agtrace` can locate and follow the right session logs, run it from the **same working directory** where your AI coding agent is started.
|
|
123
|
-
|
|
124
|
-
```bash
|
|
125
|
-
cd /path/to/your/project
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
### 2) Start `watch` (either order works)
|
|
129
|
-
|
|
130
|
-
In one terminal pane (from the project directory), run:
|
|
131
|
-
|
|
132
|
-
```bash
|
|
133
|
-
agtrace watch
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
`watch` can be started before or after your AI coding agent.
|
|
137
|
-
|
|
138
|
-
* If no active session exists yet, it stays in **waiting mode** (or opens the latest session if available).
|
|
139
|
-
* When a new session starts, agtrace detects the new logs and **automatically switches** to it.
|
|
140
|
-
* You do **not** need to restart `agtrace watch` per session.
|
|
141
|
-
|
|
142
|
-
### 3) Start Your AI Coding Agent (Same CWD)
|
|
143
|
-
|
|
144
|
-
In another terminal (same project directory), launch your agent:
|
|
145
|
-
|
|
146
|
-
```bash
|
|
147
|
-
# Example: Claude Code
|
|
148
|
-
claude
|
|
149
|
-
|
|
150
|
-
# Or Codex, Gemini, etc.
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
Thatβs it. No integration required β `watch` follows sessions by monitoring logs scoped to your current working directory.
|
|
154
|
-
|
|
155
|
-
**`watch` surfaces:**
|
|
156
|
-
|
|
157
|
-
* context window usage
|
|
158
|
-
* compaction pressure / behavior (where detectable)
|
|
159
|
-
* turns and recent activity
|
|
160
|
-
* token/cost telemetry (where available)
|
|
161
|
-
|
|
162
|
-
### 4) Analyze Past Sessions
|
|
29
|
+
## Usage
|
|
163
30
|
|
|
164
31
|
```bash
|
|
165
|
-
#
|
|
166
|
-
agtrace
|
|
167
|
-
|
|
168
|
-
# Inspect a specific session (context usage, turns, models)
|
|
169
|
-
agtrace session show <session_id>
|
|
32
|
+
agtrace init # once
|
|
33
|
+
agtrace watch # in project dir, then start your agent
|
|
170
34
|
```
|
|
171
35
|
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
Debug agent interactions or search for specific patterns, e.g. βWhen did the agent try to write to `package.json`?β:
|
|
36
|
+
## Learn More
|
|
175
37
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
# Inspect a raw provider event (useful for debugging schema changes)
|
|
181
|
-
agtrace lab grep "mcp" --raw --limit 1
|
|
182
|
-
```
|
|
38
|
+
- [Why agtrace?](docs/motivation.md) - Understanding the problem and solution
|
|
39
|
+
- [Getting Started](docs/getting-started.md) - Detailed installation and usage guide
|
|
40
|
+
- [Full Documentation](docs/README.md) - Commands, architecture, and FAQs
|
|
183
41
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
## π§ CWD-Scoped Monitoring
|
|
187
|
-
|
|
188
|
-
agtrace uses your current working directory (cwd) as the scope boundary for log discovery and session tracking.
|
|
189
|
-
To monitor a different project, run `agtrace watch` from that project's directory.
|
|
190
|
-
|
|
191
|
-
---
|
|
42
|
+
## Supported Providers
|
|
192
43
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
1. **No Data Duplication**
|
|
198
|
-
agtrace does not copy your massive log files. It indexes metadata and points to the original logs.
|
|
199
|
-
|
|
200
|
-
2. **Resilient to Schema Drift**
|
|
201
|
-
Provider log schemas change frequently. agtrace parses logs at read time, so schema updates are less likely to corrupt or invalidate historical indexes.
|
|
202
|
-
|
|
203
|
-
3. **Project Isolation**
|
|
204
|
-
Sessions are scoped by cwd/project boundaries and grouped by a project root hash to keep workspaces clean and prevent cross-project mixing.
|
|
205
|
-
|
|
206
|
-
---
|
|
207
|
-
|
|
208
|
-
## π€ Supported Providers
|
|
209
|
-
|
|
210
|
-
* **Claude Code** (Anthropic)
|
|
211
|
-
* **Codex** (OpenAI)
|
|
212
|
-
* **Gemini** (Google)
|
|
213
|
-
|
|
214
|
-
---
|
|
44
|
+
- **Claude Code** (Anthropic)
|
|
45
|
+
- **Codex** (OpenAI)
|
|
46
|
+
- **Gemini** (Google)
|
|
215
47
|
|
|
216
|
-
##
|
|
48
|
+
## License
|
|
217
49
|
|
|
218
50
|
Dual-licensed under the MIT and Apache 2.0 licenses.
|
package/npm-shrinkwrap.json
CHANGED
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
"hasInstallScript": true,
|
|
24
24
|
"license": "MIT OR Apache-2.0",
|
|
25
25
|
"name": "@lanegrid/agtrace",
|
|
26
|
-
"version": "0.1.
|
|
26
|
+
"version": "0.1.10"
|
|
27
27
|
},
|
|
28
28
|
"node_modules/@isaacs/balanced-match": {
|
|
29
29
|
"engines": {
|
|
@@ -515,5 +515,5 @@
|
|
|
515
515
|
}
|
|
516
516
|
},
|
|
517
517
|
"requires": true,
|
|
518
|
-
"version": "0.1.
|
|
518
|
+
"version": "0.1.10"
|
|
519
519
|
}
|
package/package.json
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.1.
|
|
2
|
+
"artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.1.10",
|
|
3
3
|
"bin": {
|
|
4
4
|
"agtrace": "run-agtrace.js"
|
|
5
5
|
},
|
|
@@ -93,7 +93,7 @@
|
|
|
93
93
|
"zipExt": ".tar.xz"
|
|
94
94
|
}
|
|
95
95
|
},
|
|
96
|
-
"version": "0.1.
|
|
96
|
+
"version": "0.1.10",
|
|
97
97
|
"volta": {
|
|
98
98
|
"node": "18.14.1",
|
|
99
99
|
"npm": "9.5.0"
|