Repository navigation
feat(claude-plugin): draw ClickStack query results as terminal charts #3400
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
2b5eef5
15cb6ae
e3db061
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| --- | ||
| '@hyperdx/claude-plugin': minor | ||
| --- | ||
|
|
||
| feat: add a Claude Code plugin that connects the ClickStack MCP server and draws | ||
| `clickstack_timeseries` and `clickstack_table` results as terminal charts, using | ||
| the CLI's renderers. Install with | ||
| `/plugin install hyperdx-charts --marketplace hyperdxio/hyperdx`. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| { | ||
| "name": "hyperdx", | ||
| "owner": { "name": "HyperDX" }, | ||
| "plugins": [ | ||
| { | ||
| "name": "hyperdx-charts", | ||
| "description": "Draws ClickStack MCP query results as terminal charts in Claude Code", | ||
| "source": { "source": "npm", "package": "@hyperdx/claude-plugin" } | ||
| } | ||
| ] | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| { | ||
| "name": "hyperdx-charts", | ||
| "description": "Draws ClickStack MCP query results as terminal charts in Claude Code", | ||
| "author": { | ||
| "name": "HyperDX" | ||
| }, | ||
| "homepage": "https://github.com/hyperdxio/hyperdx/tree/main/packages/claude-plugin", | ||
| "license": "MIT", | ||
| "types": "./types/index.d.ts", | ||
| "userConfig": { | ||
| "hyperdx_url": { | ||
| "type": "string", | ||
| "title": "HyperDX URL", | ||
| "description": "Your HyperDX address, e.g. https://hyperdx.example.com (no trailing slash).", | ||
| "required": true | ||
| }, | ||
| "access_key": { | ||
| "type": "string", | ||
| "title": "Personal API access key", | ||
| "description": "From Team Settings > API keys in HyperDX. Kept in secure storage.", | ||
| "required": true, | ||
| "sensitive": true | ||
| } | ||
| }, | ||
| "mcpServers": { | ||
| "clickstack": { | ||
| "type": "http", | ||
| "url": "${user_config.hyperdx_url}/api/mcp", | ||
| "headers": { | ||
| "Authorization": "Bearer ${user_config.access_key}" | ||
| } | ||
| } | ||
| } | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| hooks/chart.js | ||
| .claude-plugin/types/ |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| # @hyperdx/claude-plugin | ||
|
|
||
| A Claude Code plugin that draws ClickStack MCP query results as charts in the | ||
| terminal. When Claude runs `clickstack_timeseries` or `clickstack_table`, the | ||
| tool row shows a line, stacked bar, bar, pie, number or table chart in place of | ||
| the raw JSON. Claude still reads the full result. | ||
|
|
||
| Charts are drawn by the same renderers as the `hdx` CLI, so a query looks the | ||
| same in both. | ||
|
|
||
| ## Install | ||
|
|
||
| At a Claude Code prompt: | ||
|
|
||
| ``` | ||
| /plugin install hyperdx-charts --marketplace hyperdxio/hyperdx | ||
| ``` | ||
|
|
||
| Answer `y` to add the marketplace and pick a scope. The plugin asks for your | ||
| HyperDX URL and your personal API access key (Team Settings > API keys), then | ||
| connects the ClickStack MCP server for you, so there is no separate | ||
| `claude mcp add` step. If you already added the server yourself, remove it with | ||
| `claude mcp remove clickstack` to avoid two copies of every tool. The bundled | ||
| server's tools are named `mcp__plugin_hyperdx-charts_clickstack__*`, so update | ||
| any permission rules that name `mcp__clickstack__*`. Charts stay off until both | ||
| values are set; `/plugin configure hyperdx-charts` sets them later. | ||
|
|
||
| ## Limits | ||
|
|
||
| - Terminal only. Desktop and IDE surfaces keep the normal tool row. | ||
| - Results too large for Claude's context are replaced by a file pointer before | ||
| the plugin sees them, so they are not charted. Ask for a coarser | ||
| `granularity`. | ||
| - The Claude Code plugin API this uses is early access and may change between | ||
| releases. | ||
|
|
||
| ## Development | ||
|
|
||
| ```bash | ||
| yarn build # bundle src/ into hooks/chart.js | ||
| yarn ci:unit # jest, src/__tests__/*.spec.ts | ||
| claude plugin test . # engine tests, test/*.test.tsx | ||
| claude plugin validate . | ||
| claude --plugin-dir . # run Claude Code with the plugin loaded | ||
| ``` | ||
|
|
||
| `hooks/register.tsx` is compiled by Claude Code and must stay readable to | ||
| `claude plugin validate`, so only the renderer is bundled. The bundle must stay | ||
| under the 1 MiB hooks module limit; `tsup.config.ts` explains how. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| import js from '@eslint/js'; | ||
| import tseslint from 'typescript-eslint'; | ||
| import prettierConfig from 'eslint-config-prettier'; | ||
| import prettierPlugin from 'eslint-plugin-prettier'; | ||
|
|
||
| export default [ | ||
| js.configs.recommended, | ||
| ...tseslint.configs.recommended, | ||
| prettierConfig, | ||
| { | ||
| // hooks/register.tsx and test/ are typed against the API Claude Code writes | ||
| // at load time; `claude plugin validate` and `claude plugin test` check them. | ||
| ignores: [ | ||
| 'node_modules/**', | ||
| '.claude-plugin/**', | ||
| 'hooks/**', | ||
| 'test/**', | ||
| '**/*.config.cjs', | ||
| '**/*.config.mjs', | ||
| '**/*.config.ts', | ||
| ], | ||
| }, | ||
| { | ||
| files: ['src/**/*.ts', 'types/**/*.ts'], | ||
| plugins: { | ||
| '@typescript-eslint': tseslint.plugin, | ||
| prettier: prettierPlugin, | ||
| }, | ||
| rules: { | ||
| '@typescript-eslint/ban-ts-comment': 'error', | ||
| '@typescript-eslint/no-unused-vars': [ | ||
| 'error', | ||
| { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }, | ||
| ], | ||
| 'prettier/prettier': 'error', | ||
| }, | ||
| languageOptions: { | ||
| parser: tseslint.parser, | ||
| parserOptions: { | ||
| ecmaVersion: 'latest', | ||
| sourceType: 'module', | ||
| project: './tsconfig.json', | ||
| tsconfigRootDir: import.meta.dirname, | ||
| }, | ||
| }, | ||
| }, | ||
| ]; |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| // Types for the bundled hooks/chart.js. The published package ships without src/, | ||
| // so these are written out; src/__tests__/chartTypes.spec.ts keeps them in step. | ||
| import type { ChartCall } from '../types'; | ||
|
|
||
| export type Segment = { | ||
| text: string; | ||
| color?: string; | ||
| dim?: boolean; | ||
| bold?: boolean; | ||
| }; | ||
|
|
||
| export function chartedTool(toolName: string): string | undefined; | ||
| export function renderChart( | ||
| call: ChartCall, | ||
| columns: number, | ||
| ): Segment[][] | undefined; | ||
| export function stripControlChars(text: string): string; |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| { "modules": ["./register.tsx"] } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,130 @@ | ||
| import { atom, read, update } from 'claude-code'; | ||
| import type { | ||
| EngineInterface, | ||
| Register, | ||
| RenderElement, | ||
| RenderInput, | ||
| } from 'claude-code'; | ||
|
|
||
| import type { ChartCall } from '../types'; | ||
|
|
||
| import { chartedTool, renderChart, stripControlChars } from './chart.js'; | ||
|
|
||
| const KEEP = 20; | ||
| const MAX_COLUMNS = 140; | ||
| const calls = atom({ plugin: 'hyperdx-charts', key: 'calls' } as const, {}); | ||
|
|
||
| type Row = { id: string; tool: string; input: unknown }; | ||
|
|
||
| function chartTree( | ||
| $: EngineInterface, | ||
| e: RenderInput, | ||
| row: Row, | ||
| call: ChartCall, | ||
| ): RenderElement | undefined { | ||
| const columns = Math.min( | ||
| MAX_COLUMNS, | ||
| Math.max(40, (e.viewport?.columns ?? 80) - 6), | ||
| ); | ||
| const lines = renderChart(call, columns); | ||
| if (!lines) return undefined; | ||
| const { Box, Text } = $.ui.resolve(e); | ||
| const reason = (row.input as { reason?: unknown } | undefined)?.reason; | ||
| return ( | ||
| <Box flexDirection="column" key={`chart-${row.id}`}> | ||
| <Text> | ||
| <Text bold>{stripControlChars(row.tool.split('__').pop() ?? '')}</Text> | ||
| {typeof reason === 'string' && ( | ||
| <Text dimColor> {stripControlChars(reason)}</Text> | ||
| )} | ||
| </Text> | ||
| {lines.map((segments, i) => ( | ||
| <Text key={i} wrap="truncate"> | ||
| {segments.length === 0 | ||
| ? ' ' | ||
| : segments.map((s, j) => ( | ||
| <Text key={j} color={s.color} dimColor={s.dim} bold={s.bold}> | ||
| {s.text} | ||
| </Text> | ||
| ))} | ||
| </Text> | ||
| ))} | ||
| </Box> | ||
| ); | ||
| } | ||
|
|
||
| // Charted rows replace the engine's row and its JSON; the model still reads the full result. | ||
| async function drawRows( | ||
| $: EngineInterface, | ||
| e: RenderInput, | ||
| next: () => Promise<RenderElement>, | ||
| rows: Row[], | ||
| isEveryRowCharted: boolean, | ||
| ) { | ||
| if (e.surface !== 'terminal' || rows.length === 0) return next(); | ||
| const stored = await read($, calls); | ||
| const drawn = rows.flatMap(row => { | ||
| const call = stored[row.id]; | ||
| return (call && chartTree($, e, row, call)) || []; | ||
| }); | ||
| if (drawn.length === 0) return next(); | ||
| const { Box } = $.ui.resolve(e); | ||
| return ( | ||
| <Box flexDirection="column"> | ||
| {!(isEveryRowCharted && drawn.length === rows.length) && (await next())} | ||
| {drawn} | ||
| </Box> | ||
| ); | ||
| } | ||
|
|
||
| export const register: Register = on => { | ||
| on('tool.call', async ($, e, next) => { | ||
| // The server fixes its default window before the query runs. | ||
| const calledAt = Date.now(); | ||
| const ran = await next(e); | ||
| if (!chartedTool(e.tool) || ran.deny !== undefined || ran.isError) | ||
| return ran; | ||
| const call: ChartCall = { | ||
| tool: e.tool, | ||
| input: e, | ||
| output: ran.result, | ||
| calledAt, | ||
| }; | ||
| // Chart bookkeeping must never fail the call it watched. | ||
| try { | ||
| await update($, calls, all => | ||
| Object.fromEntries( | ||
| [...Object.entries(all), [e.tool_use_id, call]].slice(-KEEP), | ||
| ), | ||
| ); | ||
| } catch { | ||
| // The row keeps the engine's own rendering. | ||
| } | ||
| return ran; | ||
| }).catch(($, e, next) => next(e)); | ||
|
|
||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🔵 minor — The tool.call If Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond |
||
| // MCP calls draw as a collapsed group line; an expanded group draws its rows, which chart themselves. | ||
| on('ui.render', { component: 'ToolGroup' }, async ($, e, next) => { | ||
| const rows = e.props.isExpanded | ||
| ? [] | ||
| : e.props.calls.flatMap(c => | ||
| chartedTool(c.tool) && c.tool_use_id | ||
| ? [{ id: c.tool_use_id, tool: c.tool, input: c.input }] | ||
| : [], | ||
| ); | ||
| return drawRows( | ||
| $, | ||
| e, | ||
| () => next(e), | ||
| rows, | ||
| rows.length === e.props.calls.length, | ||
| ); | ||
| }); | ||
|
|
||
| on('ui.render', { component: 'ToolUse' }, async ($, e, next) => { | ||
| const rows = chartedTool(e.props.tool) | ||
| ? [{ id: e.props.tool_use_id, tool: e.props.tool, input: e.props.input }] | ||
| : []; | ||
| return drawRows($, e, () => next(e), rows, true); | ||
| }); | ||
| }; | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| /** @type {import("jest").Config} **/ | ||
| module.exports = { | ||
| preset: 'ts-jest/presets/default-esm', | ||
| testEnvironment: 'node', | ||
| extensionsToTreatAsEsm: ['.ts'], | ||
| rootDir: './src', | ||
| // *.test.ts(x) belong to `claude plugin test`, which runs every such file in the folder. | ||
| testMatch: ['**/__tests__/*.spec.ts'], | ||
| moduleNameMapper: { | ||
| // The CLI source this package renders with resolves its own `@/` alias. | ||
| '^@/(.*)$': '<rootDir>/../../cli/src/$1', | ||
| '^(\\.{1,2}/.*)\\.js$': '$1', | ||
| }, | ||
| transform: { | ||
| '^.+\\.tsx?$': ['ts-jest', { useESM: true }], | ||
| }, | ||
| }; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🔵 minor — The header re-derives the tool suffix that
chartedToolalready computesrow.tool.split('__').pop()repeats the suffix logic inchartedTool(src/toTileResult.ts). UsechartedTool(row.tool)so the label and the matching rule always agree.Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond