@lanegrid/agtrace 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.1] - 2026-01-03
+
+### Bug Fixes
+
+- Unify top-level help message between -h and --help ([5631f15](https://github.com/lanegrid/agtrace/commit/5631f15e0b7aeea3aebdc7a1b7c347fa29c9692f))
+
+
+### Documentation
+
+- Add MCP troubleshooting for Node.js version managers ([0f99972](https://github.com/lanegrid/agtrace/commit/0f999728ef04e7b2cd6742de6ca4250c467906ce))
+
+- Modernize MCP messaging and restructure README around watch and mcp values ([ef14681](https://github.com/lanegrid/agtrace/commit/ef146816220164b4e80b0104e836faa2214e732a))
+
+- Fix Gemini CLI mcp add syntax (uses positional args, not -- separator) ([e458773](https://github.com/lanegrid/agtrace/commit/e4587732bac670a9228a6c44afde375744e8679c))
+
+- Note Gemini CLI not yet supported (requires Content-Length framing) ([43a745d](https://github.com/lanegrid/agtrace/commit/43a745d130d9ac367201a01e382db72878a9710f))
+
+
+### Refactor
+
+- Update MCP tools from get_session_details/search_events to specialized tools ([31a7919](https://github.com/lanegrid/agtrace/commit/31a791934b2c52cdbf271b19fc6e5768004fc9bc))
+
+- Reorder subcommands by importance and improve descriptions ([59ad2eb](https://github.com/lanegrid/agtrace/commit/59ad2eb31943ddd5c3ec679cd588d88a503c86a1))
+
+- Hide less-used global options in -h to shorten help output ([8589bf0](https://github.com/lanegrid/agtrace/commit/8589bf09987c29edb26a19b1b1b7f85fdbdf0c86))
+
+
 ## [0.4.0] - 2026-01-02
 
 ### Bug Fixes

package/README.md

@@ -12,41 +12,57 @@
 
 ![agtrace watch demo](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)
 
-**agtrace** provides a unified timeline and analysis layer for fragmented AI agent logs.
-Use the **CLI** for instant visualization, or build custom monitoring tools with the **SDK**.
+**agtrace** is an observability platform for AI agent execution traces.
+Local-first, privacy-preserving, and zero-instrumentation.
 
-## 🌟 Core Value
+## Two Ways to Use agtrace
 
-1. **Universal Normalization**: Converts diverse provider logs (Claude, Gemini, etc.) into a standard `AgentEvent` model.
-2. **Schema-on-Read**: Resilient to provider updates. No database migrations needed.
-3. **Local-First**: 100% offline. Privacy by design.
-4. **Zero-Instrumentation**: Automatically detects and watches logs from standard locations (`~/.claude/projects`, `~/.codex/sessions`, `~/.gemini/tmp`). No code changes required.
+### 1. 🔍 Live Monitoring with `watch`
 
-## 🚀 Quick Start (CLI)
+Real-time TUI dashboard for agent sessions. Like `top` + `tail -f` for AI agents.
 
-The reference implementation of the agtrace platform.
+- **100% local and offline** — Privacy by design, no cloud dependencies
+- **Auto-discovery** — Finds logs from Claude Code, Codex, and Gemini automatically
+- **Zero instrumentation** — No code changes or configuration needed
+- **Universal timeline** — Unified view across all providers
+
+### 2. 🤖 Agent Self-Reflection via MCP
+
+Connects to AI coding assistants via [Model Context Protocol](https://modelcontextprotocol.io), enabling agents to query their own execution history.
+
+- **Query past sessions** — "Show me sessions with failures in the last hour"
+- **Search across traces** — Find specific tool calls, events, or patterns
+- **Analyze performance** — Detect loops, failures, and bottlenecks
+- **Debug behavior** — Inspect reasoning chains and tool usage
+
+**Supported MCP clients:** Claude Code, Codex (OpenAI), Claude Desktop
+**Note:** Gemini CLI support is planned (requires Content-Length framing implementation)
+
+## 🚀 Quick Start
 
 ```bash
 npm install -g @lanegrid/agtrace
 cd my-project
-agtrace init      # initialize workspace (system data directory)
-agtrace watch     # live dashboard
+agtrace init      # Initialize workspace (one-time setup)
+agtrace watch     # Launch live dashboard
 ```
 
-## 🤖 AI-Native Observability (MCP)
+## 🔌 MCP Integration
 
-**New in v0.4.0**: Enable AI agents to query their own execution history.
+Enable agent self-reflection in your AI coding assistant:
 
-agtrace exposes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that allows AI assistants like Claude Desktop to:
-- Browse session history and analyze failures
-- Search event payloads across thousands of sessions
-- Run diagnostic analysis (failures, loops, bottlenecks)
-- Debug agent behavior without manual CLI commands
+**Claude Code:**
+```bash
+claude code mcp add agtrace -- agtrace mcp serve
+```
 
-### Setup with Claude Desktop
+**Codex (OpenAI):**
+```bash
+codex mcp add agtrace -- agtrace mcp serve
+```
 
+**Claude Desktop:**
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
-
 ```json
 {
   "mcpServers": {
@@ -58,20 +74,12 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-After restarting Claude Desktop, ask questions like:
-- *"Show me sessions from the last 2 hours that had failures"*
-- *"Search for all tool calls containing 'write_file'"*
+**Example queries after setup:**
+- *"Show sessions from the last hour with failures"*
+- *"Search for tool calls containing 'write_file'"*
 - *"Analyze the most recent session for performance issues"*
 
-### Available MCP Tools
-
-- `list_sessions` - Browse session history with filtering
-- `get_session_details` - Get session overview, turns, or full details
-- `analyze_session` - Run diagnostic analysis (failures, loops)
-- `search_events` - Search event payloads across sessions
-- `get_project_info` - List all indexed projects
-
-**See also**: Run `agtrace mcp serve --help` for details.
+For detailed setup instructions and troubleshooting, see the [MCP Integration Guide](docs/mcp-integration.md).
 
 ## 🛠️ Building with the SDK
 

package/npm-shrinkwrap.json

@@ -23,7 +23,7 @@
       "hasInstallScript": true,
       "license": "MIT OR Apache-2.0",
       "name": "@lanegrid/agtrace",
-      "version": "0.4.0"
+      "version": "0.4.1"
     },
     "node_modules/@isaacs/balanced-match": {
       "engines": {
@@ -515,5 +515,5 @@
     }
   },
   "requires": true,
-  "version": "0.4.0"
+  "version": "0.4.1"
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.4.0",
+  "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.4.1",
   "bin": {
     "agtrace": "run-agtrace.js"
   },
@@ -93,7 +93,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.4.0",
+  "version": "0.4.1",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"