@lanegrid/agtrace 0.1.1 → 0.1.3
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 +61 -0
- package/README.md +141 -0
- package/npm-shrinkwrap.json +2 -2
- package/package.json +2 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
## [0.1.3] - 2025-12-25
|
|
6
|
+
|
|
7
|
+
### Bug Fixes
|
|
8
|
+
|
|
9
|
+
- Compute project_hash from SessionIndex.project_root instead of hardcoded 'unknown' (fixes #1) (#2) ([aca561a](https://github.com/lanegrid/agtrace/commit/aca561a282968cce9163e48fc7bedc0fe0fb938c))
|
|
10
|
+
|
|
11
|
+
- Ensure_index_is_fresh derives project_hash from cwd and respects --all-projects flag ([5615036](https://github.com/lanegrid/agtrace/commit/5615036a49692f72941d5a352f5663cb1c759339))
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
### Testing
|
|
15
|
+
|
|
16
|
+
- Add comprehensive integration tests for edge cases and project isolation ([bf75867](https://github.com/lanegrid/agtrace/commit/bf75867643157744a060a6f8f00f3af16b9a30f8))
|
|
17
|
+
|
|
18
|
+
- Fix project isolation tests with proper cwd/sessionId replacement to catch real bugs ([dacfc2f](https://github.com/lanegrid/agtrace/commit/dacfc2faca4fc0b33c833ddd3d3deeba90265397))
|
|
19
|
+
|
|
20
|
+
- Fix compilation errors in scan_legacy_project_hash_test and improve test helper formatting ([0d474a4](https://github.com/lanegrid/agtrace/commit/0d474a437a9bb26dabda3403887759b5ac035faf))
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
24
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
25
|
+
|
|
26
|
+
## [Unreleased]
|
|
27
|
+
|
|
28
|
+
## [0.1.2] - 2025-12-25
|
|
29
|
+
|
|
30
|
+
### Added
|
|
31
|
+
|
|
32
|
+
- Initial public release on crates.io and npm
|
|
33
|
+
- Core library APIs for AI agent log analysis
|
|
34
|
+
- Multi-provider normalization (Claude Code, Codex, Gemini)
|
|
35
|
+
- Session parsing and event stream processing
|
|
36
|
+
- SQLite-based indexing with schema-on-read architecture
|
|
37
|
+
- CLI commands:
|
|
38
|
+
- `init` - Initialize workspace and detect providers
|
|
39
|
+
- `list` - Show session history
|
|
40
|
+
- `show` - Display session details with token usage
|
|
41
|
+
- `watch` - Real-time TUI dashboard for live sessions
|
|
42
|
+
- `doctor` - Verify configuration and database integrity
|
|
43
|
+
- `lab grep` - Search across sessions with regex and JSON output
|
|
44
|
+
- Features:
|
|
45
|
+
- Live context window monitoring
|
|
46
|
+
- Token usage tracking (input/output/cache/reasoning)
|
|
47
|
+
- Provider-agnostic event normalization
|
|
48
|
+
- Local-only processing (no cloud dependencies)
|
|
49
|
+
- Zero-overhead monitoring with Rust performance
|
|
50
|
+
|
|
51
|
+
### Fixed
|
|
52
|
+
|
|
53
|
+
- Prevent panic when session_id is shorter than 8 characters in watch mode
|
|
54
|
+
|
|
55
|
+
## [0.1.1] - 2025-12-25
|
|
56
|
+
|
|
57
|
+
_Internal development release - not published to crates.io or npm_
|
|
58
|
+
|
|
59
|
+
## [0.1.0] - 2025-12-25
|
|
60
|
+
|
|
61
|
+
_Internal development release - not published to crates.io or npm_
|
package/README.md
CHANGED
|
@@ -1 +1,142 @@
|
|
|
1
1
|
# agtrace
|
|
2
|
+
|
|
3
|
+
**The Vital Monitor for AI Coding Agents.**
|
|
4
|
+
|
|
5
|
+
Real-time telemetry, context window tracking, and session forensics for Claude Code, Codex, and Gemini. **Built in Rust for zero-overhead monitoring.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@lanegrid/agtrace)
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 📉 The Problem: "Context Window Anxiety"
|
|
12
|
+
|
|
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.
|
|
14
|
+
|
|
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.
|
|
16
|
+
|
|
17
|
+
You are effectively flying a plane without a fuel gauge.
|
|
18
|
+
|
|
19
|
+
## ⚡ The Solution: agtrace
|
|
20
|
+
|
|
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.
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
*The dashboard showing Context Window usage, current turn, and token costs*
|
|
26
|
+
|
|
27
|
+
### Key Features
|
|
28
|
+
|
|
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.
|
|
31
|
+
|
|
32
|
+
* **🔌 Provider Normalization**
|
|
33
|
+
Whether you use `Claude Code`, `Codex`, or `Gemini`, agtrace normalizes the events into a standard format.
|
|
34
|
+
|
|
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.).
|
|
37
|
+
|
|
38
|
+
* **🚀 Auto-Tracking**
|
|
39
|
+
The `watch` command automatically detects new sessions as they are created. Just keep it running in a separate terminal pane.
|
|
40
|
+
|
|
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.
|
|
43
|
+
|
|
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.
|
|
46
|
+
|
|
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.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 📦 Installation
|
|
53
|
+
|
|
54
|
+
We recommend installing `agtrace` globally for the best performance and quick access to the `watch` command.
|
|
55
|
+
|
|
56
|
+
### via npm (Recommended)
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
npm install -g @lanegrid/agtrace
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### ⚡ Or use via npx
|
|
63
|
+
|
|
64
|
+
If you prefer not to install it globally, you can run commands using `npx`.
|
|
65
|
+
*Note: In the examples below, replace `agtrace` with `npx @lanegrid/agtrace`.*
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
npx @lanegrid/agtrace@latest init
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## 🚀 Quick Start
|
|
75
|
+
|
|
76
|
+
### 1. Initialize
|
|
77
|
+
|
|
78
|
+
Run this in your project root to detect installed providers (Claude, etc.) and index existing sessions.
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
agtrace init
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### 2. Watch Mode (The "Vital Check")
|
|
85
|
+
|
|
86
|
+
Open a new terminal pane and run the watch command. This will launch the TUI dashboard.
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
agtrace watch
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
* **Visualizes:** Context Window usage, Cost, Turns, and Last Activity.
|
|
93
|
+
* **Auto-Switch:** When you start a `claude` or `codex` session in another pane, agtrace automatically latches onto the new log file.
|
|
94
|
+
|
|
95
|
+
### 3. Analyze Past Sessions
|
|
96
|
+
|
|
97
|
+
List recent sessions across all providers or inspect a specific one.
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
# List recent sessions
|
|
101
|
+
agtrace session list
|
|
102
|
+
|
|
103
|
+
# Show analysis of a specific session (Context usage, turns, models)
|
|
104
|
+
agtrace session show <session_id>
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### 4. Advanced: The "Lab"
|
|
109
|
+
|
|
110
|
+
Debug agent interactions or search for specific patterns (e.g., "When did the agent try to write to `package.json`?").
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
# Find all file write operations across history
|
|
114
|
+
agtrace lab grep "write_file" --json
|
|
115
|
+
|
|
116
|
+
# Inspect raw provider event (useful for debugging schema changes)
|
|
117
|
+
agtrace lab grep "mcp" --raw --limit 1
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 🏗️ Architecture
|
|
124
|
+
|
|
125
|
+
agtrace is designed with **"Pointer-Based"** and **"Schema-on-Read"** philosophies:
|
|
126
|
+
|
|
127
|
+
1. **No Data Duplication:** We don't copy your massive log files. We index metadata and point to the original logs.
|
|
128
|
+
2. **Resilience:** Provider log schemas change frequently. agtrace parses logs at read-time, meaning a schema update won't corrupt your historical index.
|
|
129
|
+
3. **Project Isolation:** Sessions are grouped by project root hash, keeping your workspaces clean
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
## 🤝 Supported Providers
|
|
133
|
+
|
|
134
|
+
* **Claude Code** (Anthropic)
|
|
135
|
+
* **Codex** (OpenAI)
|
|
136
|
+
* **Gemini** (Google)
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## 📜 License
|
|
141
|
+
|
|
142
|
+
This project is 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.3"
|
|
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.3"
|
|
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.3",
|
|
3
3
|
"bin": {
|
|
4
4
|
"agtrace": "run-agtrace.js"
|
|
5
5
|
},
|
|
@@ -83,7 +83,7 @@
|
|
|
83
83
|
"zipExt": ".tar.xz"
|
|
84
84
|
}
|
|
85
85
|
},
|
|
86
|
-
"version": "0.1.
|
|
86
|
+
"version": "0.1.3",
|
|
87
87
|
"volta": {
|
|
88
88
|
"node": "18.14.1",
|
|
89
89
|
"npm": "9.5.0"
|