@lanegrid/agtrace 0.1.6 → 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.
Files changed (4) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/README.md +120 -58
  3. package/npm-shrinkwrap.json +2 -2
  4. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,62 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [0.1.8] - 2025-12-28
6
+
7
+ ### Documentation
8
+
9
+ - Rewrite README to emphasize observability layer and compaction behavior ([c8a669f](https://github.com/lanegrid/agtrace/commit/c8a669fac6db12214febc0796f3b32b62ce5d032))
10
+
11
+ - Rewrite README to emphasize observability layer and compaction behavior ([8fafcf4](https://github.com/lanegrid/agtrace/commit/8fafcf4680ba80e93decb634ed3d348cee8034a1))
12
+
13
+ - Clarify CWD-scoped monitoring and improve Quick Start workflow ([63e5c38](https://github.com/lanegrid/agtrace/commit/63e5c38e8d2c7d4e4d56576054055615c89237c7))
14
+
15
+ - Use GitHub raw content URLs for images and move demo.gif to docs/assets ([d4dbda6](https://github.com/lanegrid/agtrace/commit/d4dbda623e32e18cb8519bcced6dd22a70ec2e2d))
16
+
17
+
18
+ ### Miscellaneous Tasks
19
+
20
+ - Remove PROGRESS.md ([0e728f5](https://github.com/lanegrid/agtrace/commit/0e728f5c627988d64e93cd640c6a30f73153c3bd))
21
+
22
+
23
+ ## [0.1.7] - 2025-12-28
24
+
25
+ ### Features
26
+
27
+ - Add demo mode to showcase TUI without requiring local logs ([a7f3261](https://github.com/lanegrid/agtrace/commit/a7f3261))
28
+
29
+ ### Bug Fixes
30
+
31
+ - Change turn percentage display from cumulative to delta (incremental) ([65eeaa5](https://github.com/lanegrid/agtrace/commit/65eeaa5))
32
+ - Preserve all events in demo to prevent turn count reduction ([1bbe397](https://github.com/lanegrid/agtrace/commit/1bbe397))
33
+ - Link demo notifications to progress bar percentage instead of event index ([07f0577](https://github.com/lanegrid/agtrace/commit/07f0577))
34
+ - Unify progress bar calculation to include both input and output tokens ([49e0b5b](https://github.com/lanegrid/agtrace/commit/49e0b5b))
35
+ - Add context window limit enforcement to demo token generation ([f6771c5](https://github.com/lanegrid/agtrace/commit/f6771c5))
36
+ - Update demo model name and prevent context window overflow ([c708a9c](https://github.com/lanegrid/agtrace/commit/c708a9c))
37
+ - Assemble session from events to display turn data in demo mode ([7f77b87](https://github.com/lanegrid/agtrace/commit/7f77b87))
38
+ - Correct provider default log paths in help text ([0d6f5b8](https://github.com/lanegrid/agtrace/commit/0d6f5b8))
39
+
40
+ ### Refactoring
41
+
42
+ - Unify --source option to --provider across CLI ([657cd40](https://github.com/lanegrid/agtrace/commit/657cd40))
43
+ - Rename source to provider in internal API ([b7ab5a4](https://github.com/lanegrid/agtrace/commit/b7ab5a4))
44
+ - Centralize CLI command hints to prevent duplication and typos ([6188a34](https://github.com/lanegrid/agtrace/commit/6188a34))
45
+ - Add scenario builder pattern and expand demo to 7 turns with 100+ events ([7917ffb](https://github.com/lanegrid/agtrace/commit/7917ffb))
46
+ - Unify token usage logic by using engine's extract_state_updates in demo ([a79f5b9](https://github.com/lanegrid/agtrace/commit/a79f5b9))
47
+ - Remove hardcoded context limit in demo, use configurable constant ([9277085](https://github.com/lanegrid/agtrace/commit/9277085))
48
+
49
+ ### Documentation
50
+
51
+ - Add VHS demo gif and agtrace demo command documentation ([ea15513](https://github.com/lanegrid/agtrace/commit/ea15513))
52
+ - Regenerate demo.gif with cargo-installed agtrace v0.1.6 ([ef0b1c7](https://github.com/lanegrid/agtrace/commit/ef0b1c7))
53
+ - Reduce demo.gif size for better readability (1200x700) ([d328478](https://github.com/lanegrid/agtrace/commit/d328478))
54
+ - Organize demo generation scripts into scripts/demo directory ([acd1d46](https://github.com/lanegrid/agtrace/commit/acd1d46))
55
+ - Increase demo.gif font size for better readability (FontSize 18) ([508d1c1](https://github.com/lanegrid/agtrace/commit/508d1c1))
56
+ - Improve CLI help text and command descriptions for better UX ([0ae8b91](https://github.com/lanegrid/agtrace/commit/0ae8b91))
57
+ - Remove unnecessary documents ([98bb313](https://github.com/lanegrid/agtrace/commit/98bb313))
58
+ - Add centered logo to README header ([0327721](https://github.com/lanegrid/agtrace/commit/0327721))
59
+ - Add crates.io badge and cargo install instructions ([2908ebb](https://github.com/lanegrid/agtrace/commit/2908ebb))
60
+
5
61
  ## [0.1.6] - 2025-12-27
6
62
 
7
63
  ### Infrastructure
package/README.md CHANGED
@@ -1,57 +1,82 @@
1
- # agtrace
1
+ <div align="center">
2
+ <img src="https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/images/agtrace-icon.png" width="96" alt="agtrace logo">
3
+ <h1>agtrace</h1>
4
+ <p><strong>The Observability Layer for AI Coding Agents.</strong></p>
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>
10
+
11
+ [![npm version](https://img.shields.io/npm/v/@lanegrid/agtrace.svg?style=flat)](https://www.npmjs.com/package/@lanegrid/agtrace)
12
+ [![crates.io](https://img.shields.io/crates/v/agtrace.svg)](https://crates.io/crates/agtrace)
13
+ </div>
2
14
 
3
- **The Vital Monitor for AI Coding Agents.**
15
+ ---
4
16
 
5
- Real-time telemetry, context window tracking, and session forensics for Claude Code, Codex, and Gemini. **Built in Rust for zero-overhead monitoring.**
17
+ ## 📉 The Problem: No Observability for Context Compaction
6
18
 
7
- [![npm version](https://img.shields.io/npm/v/@lanegrid/agtrace.svg?style=flat)](https://www.npmjs.com/package/@lanegrid/agtrace)
19
+ Modern AI coding agents rely on context window compaction by design. It is a standard mechanism across Claude Code, Codex, and Gemini.
8
20
 
9
- ---
21
+ The problem is not that compaction happens.
10
22
 
11
- ## 📉 The Problem: "Context Window Anxiety"
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
12
27
 
13
- AI Coding Agents (Claude Code, Codex, etc.) are evolving rapidly, but managing their **"Context Window"** has become a hidden, cognitively heavy burden for humans.
28
+ In practice, we are running a lossy, stateful system without logs, metrics, or traces for its most critical state transition.
14
29
 
15
- When a conversation exceeds the token limit, agents trigger **"Auto Compaction"** (silent compression). They start to "forget" previous instructions, file contents, or architectural decisions. Currently, this happens invisibly. You only realize it when the agent starts hallucinating or making regression errors.
30
+ ## ⚡ The Solution: agtrace
16
31
 
17
- You are effectively flying a plane without a fuel gauge.
32
+ **agtrace** adds the missing observability layer to AI coding agents.
18
33
 
19
- ## ⚡ The Solution: agtrace
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
+ ![agtrace watch demo](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)
20
37
 
21
- **agtrace** is a local-only telemetry tool that acts as a "Vital Check" for your AI agents. by normalizing logs from various providers, it visualizes the internal state of your agent in real-time.
38
+ *Live demo of `agtrace watch` — real-time session monitoring*
22
39
 
23
- ![agtrace watch TUI dashboard](docs/images/watch-screenshot-claude.png)
40
+ ![agtrace watch TUI dashboard](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/images/watch-screenshot-claude.png)
24
41
 
25
- *The dashboard showing Context Window usage, current turn, and token costs*
42
+ *The dashboard showing context usage, current turn, and token costs*
26
43
 
27
- ### Key Features
44
+ ---
45
+
46
+ ## ✨ Key Features
28
47
 
29
- * **👁️ Live Vital Monitoring (`watch`)**
30
- A TUI (Terminal User Interface) dashboard that visualizes the "health" of your session. See exactly how much Context Window is remaining before auto-compaction hits.
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)
31
53
 
32
- * **🔌 Provider Normalization**
33
- Whether you use `Claude Code`, `Codex`, or `Gemini`, agtrace normalizes the events into a standard format.
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.
34
56
 
35
- * **🔒 Local & Private**
36
- Agent logs contain sensitive code and secrets. **agtrace runs 100% locally.** No data is sent to the cloud. It reads directly from your local log files (`~/.claude`, etc.).
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.
37
59
 
38
- * **🚀 Auto-Tracking**
39
- The `watch` command automatically detects new sessions as they are created. Just keep it running in a separate terminal pane.
60
+ ### 4) Always-On Session Tracking
61
+ Keep `watch` running — it automatically detects new sessions and follows the latest one.
40
62
 
41
- * **🥼 Forensics Lab**
42
- Use `agtrace lab grep` to search across thousands of past sessions, analyze tool usage patterns, or debug agent behavior with `--raw` inspection.
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`)
43
68
 
44
- * **⚡ Zero-Overhead Monitoring**
45
- Built in **Rust**, agtrace is designed to run in the background with a minimal footprint. It won't slow down your machine while you work with heavy AI agents.
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.
46
71
 
47
- * **🔍 Instant Forensics**
48
- Parse and grep through gigabytes of JSONL logs in milliseconds. The schema-on-read architecture combined with Rust's performance makes analyzing history instantaneous.
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.
49
74
 
50
75
  ---
51
76
 
52
77
  ## 📦 Installation
53
78
 
54
- We recommend installing `agtrace` globally for the best performance and quick access to the `watch` command.
79
+ For best performance and easy access to `watch`, install globally.
55
80
 
56
81
  ### via npm (Recommended)
57
82
 
@@ -59,89 +84,126 @@ We recommend installing `agtrace` globally for the best performance and quick ac
59
84
  npm install -g @lanegrid/agtrace
60
85
  ```
61
86
 
62
- ### ⚡ Or use via npx
87
+ ### via npx (no installation)
88
+
89
+ If you prefer not to install globally, run via `npx`.
63
90
 
64
- If you prefer not to install it globally, you can run commands using `npx`.
65
91
  *Note: In the examples below, replace `agtrace` with `npx @lanegrid/agtrace`.*
66
92
 
67
93
  ```bash
68
94
  npx @lanegrid/agtrace@latest init
69
95
  ```
70
96
 
97
+ ### via Cargo (Rust)
98
+
99
+ ```bash
100
+ cargo install agtrace
101
+ ```
71
102
 
72
103
  ---
73
104
 
74
105
  ## 🚀 Quick Start
75
106
 
76
- ### 1. Initialize in Your Project
107
+ ### 0) Initialize Once (Global)
108
+
109
+ Run `agtrace init` **once** on your machine.
77
110
 
78
- Navigate to your project directory and run:
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.
79
113
 
80
114
  ```bash
81
- cd /path/to/your/project
82
115
  agtrace init
83
116
  ```
84
117
 
85
- ### 2. Start Your AI Coding Agent
118
+ ### 1) Open Your Project Directory (CWD matters)
86
119
 
87
- In one terminal, launch your usual AI coding agent:
120
+ `agtrace` scopes monitoring by the **current working directory (cwd)**.
88
121
 
89
- ```bash
90
- # Example: Claude Code
91
- claude
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.
92
123
 
93
- # Or Codex, Gemini, etc.
124
+ ```bash
125
+ cd /path/to/your/project
94
126
  ```
95
127
 
96
- ### 3. Watch in Another Terminal
128
+ ### 2) Start `watch` (either order works)
97
129
 
98
- Open a separate terminal pane in the same project directory and run:
130
+ In one terminal pane (from the project directory), run:
99
131
 
100
132
  ```bash
101
133
  agtrace watch
102
134
  ```
103
135
 
104
- That's it. No integration required—agtrace automatically detects and monitors your agent session.
136
+ `watch` can be started before or after your AI coding agent.
105
137
 
106
- * **Visualizes:** Context Window usage, Cost, Turns, and Last Activity.
107
- * **Auto-Switch:** When you start a new session, agtrace automatically latches onto it.
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.
108
141
 
109
- ### 4. Analyze Past Sessions
142
+ ### 3) Start Your AI Coding Agent (Same CWD)
110
143
 
111
- List recent sessions across all providers or inspect a specific one.
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
112
163
 
113
164
  ```bash
114
165
  # List recent sessions
115
166
  agtrace session list
116
167
 
117
- # Show analysis of a specific session (Context usage, turns, models)
168
+ # Inspect a specific session (context usage, turns, models)
118
169
  agtrace session show <session_id>
119
-
120
170
  ```
121
171
 
122
- ### 5. Advanced: The "Lab"
172
+ ### 5) Advanced: The Lab
123
173
 
124
- Debug agent interactions or search for specific patterns (e.g., "When did the agent try to write to `package.json`?").
174
+ Debug agent interactions or search for specific patterns, e.g. “When did the agent try to write to `package.json`?”:
125
175
 
126
176
  ```bash
127
177
  # Find all file write operations across history
128
178
  agtrace lab grep "write_file" --json
129
179
 
130
- # Inspect raw provider event (useful for debugging schema changes)
180
+ # Inspect a raw provider event (useful for debugging schema changes)
131
181
  agtrace lab grep "mcp" --raw --limit 1
132
-
133
182
  ```
134
183
 
135
184
  ---
136
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
+ ---
192
+
137
193
  ## 🏗️ Architecture
138
194
 
139
- agtrace is designed with **"Pointer-Based"** and **"Schema-on-Read"** philosophies:
195
+ agtrace is designed around **pointer-based indexing** and **schema-on-read**:
196
+
197
+ 1. **No Data Duplication**
198
+ agtrace does not copy your massive log files. It indexes metadata and points to the original logs.
140
199
 
141
- 1. **No Data Duplication:** We don't copy your massive log files. We index metadata and point to the original logs.
142
- 2. **Resilience:** Provider log schemas change frequently. agtrace parses logs at read-time, meaning a schema update won't corrupt your historical index.
143
- 3. **Project Isolation:** Sessions are grouped by project root hash, keeping your workspaces clean
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.
144
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
+ ---
145
207
 
146
208
  ## 🤝 Supported Providers
147
209
 
@@ -153,4 +215,4 @@ agtrace is designed with **"Pointer-Based"** and **"Schema-on-Read"** philosophi
153
215
 
154
216
  ## 📜 License
155
217
 
156
- This project is dual-licensed under the MIT and Apache 2.0 licenses.
218
+ 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.6"
26
+ "version": "0.1.8"
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.6"
518
+ "version": "0.1.8"
519
519
  }
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.1.6",
2
+ "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.1.8",
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.6",
96
+ "version": "0.1.8",
97
97
  "volta": {
98
98
  "node": "18.14.1",
99
99
  "npm": "9.5.0"