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
{{ message }}
Repository navigation
feat: tool report-event for the Claude Code plugin's lineage report - #1718
What changes for users: the Claude Code plugin can count how its offline lineage report gets used: the summary shown, Open report pressed, /lineage-report run, and the report built, failed, or found no browser. This goes through altimate-code's usage telemetry, under its usual opt-out.
altimate-code tool report-event <action> --session claude:<id> sends one lineage_report event: the action, the Claude Code session id and a timestamp. Nothing else.
Any other action, or a session that isn't claude:<id>, exits 1 and sends nothing. So a path or a name can't ride along.
The event is added to the telemetry union and to the telemetry reference page.
Claims C1–C4 and residuals R1–R2 for review are in the review-log comment.
How did you verify your code works?
New tests for each of the six actions, refused actions, and refused sessions, including a path and an overlong id.
The command from source, with telemetry off: a valid call exits 0; a bad action and a bad session each exit 1 with the reason.
test/altimate/tool-cli and every telemetry test file, after merging main: 803 pass. The repo typecheck and Marker Guard pass. Linux only.
Cost side effects
None. One small usage event per action; no model calls, warehouse queries or cloud resources.
Checklist
I have tested my changes locally
I have not included unrelated changes in this PR
I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"
Adds a tool report-event command so the Claude Code plugin can record how its offline lineage report is used, through the existing altimate-code telemetry and its usual opt-out. The report page itself makes no network requests.
altimate-code tool report-event <action> --session claude:<id> sends one lineage_report event with the action, session id, and timestamp. Only the six defined actions and a claude: session id are accepted; anything else exits 1 and sends nothing. The event is added to the telemetry union and documented on the telemetry reference page.
New Features
Supports the actions summary_shown, open_pressed, command_run, built, build_failed, and no_browser.
Rejects paths, names, or non-claude: sessions, so no extra data can ride along.
Lists the command in altimate-code tool --help.
Requires no changes to existing commands or events.
Written for commit 354cbe8. Summary will update on new commits.
Summary by CodeRabbit
New Features
Added telemetry reporting for Claude Code lineage-report interactions, including summaries shown, reports opened or built, build failures, command runs, and unavailable browsers.
Added a CLI command to submit supported report events with a valid Claude Code session ID.
Documentation
Documented the event details, the exclusion of report content and identifying names, and that the report page makes no network requests.
- `altimate-code tool report-event <action> --session claude:<id>` sends one `lineage_report` usage event: the action and the session, no model, column or file names.
- Only the six report actions and a `claude:` session id are accepted; the telemetry opt-out drops it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VEmKQwEiHMwQ7BdwgPo9sb
No actionable comments were generated in the recent review.
Walkthrough
The change adds a lineage_report telemetry event, validates its action and Claude Code session ID through a new CLI command, submits valid events to telemetry, tests accepted and rejected inputs, and documents the event.
Changes: Lineage report telemetry
Layer / File(s)
Summary
Event contract and validation packages/opencode/src/altimate/telemetry/index.ts, packages/opencode/src/altimate/tool-cli/report-event.ts
The telemetry event defines six lineage-report actions. reportEvent validates the action and session ID, then returns the event with a supplied timestamp or the current time.
CLI submission and validation coverage packages/opencode/src/cli/cmd/tool.ts, packages/opencode/test/altimate/tool-cli/report-event.test.ts, docs/docs/reference/telemetry.md
The registered CLI command reports validation errors or submits valid events to telemetry. Tests cover valid actions and invalid actions and session IDs. The reference documents the event fields and excluded content.
sequenceDiagram
participant ToolReportEventCommand
participant reportEvent
participant Telemetry
ToolReportEventCommand->>reportEvent: action and session
reportEvent-->>ToolReportEventCommand: validated event or error
ToolReportEventCommand->>Telemetry: track valid event
Loading
Suggested reviewers:sahrizvi, hkaltai
Merge Risk: Minimal · up to 354cb
This adds a small, validated telemetry event and CLI command with tests and documentation. No merge-blocking risk was identified.
Pre-merge checks: 4
Check name
Status
Explanation
Title check
The title names the change: a new tool report-event command that records usage of the Claude Code plugin's lineage report. The changeset adds that command, the lineage_report telemetry event, the re…
Description check
The description follows the repository template. It has the issue link (Closes #1717), a checked type of change (New feature), a What does this PR do section that explains the new command, its validat…
Linked Issues check
[#1717] The coding requirements are: a tool report-event command, six accepted actions, a claude:<id> session check, a lineage_report telemetry event carrying only action and session, and a tele…
Out of Scope Changes check
All changed areas support #1717. These are the telemetry union member, the reportEvent helper, the report-event command registration in tool.ts, the unit tests for reportEvent, and the telemet…
Full details: Title check
Explanation
The title names the change: a new tool report-event command that records usage of the Claude Code plugin's lineage report. The changeset adds that command, the lineage_report telemetry event, the report-event helper, the CLI wiring, the docs entry, and tests. The title is specific and matches the main change.
Full details: Description check
Explanation
The description follows the repository template. It has the issue link (Closes #1717), a checked type of change (New feature), a What does this PR do section that explains the new command, its validation rules, and the event fields, a verification section with test and manual command results, and a cost side effects section that states None with a reason. The checklist items are checked. The description does not include a wrapper for the template's required prose beyond these sections, but all required sections are filled in.
Full details: Linked Issues check
Explanation
[#1717] The coding requirements are: a tool report-event command, six accepted actions, a claude:<id> session check, a lineage_report telemetry event carrying only action and session, and a telemetry reference entry. At head 354cbe8, packages/opencode/src/altimate/tool-cli/report-event.ts defines REPORT_ACTIONS with exactly the six actions. It requires the session to match ^claude:[A-Za-z0-9_-]{1,128}$. It returns { error } for any other input. A valid call returns { type: "lineage_report", timestamp, session_id, action }. cli/cmd/tool.ts registers report-event <action> --session. On error it prints the message and sets exit code 1. On success it calls Telemetry.track(event). The telemetry union and telemetry.md document the event. The opt-out relies on the existing Telemetry.track path. This review did not read that path directly. The PR reports a run with telemetry off that sent nothing. The background call from the plugin is outside this repository. The incremental diff from the previous reviewed head could not be read because changed blobs are missing from the checkout. The current code and summaries are consistent with the prior PASS. Tests cover the six actions and refused inputs, per the PR and test summary.
Full details: Out of Scope Changes check
Explanation
All changed areas support #1717. These are the telemetry union member, the reportEvent helper, the report-event command registration in tool.ts, the unit tests for reportEvent, and the telemetry reference entry. The tool.ts change is the new command block and its help text. It does not alter the existing commands. The commit message says the telemetry docs were clarified and a test pins the six actions. Both fit the issue. The incremental diff since the previous reviewed head could not be read, so this result relies on the current file contents and the PR summaries.
Finishing Touches
Generate unit tests (beta)
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
A rabbit taps the report command, Six actions hop at its demand. A session tag is checked with care, Valid events travel through the air. The docs now list the path they share.
Recent review info
Run configuration
Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: Repository UI
Review profile: CHILL
Plan: Advanced
Run ID: deb89851-bf88-447c-8341-b4f4cae2ef6b
Commits
Reviewing files that changed from the base of the PR and between 00e9116 and 354cbe8.
Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 1 remain after this review.
@codex review against the numbered claims (C1–C4) and the disclosed residuals (R1–R2) in the "Claims (for review)" section of this PR's description: report only a reproducible trace that violates a numbered claim. Instances of the disclosed residuals are not findings. A round with no claim violation ends review.
Claims (each can be violated by a concrete trace):
C1. A valid call sends at most one event, of type lineage_report, with exactly type, timestamp, session_id and action.
C2. An action outside the six, or a session that isn't claude: followed by 1–128 of [A-Za-z0-9_-], exits 1 and sends nothing.
C3. With telemetry turned off (ALTIMATE_TELEMETRY_DISABLED, OPENCODE_DISABLE_TELEMETRY or the config), nothing is sent.
C4. No other command or event changes; tool --help lists the new subcommand.
Disclosed residuals (accepted; instances are not findings):
R1. Like every altimate-code event, one from a machine signed in to Altimate carries its Altimate user ID.
R2. The event is buffered and flushed when the CLI exits, as for other commands; a process killed first loses it.
Round 1: Codex clean on 5f599dd. CI on 5f599dd caught the tool --help snapshot, which 00e9116 updates (test only). cubic on 00e9116: 2 findings, both fixed in 354cbe8 (the test pins the six actions; the docs row calls the action and session id the payload). cubic on 354cbe8: 0 issues.
The reason will be displayed to describe this comment to others. Learn more.
[SUGGESTION]: The six lineage-report actions are declared twice: here and in REPORT_ACTIONS (altimate/tool-cli/report-event.ts:8).
Adding an action to this union without adding it to REPORT_ACTIONS compiles Telemetry.track fine but advertises an action the CLI always rejects with exit 1; only the other direction (list first, union second) is caught by typecheck. Deriving the field from the single list (import type { ReportAction } from "../tool-cli/report-event", then action: ReportAction; the module has no imports, so the type-only edge is free) keeps the telemetry reference and the validator from drifting.
The reason will be displayed to describe this comment to others. Learn more.
Agreed this is a drift risk, but no fix in this PR: as it stands, the union and REPORT_ACTIONS hold the same six actions, and a test pins that list. Deriving the field from ReportAction with a type-only import is queued for a small follow-up, so this PR can go into today's release without another full CI run.
The reason will be displayed to describe this comment to others. Learn more.
[SUGGESTION]: These tests cover reportEvent() only; the CLI wiring the PR's claims describe (exit 1 and nothing tracked for a refused action or session) has no test.
test/altimate/tool-cli/cli.test.ts already spawns the real CLI through inShell with ALTIMATE_TELEMETRY_DISABLED=1, so a refused-action and a refused-session case (exit code 1, reason on stderr) is cheap and would lock in C2 end to end. Asserting the send path for C1/C3 could reuse the sink pattern from test/altimate/telemetry/* via APPLICATIONINSIGHTS_CONNECTION_STRING.
The reason will be displayed to describe this comment to others. Learn more.
Not in this PR. C2's CLI path was checked by hand from source: a valid call exits 0, and a bad action or a bad session each exits 1 with the reason and sends nothing. A spawned-CLI test of those exits in cli.test.ts, plus a sink check for C1 and C3, is queued for the same follow-up.
The reason will be displayed to describe this comment to others. Learn more.
[SUGGESTION]:docs/docs/usage/tool.md documents every other tool subcommand (list, context, run, daemon); this one is now user-visible in tool --help but has no entry there.
A short section saying it is the Claude Code plugin's hook, takes one of the six actions plus claude:<id>, and sends a single lineage_report event under the usual telemetry opt-out would keep the page complete and put the privacy contract where people reading tool docs will see it.
The reason will be displayed to describe this comment to others. Learn more.
Good point. A short report-event section in docs/docs/usage/tool.md (what calls it, the six actions, claude:<id>, one lineage_report event under the usual opt-out) is queued for the follow-up. Until then, the telemetry reference page describes the event.
Status: 3 Issues Found | Recommendation: Address before merge
Overview
Severity
Count
CRITICAL
0
WARNING
0
SUGGESTION
3
Verified the claimed behavior against the shipped CLI path: the command is registered under tool (src/cli/cmd/tool.ts:333), telemetry is initialised in the root middleware and the src/index.ts exit finally runs Telemetry.shutdown(), so the event is buffered pre-init and flushed on exit (claude:<id> validated by HOST_SESSION, so no path/name can ride along). telemetry.disabled in a project config is still honoured because the fallback reads project files from cwd. No unbounded cost path. Two things checked and deliberately not flagged: the .snap marker lines removed by snapshot regeneration (test paths are excluded from Marker Guard) and the new union member's markers (siblings, not nested).
Issue Details (click to expand)
SUGGESTION
File
Line
Issue
packages/opencode/src/altimate/telemetry/index.ts
928
Action union duplicates REPORT_ACTIONS; adding to the union alone compiles and advertises an action the CLI always rejects. Derive it from the list.
The reason will be displayed to describe this comment to others. Learn more.
Consensus review (panel: Claude as lead, and Codex): approve.
I ran the command from source against a local capture sink. A valid call sends one lineage_report with action, the claude:<id> session (in ai.session.id) and the timestamp, plus the shared envelope every event carries, and nothing from the cwd or project. ALTIMATE_TELEMETRY_DISABLED, OPENCODE_DISABLE_TELEMETRY and telemetry.disabled (global and project config) all suppress it. A bad action or session exits 1 with the reason and sends nothing from this command. A send that fails or hangs never changes the exit code. Marker guard ok (checked by hand too), typecheck passes, and test/altimate/tool-cli, test/cli/help and test/telemetry give 502 pass at head against 499 at base, with no regressions.
Remaining minors, none blocking (inline):
Help text says nothing is sent when telemetry is off, but the existing one-time telemetry_opted_out marker can be: wording about pre-existing, documented behaviour.
first_launch can go out with the event, even on a refused call: pre-existing once-per-install event, no data from the plugin.
A hanging endpoint holds the command for about 10 s: pre-existing flush budget, and the plugin calls it in the background.
The CLI wiring is untested and ALL_EVENT_TYPES omits the event: test-only, safe in the follow-up you queued.
The reason will be displayed to describe this comment to others. Learn more.
Minor (not blocking): the help text overstates the opt-out. With telemetry off, lineage_report is never sent (checked against a capture sink with each switch). But the first opted-out run on a machine that has a machine id still sends the one-time telemetry_opted_out marker, as docs/docs/reference/telemetry.md describes for every command. Suggest "usage telemetry, under the usual opt-out" here and the same in C3. Not blocking: wording about pre-existing, documented behaviour.
The reason will be displayed to describe this comment to others. Learn more.
Minor (not blocking): first_launch can go out with this command. The CLI middleware runs the welcome banner before this handler. When .installed-version is present, tool report-event bogus --session claude:abc exits 1 and still sends first_launch, and a valid call sends first_launch + lineage_report (reproduced). C1 and C2 hold for what this command adds; worth wording them that way. Not blocking: a pre-existing once-per-install event (version, is_upgrade, install_method, machine id) carrying nothing from the plugin.
The reason will be displayed to describe this comment to others. Learn more.
Minor (not blocking): a hanging endpoint holds the command for about 10 s. Against an endpoint that never answers, the call took 10.9 s and exited 0 (unreachable: 0.9 s, exit 0). That is the inherited Telemetry.shutdown() flush budget, and the failure is swallowed correctly. Not blocking, because #1717 says the plugin runs this in the background; just make sure the plugin never awaits it on the report path.
The reason will be displayed to describe this comment to others. Learn more.
Minor (not blocking): the CLI path is untested. These tests cover reportEvent() only. With Telemetry.track(event) and process.exitCode = 1 removed from the handler in tool.ts, all test/altimate/tool-cli and test/cli/help tests still pass (106). Also, ALL_EVENT_TYPES in test/telemetry/telemetry.test.ts stays at 55 without lineage_report (the recent rules_* events were added there). Test-only, and fine in the spawned-CLI / sink-check follow-up you queued.
Consensus review nits (Claude + Codex), PR head 354cbe81b6. None is blocking.
Snapshot churn:bun test -u dropped the altimate_change start/end pair around the run --help snapshot in help-snapshots.test.ts.snap. Markers are not required in test files, but this is unrelated to the feature; consider restoring it.
Silent missing --session:altimate-code tool report-event built with no --session exits 1 with empty stdout and stderr. The global .fail handler in src/index.ts prints help only for unknown, too few or invalid arguments, and otherwise exits silently. Pre-existing, and the plugin always passes --session.
Drift: the action union in telemetry/index.ts repeats REPORT_ACTIONS; deriving it from ReportAction (already queued) removes the risk.
Dashboards: the session lands in ai.session.id, so a distinct-session count over all customEvents will include Claude Code host sessions. The claude: prefix keeps them separable; informational only.
🤖 Code Review — OpenCodeReview (Gemini) — No Issues Found
No supported files changed.
This branch has not been deployed
No deployments
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
sahrizvi
left a comment
Issue for this PR
Closes #1717
Type of change
What does this PR do?
What changes for users: the Claude Code plugin can count how its offline lineage report gets used: the summary shown, Open report pressed,
/lineage-reportrun, and the report built, failed, or found no browser. This goes through altimate-code's usage telemetry, under its usual opt-out.altimate-code tool report-event <action> --session claude:<id>sends onelineage_reportevent: the action, the Claude Code session id and a timestamp. Nothing else.claude:<id>, exits 1 and sends nothing. So a path or a name can't ride along.Claims C1–C4 and residuals R1–R2 for review are in the review-log comment.
How did you verify your code works?
test/altimate/tool-cliand every telemetry test file, after mergingmain: 803 pass. The repo typecheck and Marker Guard pass. Linux only.Cost side effects
None. One small usage event per action; no model calls, warehouse queries or cloud resources.
Checklist
🤖 Generated with Claude Code
https://claude.ai/code/session_01VEmKQwEiHMwQ7BdwgPo9sb
Summary by cubic
Adds a
tool report-eventcommand so the Claude Code plugin can record how its offline lineage report is used, through the existing altimate-code telemetry and its usual opt-out. The report page itself makes no network requests.altimate-code tool report-event <action> --session claude:<id>sends onelineage_reportevent with the action, session id, and timestamp. Only the six defined actions and aclaude:session id are accepted; anything else exits 1 and sends nothing. The event is added to the telemetry union and documented on the telemetry reference page.New Features
summary_shown,open_pressed,command_run,built,build_failed, andno_browser.claude:sessions, so no extra data can ride along.altimate-code tool --help.Written for commit 354cbe8. Summary will update on new commits.
Summary by CodeRabbit