Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/claude-charts-plugin.md
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`.
11 changes: 11 additions & 0 deletions .claude-plugin/marketplace.json
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" }
}
]
}
5 changes: 4 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ schema-agnostic design, and correlation across all telemetry types in one place.

## Architecture (WHAT)

This is a **monorepo** with six packages:
This is a **monorepo** with seven packages:

- `packages/app` - Next.js frontend (TypeScript, Mantine UI, TanStack Query)
- `packages/api` - Express backend (Node.js 22+, MongoDB for metadata,
Expand All @@ -23,6 +23,9 @@ This is a **monorepo** with six packages:
tailing, and inspecting logs and traces (Ink/React). Has its own
[`AGENTS.md`](packages/cli/AGENTS.md) with detailed architecture and
keybindings.
- `packages/claude-plugin` - Claude Code plugin that draws ClickStack MCP
query results as terminal charts, using the CLI's chart renderers. See its
[`README.md`](packages/claude-plugin/README.md).
- `packages/otel-collector` - Custom-built OpenTelemetry Collector (Go, OCB).
See its [`README.md`](packages/otel-collector/README.md) for architecture,
included components, and upgrade procedures.
Expand Down
8 changes: 8 additions & 0 deletions MCP.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,14 @@ claude mcp add --transport http clickstack <your-hyperdx-url>/api/mcp \
--header "Authorization: Bearer <your-personal-access-key>"
```

Or install the [charts plugin](packages/claude-plugin/README.md) instead: it
connects the same server (asking for your URL and key) and draws query results
as charts in the terminal instead of JSON:

```
/plugin install hyperdx-charts --marketplace hyperdxio/hyperdx
```

### Codex CLI

The Codex CLI reads the bearer token from an environment variable rather than a
Expand Down
4 changes: 4 additions & 0 deletions knip.json
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,10 @@
"ignoreDependencies": ["@stryker-mutator/core"],
"ignoreBinaries": ["stryker"]
},
"packages/claude-plugin": {
"project": ["src/**/*.ts"],
"ignoreBinaries": ["claude"]
},
"packages/hdx-eval": {
"project": ["src/**/*.ts"],
"ignoreDependencies": ["tsx"],
Expand Down
34 changes: 34 additions & 0 deletions packages/claude-plugin/.claude-plugin/plugin.json
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}"
}
}
}
}
2 changes: 2 additions & 0 deletions packages/claude-plugin/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
hooks/chart.js
.claude-plugin/types/
49 changes: 49 additions & 0 deletions packages/claude-plugin/README.md
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.
47 changes: 47 additions & 0 deletions packages/claude-plugin/eslint.config.mjs
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,
},
},
},
];
17 changes: 17 additions & 0 deletions packages/claude-plugin/hooks/chart.d.ts
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;
1 change: 1 addition & 0 deletions packages/claude-plugin/hooks/hooks.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{ "modules": ["./register.tsx"] }
130 changes: 130 additions & 0 deletions packages/claude-plugin/hooks/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' && (

Copy link
Copy Markdown
Contributor

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 chartedTool already computes

row.tool.split('__').pop() repeats the suffix logic in chartedTool (src/toTileResult.ts). Use chartedTool(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

<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));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — The tool.call .catch handler calls next(e) again, so a call that rejects can run twice

If await next(e) rejects (for example a transport error from the MCP server), the hook throws and .catch(($, e, next) => next(e)) runs the same ClickStack query a second time. The plugin's own bookkeeping already has a try/catch, so drop the outer .catch. If the API requires one, make it rethrow or return the original failure instead of calling next again.

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);
});
};
17 changes: 17 additions & 0 deletions packages/claude-plugin/jest.config.cjs
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 }],
},
};
Loading
Loading