You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
refactor: rename Recap back to Trace for AI model comprehension (#443)
* refactor: rename `Recap` back to `Trace` across entire codebase
AI models (Claude, GPT, etc.) struggle to understand "compare recaps" but
natively understand "compare traces" — `trace` is standard observability
terminology. This reverts the Tracer→Recap rename while keeping backward-
compat aliases for both `Tracer` and `Recap`.
**Source code (7 files):**
- Class `Recap` → `Trace` in `tracing.ts` with backward-compat aliases
- CLI command `recap` → `trace` with `recap` kept as hidden alias
- TUI slash command `/recap` → `/trace` with `recap` kept as alias
- Viewer branding: "Altimate Recap" → "Altimate Trace"
- All variable/function names updated (`sessionRecaps` → `sessionTraces`, etc.)
**Documentation (7 files):**
- `docs/configure/recap.md` → `docs/configure/trace.md`
- All doc references updated: CLI, TUI, CI/headless guides
- Image directory `assets/images/recap/` → `assets/images/trace/`
**Tests (12 files):**
- All imports updated `Recap` → `Trace`
- Variable shadowing fixed: `const trace: TraceFile` → `const traceFile`
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: address PR review comments
- Keep `traceViewerTracesDir` in sync on every URL request, not just
on first server creation (app.tsx)
- Reset per-session trace state (`sessionTraces`, `sessionUserMsgIds`)
when restarting the event stream in worker.ts
- Fix "traceFile" variable-style wording in test file comments to use
natural language ("trace file", "trace viewer", "trace list")
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: README.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -131,8 +131,8 @@ Manifest parsing, test generation, model scaffolding, incremental model detectio
131
131
### Data Visualization
132
132
Interactive charts and dashboards from SQL results. The data-viz skill generates publication-ready visualizations with automatic chart type selection based on your data.
133
133
134
-
### Local-First Recap
135
-
Built-in observability for AI interactions — recap tool calls, token usage, and session activity locally. No external services required. View recaps with `altimate recap`. Features include loop detection, post-session summary, and shareable HTML exports.
134
+
### Local-First Tracing
135
+
Built-in observability for AI interactions — trace tool calls, token usage, and session activity locally. No external services required. View session recordings with `altimate trace`. Features include loop detection, post-session summary, and shareable HTML exports.
136
136
137
137
### AI Teammate Training
138
138
Teach your AI teammate project-specific patterns, naming conventions, and best practices. The training system learns from examples and applies rules automatically across sessions.
Copy file name to clipboardExpand all lines: docs/docs/configure/trace.md
+53-56Lines changed: 53 additions & 56 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,31 +1,28 @@
1
-
# Recap
1
+
# Trace
2
2
3
-
Altimate Code captures detailed recaps of every session, including LLM generations, tool calls, token usage, cost, and timing, and saves them locally as JSON files. Recaps are invaluable for debugging agent behavior, optimizing cost, and understanding how the agent solves problems.
3
+
Altimate Code captures detailed traces (session recordings) of every session, including LLM generations, tool calls, token usage, cost, and timing, and saves them locally as JSON files. Traces are invaluable for debugging agent behavior, optimizing cost, and understanding how the agent solves problems.
4
4
5
-
Recap is **enabled by default** and requires no configuration. Recaps are stored locally and never leave your machine unless you configure a remote exporter.
5
+
Tracing is **enabled by default** and requires no configuration. Traces are stored locally and never leave your machine unless you configure a remote exporter.
The tracer feature has been renamed to **recap**. The `trace` command still works as a backward-compatible alias (`--no-trace` is the backward-compatible flag name). New features include loop detection, post-session summary, and shareable HTML exports.
|**Cost Attribution**| LLM cost + warehouse compute cost + storage delta = total cost, per user/team/project |
53
50
54
-
These attributes are purely optional. Recaps are valid without them. They're populated automatically by tools that have access to warehouse metadata.
51
+
These attributes are purely optional. Traces are valid without them. They're populated automatically by tools that have access to warehouse metadata.
55
52
56
53
## Configuration
57
54
@@ -70,12 +67,12 @@ Add to your config file (`~/.config/altimate-code/altimate-code.json` or project
70
67
71
68
| Option | Type | Default | Description |
72
69
|--------|------|---------|-------------|
73
-
|`enabled`|`boolean`|`true`| Enable or disable recap|
74
-
|`dir`|`string`|`~/.local/share/altimate-code/traces/`| Custom directory for recap files |
75
-
|`maxFiles`|`number`|`100`| Max recap files to keep (oldest pruned automatically). Set to `0` for unlimited |
70
+
|`enabled`|`boolean`|`true`| Enable or disable tracing|
71
+
|`dir`|`string`|`~/.local/share/altimate-code/traces/`| Custom directory for trace files |
72
+
|`maxFiles`|`number`|`100`| Max trace files to keep (oldest pruned automatically). Set to `0` for unlimited |
76
73
|`exporters`|`array`|`[]`| Remote HTTP exporters (see below) |
77
74
78
-
### Disabling Recap
75
+
### Disabling Tracing
79
76
80
77
```json
81
78
{
@@ -91,15 +88,15 @@ Or per-run with the `--no-trace` flag:
91
88
altimate-code run --no-trace "quick question"
92
89
```
93
90
94
-
## Viewing Recaps
91
+
## Viewing Traces
95
92
96
-
### List Recaps
93
+
### List Traces
97
94
98
95
```bash
99
-
altimate-code recap list
96
+
altimate-code trace list
100
97
```
101
98
102
-
Shows a table of recent recaps with session ID, timestamp, duration, tokens, cost, tool calls, and status.
99
+
Shows a table of recent traces with session ID, timestamp, duration, tokens, cost, tool calls, and status.
103
100
104
101
```
105
102
SESSION WHEN DURATION TOKENS COST TOOLS STATUS PROMPT
@@ -112,17 +109,17 @@ Options:
112
109
113
110
| Flag | Description |
114
111
|------|-------------|
115
-
|`-n`, `--limit`| Number of recaps to show (default: 20) |
112
+
|`-n`, `--limit`| Number of traces to show (default: 20) |
116
113
117
-
### View a Recap
114
+
### View a Trace
118
115
119
116
```bash
120
-
altimate-code recap view <session-id>
117
+
altimate-code trace view <session-id>
121
118
```
122
119
123
-
Opens a local web server with an interactive recap viewer in your browser.
120
+
Opens a local web server with an interactive trace viewer in your browser.
124
121
125
-
122
+
126
123
127
124
The viewer has 5 tabs:
128
125
@@ -148,35 +145,35 @@ Options:
148
145
|`--port`| Port for the viewer server (default: random) |
149
146
|`--live`| Auto-refresh every 2s for in-progress sessions |
150
147
151
-
Partial session ID matching is supported. For example, `altimate-code recap view abc` matches `abc123def456`.
148
+
Partial session ID matching is supported. For example, `altimate-code trace view abc` matches `abc123def456`.
152
149
153
150
### Live Viewing (In-Progress Sessions)
154
151
155
-
Recaps are written incrementally. After every tool call and generation, a snapshot is flushed to disk. This means you can view a recap while the session is still running:
152
+
Traces are written incrementally. After every tool call and generation, a snapshot is flushed to disk. This means you can view a trace while the session is still running:
156
153
157
154
```bash
158
155
# In terminal 1: run a long task
159
156
altimate-code run "refactor the entire pipeline"
160
157
161
-
# In terminal 2: watch the recap live
162
-
altimate-code recap view <session-id> --live
158
+
# In terminal 2: watch the trace live
159
+
altimate-code trace view <session-id> --live
163
160
```
164
161
165
162
The `--live` flag adds a green "LIVE" indicator and polls for updates every 2 seconds. The page auto-refreshes when new spans appear.
166
163
167
164
### From the TUI
168
165
169
-
Type `/recap` in the TUI to open a recap history dialog listing all recent sessions. Select any recap to open it in your browser with the interactive viewer. The current session appears at the top, and recaps are grouped by date with duration and timestamp info.
166
+
Type `/trace` in the TUI to open a trace history dialog listing all recent sessions. Select any trace to open it in your browser with the interactive viewer. The current session appears at the top, and traces are grouped by date with duration and timestamp info.
170
167
171
168
The viewer launches in live mode automatically for in-progress sessions, so you can watch spans appear as the agent works.
172
169
173
-
### Sharing Recaps
170
+
### Sharing Traces
174
171
175
-
The recap viewer includes a **Share** button that exports a self-contained HTML file. This file includes all session data and can be opened in any browser without a server — perfect for sharing with teammates, attaching to tickets, or archiving sessions.
172
+
The trace viewer includes a **Share Trace** button that exports a self-contained HTML file. This file includes all session data and can be opened in any browser without a server — perfect for sharing with teammates, attaching to tickets, or archiving sessions.
176
173
177
174
## Remote Exporters
178
175
179
-
Recaps can be sent to remote backends via HTTP POST. Each exporter receives the full recap JSON on session completion.
176
+
Traces can be sent to remote backends via HTTP POST. Each exporter receives the full trace JSON on session completion.
180
177
181
178
```json
182
179
{
@@ -197,7 +194,7 @@ Recaps can be sent to remote backends via HTTP POST. Each exporter receives the
197
194
| Field | Type | Description |
198
195
|-------|------|-------------|
199
196
|`name`|`string`| Identifier for this exporter (used in logs) |
200
-
|`endpoint`|`string`| HTTP endpoint to POST recap JSON to |
197
+
|`endpoint`|`string`| HTTP endpoint to POST trace JSON to |
@@ -208,9 +205,9 @@ Recaps can be sent to remote backends via HTTP POST. Each exporter receives the
208
205
- Exporters have a 10-second timeout
209
206
- All export operations are best-effort and never crash the CLI
210
207
211
-
## Recap File Format
208
+
## Trace File Format
212
209
213
-
Recaps are stored as JSON files in the traces directory. The schema is versioned for forward compatibility.
210
+
Traces are stored as JSON files in the traces directory. The schema is versioned for forward compatibility.
214
211
215
212
```json
216
213
{
@@ -322,15 +319,15 @@ All domain-specific attributes use the `de.*` prefix and are stored in the `attr
322
319
323
320
## Crash Recovery
324
321
325
-
Recaps are designed to survive process crashes:
322
+
Traces are designed to survive process crashes:
326
323
327
-
1.**Immediate snapshot.** A recap file is written as soon as the session starts, before any LLM interaction. Even if the process crashes immediately, a minimal recap file exists.
324
+
1.**Immediate snapshot.** A trace file is written as soon as the session starts, before any LLM interaction. Even if the process crashes immediately, a minimal trace file exists.
328
325
329
-
2.**Incremental snapshots.** After every tool call and generation completion, the recap file is updated atomically (write to temp file, then rename). The file on disk always contains a valid, complete JSON document.
326
+
2.**Incremental snapshots.** After every tool call and generation completion, the trace file is updated atomically (write to temp file, then rename). The file on disk always contains a valid, complete JSON document.
330
327
331
-
3.**Crash handlers.** The `run` command registers `SIGINT`/`SIGTERM`/`beforeExit` handlers that flush the recap synchronously with a `"crashed"` status.
328
+
3.**Crash handlers.** The `run` command registers `SIGINT`/`SIGTERM`/`beforeExit` handlers that flush the trace synchronously with a `"crashed"` status.
332
329
333
-
4.**Status indicators.**Recap status tells you exactly what happened:
330
+
4.**Status indicators.**Trace status tells you exactly what happened:
334
331
335
332
| Status | Meaning |
336
333
|--------|---------|
@@ -339,31 +336,31 @@ Recaps are designed to survive process crashes:
339
336
|`running`| Session is still in progress (visible in live mode) |
340
337
|`crashed`| Process was interrupted before the session completed |
341
338
342
-
Crashed recaps contain all data up to the last successful snapshot. You can view them normally with `altimate-code recap view`.
339
+
Crashed traces contain all data up to the last successful snapshot. You can view them normally with `altimate-code trace view`.
343
340
344
-
## Historical Recaps
341
+
## Historical Traces
345
342
346
-
All recaps are stored in the traces directory and persist across sessions. Use `recap list` to browse history:
343
+
All traces are stored in the traces directory and persist across sessions. Use `trace list` to browse history:
347
344
348
345
```bash
349
-
# Show the last 50 recaps
350
-
altimate-code recap list -n 50
346
+
# Show the last 50 traces
347
+
altimate-code trace list -n 50
351
348
352
-
# View any historical recap
353
-
altimate-code recap view <session-id>
349
+
# View any historical trace
350
+
altimate-code trace view <session-id>
354
351
```
355
352
356
-
Recaps are automatically pruned when `maxFiles` is exceeded (default: 100). The oldest recaps are removed first. Set `maxFiles: 0` for unlimited retention.
353
+
Traces are automatically pruned when `maxFiles` is exceeded (default: 100). The oldest traces are removed first. Set `maxFiles: 0` for unlimited retention.
357
354
358
355
## Privacy
359
356
360
-
Recaps are stored **locally only** by default. They contain:
357
+
Traces are stored **locally only** by default. They contain:
If you configure remote exporters, recap data is sent to those endpoints. No recap data is included in the anonymous telemetry described in [Telemetry](../reference/telemetry.md).
363
+
If you configure remote exporters, trace data is sent to those endpoints. No trace data is included in the anonymous telemetry described in [Telemetry](../reference/telemetry.md).
367
364
368
365
!!! warning "Sensitive Data"
369
-
Recaps may contain SQL queries, file paths, and command outputs from your session. If you share recap files or configure remote exporters, be aware that this data will be included.
366
+
Traces may contain SQL queries, file paths, and command outputs from your session. If you share trace files or configure remote exporters, be aware that this data will be included.
Copy file name to clipboardExpand all lines: docs/docs/usage/cli.md
+8-10Lines changed: 8 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,7 +33,7 @@ altimate --agent analyst
33
33
|`export`| Export session data |
34
34
|`import`| Import session data |
35
35
|`session`| Session management |
36
-
|`recap`| List and view session recaps (formerly `trace`) |
36
+
|`trace`| List and view session traces (recordings of agent sessions) |
37
37
|`github`| GitHub integration |
38
38
|`pr`| Pull request tools |
39
39
|`upgrade`| Upgrade to latest version |
@@ -149,22 +149,20 @@ altimate run --model anthropic/claude-sonnet-4-6 "optimize my warehouse"
149
149
# Print logs for debugging
150
150
altimate --print-logs --log-level DEBUG run "test query"
151
151
152
-
# Disable recap for a single run (--no-trace is the backward-compatible flag name)
152
+
# Disable tracing for a single run
153
153
altimate run --no-trace "quick question"
154
154
```
155
155
156
156
For CI pipelines and headless automation, see [CI & Automation](ci-headless.md).
157
157
158
-
## Recap
158
+
## Trace
159
159
160
-
Every `run` command automatically saves a recap file with the full session details, including generations, tool calls, tokens, cost, and timing. See [Recap](../configure/recap.md) for configuration options.
160
+
Every `run` command automatically saves a trace file (a recording of the agent session) with the full session details, including generations, tool calls, tokens, cost, and timing. See [Trace](../configure/trace.md) for configuration options.
161
161
162
162
```bash
163
-
# List recent recaps
164
-
altimate recap list
163
+
# List recent traces
164
+
altimate trace list
165
165
166
-
# View a recap in the browser
167
-
altimate recap view <session-id>
166
+
# View a trace in the browser
167
+
altimate trace view <session-id>
168
168
```
169
-
170
-
> **Note:** The `trace` command still works as a backward-compatible alias for `recap`.
0 commit comments