claude-terminal-prism

PRISM — Agentic visibility layer for Claude. Intercept, record, and debug multi-agent sessions in a real-time dashboard.

Install

npm install -g claude-terminal-prism

Getting started — two commands

prism setup
source ~/.zshrc

prism setup starts the collector + dashboard daemon, adds a shell alias so every claude session is auto-captured, and opens the browser at http://localhost:4700.

Global setup (all Claude sessions on this machine)

prism start                    # Start collector + dashboard → http://localhost:4700
prism init && source ~/.zshrc  # Add shell integration + Claude Code hooks
claude "your task"             # Every session is now captured automatically

prism init writes a prism_claude() wrapper to ~/.zshrc and installs hooks into ~/.claude/settings.json so Claude Code lifecycle events (session start/stop, tool calls, prompts) are captured automatically.

prism uninit   # Remove shell integration and hooks

Per-repo install (scoped to a specific project)

Install PRISM as a dev dependency in a repo to capture sessions for that project only. A single collector on port 4701 handles all your local repos simultaneously — run it once, then add as many repos as you want.

# In your project
npm install --save-dev claude-terminal-prism

# Start the shared local collector once (handles all local repos)
npx prism start --port 4701

# Add this repo (run in each repo you want tracked)
npx prism init --local

On each session start, PRISM automatically captures a git snapshot of the repo:

• Current branch and commit SHA
• Staged, unstaged, and untracked files
• Working-tree diff stat
• Upstream tracking info (ahead/behind)

Sessions in the dashboard are named parent/repo (e.g. work/api, personal/website) so repos with the same folder name stay distinct.

Adding more repos

cd ~/work/project-b && npx prism init --local   # collector already running — repo is ready
cd ~/work/project-c && npx prism init --local   # same

Each prism init --local detects whether the collector is already running and adjusts its output accordingly. All repos share one dashboard at http://localhost:4701.

Custom port

npx prism init --local --port 4702
npx prism start --port 4702

The port is stored in .claude/settings.json so uninit always removes the exact hooks that were installed.

Remove local hooks

npx prism uninit --local

Global and local together

Global (:4700) and local (:4701) run as completely separate processes with separate databases and dashboards — no duplicate events. If you have prism init (global) already set up, prism init --local in a project will post to :4701 only.

Other useful commands

prism start [--port N] [--no-open]   # Start collector + dashboard daemon
prism stop                            # Stop the daemon
prism status                          # Show running state
prism init                            # Global: shell integration + hooks
prism init --local [--port N]         # Local: project hooks only (default port: 4701)
prism uninit                          # Remove global shell integration
prism uninit --local                  # Remove local project hooks
prism tui                             # Inline terminal dashboard
prism exec <cmd>                      # Run a command with full capture
prism shell                           # Spawn a captured interactive shell

SDK instrumentation

Wrap any Anthropic client with one line:

import { prism } from 'claude-terminal-prism';
import Anthropic from '@anthropic-ai/sdk';

const client = prism(new Anthropic());

const message = await client.messages.create({
  model: 'claude-opus-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }],
});

All API calls are intercepted and streamed to the PRISM collector (ws://localhost:4700 by default).

Configuration

const client = prism(new Anthropic(), {
  collectorUrl: 'ws://localhost:4700', // Collector WebSocket URL
  sessionName: 'my-coding-agent',      // Human-readable session label
  redactKeys: true,                    // Redact API keys from events (default: true)
  bufferSize: 100,                     // Event buffer when collector is disconnected
  metadata: { env: 'dev' },           // Arbitrary metadata attached to every event
});

Environment variables

| Variable | Description | |-----------------------|--------------------------------------------------------------| | PRISM_ENABLED | Set to true/1 to enable, false/0 to disable | | PRISM_COLLECTOR_URL | Override the collector WebSocket URL |

Auto-instrumentation (single terminal session)

Intercept all Node.js processes in the current terminal without code changes:

export PRISM_ENABLED=true
export NODE_OPTIONS="--require claude-terminal-prism/auto"
# Optional: export PRISM_COLLECTOR_URL=ws://your-host:4700

Deactivate:

unset PRISM_ENABLED NODE_OPTIONS PRISM_COLLECTOR_URL

Agent tracking

import { agent } from 'claude-terminal-prism';

const coder = agent('coder', async (ctx) => {
  ctx.log('Starting code generation');

  // Emits tool.call event — detects loops (3+ calls to same tool in 60s)
  await ctx.toolCall('write_file', { path: 'src/api.ts', content: '...' });

  // Named checkpoint visible in the dashboard timeline
  ctx.checkpoint('routes-written');
});

await coder();

AgentContext API

| Method | Description | |--------|-------------| | ctx.log(message, data?) | Emit an agent.log event | | ctx.toolCall(name, input) | Emit a tool.call event, detect loops | | ctx.checkpoint(label, meta?) | Emit a checkpoint.create event | | ctx.agentId | ULID for this agent run | | ctx.sessionId | Session ID shared with the prism() client |

Record the user prompt

import { prism, setPrompt } from 'claude-terminal-prism';

const client = prism(new Anthropic());
setPrompt('Build a REST API with authentication');

Reusable factory

import { createPrismFactory } from 'claude-terminal-prism';

const myPrism = createPrismFactory({ sessionName: 'prod-agent', metadata: { env: 'prod' } });
const client = myPrism(new Anthropic());

TypeScript

Full TypeScript support with strict types. All event payload shapes are exported:

import type {
  PrismEvent,
  PrismOptions,
  AgentContext,
  GitContextPayload,
  GitFileStatus,
} from 'claude-terminal-prism';

License

MIT