@lanegrid/agtrace 0.5.4 → 0.5.5

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 +21 -0
  2. package/README.md +53 -74
  3. package/npm-shrinkwrap.json +2 -2
  4. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,27 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [0.5.5] - 2026-01-06
6
+
7
+ ### Documentation
8
+
9
+ - Add feedback section with link to discussion ([403a011](https://github.com/lanegrid/agtrace/commit/403a0115332bebed2ddfcf197133e9907b3866cc))
10
+
11
+ - Add RFC links for watch TUI and MCP tools ([ac601bb](https://github.com/lanegrid/agtrace/commit/ac601bb2cb36f904f8d687004581d070d16757bb))
12
+
13
+ - Rewrite README with authentic dogfooding experience ([46e200b](https://github.com/lanegrid/agtrace/commit/46e200bed8eb4d7420c83f606d442525422778b2))
14
+
15
+
16
+ ### Features
17
+
18
+ - *(sdk)* Add Providers type for lightweight operations without database ([f738160](https://github.com/lanegrid/agtrace/commit/f7381606d5115457b0f382a08dec2039ac8aa59a))
19
+
20
+
21
+ ### Miscellaneous Tasks
22
+
23
+ - *(sdk)* Remove debug examples ([5671ffd](https://github.com/lanegrid/agtrace/commit/5671ffd280b34412b622a86e1b0542671e983a99))
24
+
25
+
5
26
  ## [0.5.4] - 2026-01-05
6
27
 
7
28
  ### Bug Fixes
package/README.md CHANGED
@@ -1,120 +1,99 @@
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>Observability for AI Agents</strong></p>
5
- <p>Local-first monitoring for Claude Code, Codex, and Gemini.</p>
4
+ <p><strong>See What Your AI Agent Is Actually Doing</strong></p>
6
5
 
7
6
  [![npm](https://img.shields.io/npm/v/@lanegrid/agtrace.svg?style=flat&label=npm)](https://www.npmjs.com/package/@lanegrid/agtrace)
8
- [![crates.io](https://img.shields.io/crates/v/agtrace-sdk.svg?label=SDK)](https://crates.io/crates/agtrace-sdk)
7
+ [![crates.io](https://img.shields.io/crates/v/agtrace.svg?label=crates.io)](https://crates.io/crates/agtrace)
9
8
  </div>
10
9
 
11
10
  ---
12
11
 
13
- ![agtrace watch demo](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)
12
+ ## The Problem I Had
13
+
14
+ When I started using AI coding agents (Claude Code, Codex, Gemini), I realized I was working with a **black box**. I couldn't see:
15
+
16
+ - How much of the context window was being consumed
17
+ - What the agent was actually doing between my prompts
18
+ - When the conversation was getting too long and performance would degrade
19
+
20
+ I found myself *guessing* the agent's internal state. That felt wrong.
21
+
22
+ ## What Changed
23
+
24
+ Now I always run **agtrace** alongside my coding agent. It's become essential.
14
25
 
15
- **agtrace** monitors AI agent sessions in real-time and lets agents query their own execution history via MCP.
26
+ ![agtrace with Claude Code](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/images/agtrace_live_use_screenshot.png)
16
27
 
17
- - **Zero instrumentation** — Auto-discovers provider logs
18
- - **100% local** — Privacy by design, no cloud dependencies
19
- - **Universal timeline** — Unified view across all providers
28
+ What I see:
29
+ - **Context window usage** — A color-coded bar showing how full the conversation is
30
+ - **Token consumption trends** — How much context each task uses over time
31
+ - **Live activity** — Tool calls, file reads, reasoning traces as they happen
32
+
33
+ For the first time, I can make informed decisions about when to start a new session, how to scope my requests, and whether the agent is stuck in a loop.
34
+
35
+ ---
36
+
37
+ ![agtrace watch demo](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)
20
38
 
21
- ## Quick Start
39
+ ## Try It
22
40
 
23
41
  ```bash
24
42
  npm install -g @lanegrid/agtrace
25
43
  cd my-project
26
- agtrace init # Initialize workspace (one-time setup)
27
- agtrace watch # Launch live dashboard
44
+ agtrace init # One-time setup
45
+ agtrace watch # Launch dashboard in a separate terminal
28
46
  ```
29
47
 
30
- ## MCP: Let Agents Query Their Own History
48
+ Works with Claude Code, Codex (OpenAI), and Gemini. Zero config — just discovers existing logs.
31
49
 
32
- Connect your AI assistant to search past sessions via [Model Context Protocol](https://modelcontextprotocol.io):
50
+ ## Give Your Agent Memory of Past Sessions
51
+
52
+ One thing I didn't expect: agents can also query their own execution history via [MCP](https://modelcontextprotocol.io):
33
53
 
34
- **Claude Code:**
35
54
  ```bash
55
+ # Claude Code
36
56
  claude mcp add agtrace -- agtrace mcp serve
37
- ```
38
57
 
39
- **Codex (OpenAI):**
40
- ```bash
58
+ # Codex
41
59
  codex mcp add agtrace -- agtrace mcp serve
42
60
  ```
43
61
 
44
- **Claude Desktop:**
45
- Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
46
- ```json
47
- {
48
- "mcpServers": {
49
- "agtrace": {
50
- "command": "agtrace",
51
- "args": ["mcp", "serve"]
52
- }
53
- }
54
- }
55
- ```
56
-
57
- Your agent can now:
58
- - Search past sessions for tool calls and errors
59
- - Retrieve tool calls and results from previous work
60
- - Analyze failure patterns
61
-
62
- **Example queries:**
63
- - *"Show me sessions with failures in the last hour"*
64
- - *"Search for tool calls that modified the database schema"*
65
- - *"Analyze the most recent session for performance issues"*
62
+ Now your agent can search what it did yesterday, find past errors, and learn from previous sessions.
66
63
 
67
- For detailed setup and examples, see the [MCP Integration Guide](docs/mcp-integration.md).
64
+ See the [MCP Integration Guide](docs/mcp-integration.md) for more.
68
65
 
69
- ## CLI Commands
70
-
71
- Debug and inspect agent behavior manually:
66
+ ## Other Commands
72
67
 
73
68
  ```bash
74
- agtrace watch # Live TUI dashboard
75
- agtrace session list # Browse session history
76
- agtrace lab grep "error" # Search across sessions
69
+ agtrace session list # Browse past sessions
70
+ agtrace lab grep "error" # Search across all sessions
77
71
  ```
78
72
 
79
- ## Building with the SDK
73
+ ## For Tool Builders
80
74
 
81
- Embed agent observability into your own tools (dashboards, IDE plugins, custom analytics).
75
+ If you're building your own IDE plugin, dashboard, or observability tool:
82
76
 
83
77
  ```toml
84
78
  [dependencies]
85
79
  agtrace-sdk = "0.5"
86
80
  ```
87
81
 
88
- ```rust
89
- use agtrace_sdk::{Client, types::SessionFilter};
90
-
91
- let client = Client::connect_default().await?;
92
- let sessions = client.sessions().list(SessionFilter::all())?;
93
- if let Some(summary) = sessions.first() {
94
- let handle = client.sessions().get(&summary.id)?;
95
- let session = handle.assemble()?;
96
- println!("{} turns, {} tokens",
97
- session.turns.len(),
98
- session.stats.total_tokens);
99
- }
100
- ```
101
-
102
- See [SDK Documentation](https://docs.rs/agtrace-sdk), [Examples](crates/agtrace-sdk/examples/), and [SDK README](crates/agtrace-sdk/README.md).
82
+ See [SDK Documentation](https://docs.rs/agtrace-sdk) and [Examples](crates/agtrace-sdk/examples/).
103
83
 
104
- ## Supported Providers
84
+ ## Documentation
105
85
 
106
- - **Claude Code** (Anthropic)
107
- - **Codex** (OpenAI)
108
- - **Gemini** (Google)
86
+ - [Getting Started](docs/getting-started.md)
87
+ - [MCP Integration](docs/mcp-integration.md)
88
+ - [Architecture](docs/architecture.md)
89
+ - [Full Documentation](docs/README.md)
109
90
 
110
- ## Documentation
91
+ ## Feedback
111
92
 
112
- - [Getting Started](docs/getting-started.md) - Detailed installation and usage guide
113
- - [MCP Integration](docs/mcp-integration.md) - Connect agents to their execution history
114
- - [Architecture](docs/architecture.md) - Platform design and principles
115
- - [Why agtrace?](docs/motivation.md) - Understanding the problem and solution
116
- - [Full Documentation](docs/README.md) - Commands, FAQs, and more
93
+ Have ideas?
94
+ - [RFC: Watch TUI Display](https://github.com/lanegrid/agtrace/discussions/36)
95
+ - [RFC: MCP Tools](https://github.com/lanegrid/agtrace/discussions/37)
117
96
 
118
97
  ## License
119
98
 
120
- Dual-licensed under the MIT and Apache 2.0 licenses.
99
+ MIT / Apache 2.0
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.5.4"
26
+ "version": "0.5.5"
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.5.4"
518
+ "version": "0.5.5"
519
519
  }
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.5.4",
2
+ "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.5.5",
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.5.4",
96
+ "version": "0.5.5",
97
97
  "volta": {
98
98
  "node": "18.14.1",
99
99
  "npm": "9.5.0"