A CLI for Arize AI Phoenix data analysis with AI agents
npm install @cephalization/phoenix-insight
Phoenix Insight brings AI-powered analysis to your Phoenix observability data using the "bash + files" paradigm. Instead of hiding data behind opaque API calls, Phoenix Insight materializes your traces, experiments, datasets, and prompts as a structured filesystem. An AI agent then explores this data using standard bash commands you already know: cat, grep, jq, awk, and more.
This filesystem-native approach provides transparency that traditional APIs can't match. Every query the agent runs is visible and reproducible. You can inspect the exact files it reads, copy its commands, and run them yourself. The data is just files, and the analysis is just bash, making AI-driven observability debuggable, auditable, and extensible with any tool in your Unix toolkit.
- Node.js v22 or newer - Required for the CLI to run
- Anthropic API key - Required for the AI agent
Set your Anthropic API key before running:
``bash`
export ANTHROPIC_API_KEY=sk-ant-api03-...
Or add it to your shell profile for persistence:
`bash`
echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.zshrc # or ~/.bashrc
You can get an API key from console.anthropic.com.
`bashInstall globally via npm
npm install -g @cephalization/phoenix-insight
Quick Start
`bash
Start interactive mode
phoenix-insightAnalyze Phoenix data with natural language
phoenix-insight "What are the most common errors in the last hour?"Show help
phoenix-insight help
`CLI Examples
This section covers all CLI usage, progressing from basic to advanced scenarios.
$3
`bash
Ask a question about your Phoenix data
phoenix-insight "What types of errors are occurring most frequently?"Analyze performance patterns
phoenix-insight "Find the slowest traces and identify patterns"Compare experiments
phoenix-insight "Compare success rates across recent experiments"Explore datasets
phoenix-insight "Show me statistics about my datasets"
`$3
Start an interactive REPL session for multiple queries without re-fetching data:
`bash
Start interactive mode (default when no query is provided)
phoenix-insightOr explicitly with --interactive flag
phoenix-insight --interactive
`Within interactive mode:
`
phoenix> What projects have the most spans?
[Agent analyzes and responds...]phoenix> Show me error patterns in the chatbot-prod project
[Agent investigates specific project...]
phoenix> px-fetch-more trace --trace-id abc123
[Agent fetches specific trace data...]
phoenix> help
[Shows available commands and tips...]
phoenix> exit
`$3
Create or update snapshots separately from queries:
`bash
Create initial snapshot (explicit command)
phoenix-insight snapshot createCreate initial snapshot (shorthand, same as 'snapshot create')
phoenix-insight snapshotForce refresh snapshot (ignore cache)
phoenix-insight snapshot --refreshSnapshot from a specific Phoenix instance
phoenix-insight snapshot --base-url https://phoenix.example.com --api-key your-api-keyGet the path to the latest snapshot
phoenix-insight snapshot latestList all available snapshots
phoenix-insight snapshot listClean up local snapshots
phoenix-insight prunePreview what would be deleted
phoenix-insight prune --dry-run
`$3
`bash
Run a query in local mode (persistent storage, full bash capabilities)
phoenix-insight --local "analyze trace patterns"
`$3
Connect to different Phoenix instances:
`bash
Connect to a remote Phoenix instance
phoenix-insight --base-url https://phoenix.example.com "analyze traces"Authenticate with an API key
phoenix-insight --base-url https://phoenix.example.com --api-key your-api-key "show errors"
`$3
`bash
Increase span fetch limit (default: 1000 per project)
phoenix-insight --limit 5000 "deep trace analysis"Force refresh of cached data
phoenix-insight --refresh "show me the latest errors"
`$3
`bash
Disable streaming for batch processing (streaming is enabled by default)
phoenix-insight --no-stream "generate report" > report.txt
`$3
Start the web-based UI for a visual chat interface and structured report display:
`bash
Start web UI (opens browser automatically)
phoenix-insight uiStart on a custom port
phoenix-insight ui --port 8080Start without opening browser
phoenix-insight ui --no-open
`The web UI provides:
- Split-pane interface: Chat panel on the left, report display on the right
- Real-time streaming: See agent responses and tool usage as they happen
- Structured reports: AI-generated reports with tables, metrics, and formatted content
- Session history: Persist and browse previous conversations and reports
- WebSocket connection: Real-time bidirectional communication with the agent
$3
`bash
Enable tracing of agent operations to Phoenix (enabled by default)
phoenix-insight --trace "analyze performance"
`$3
Within interactive mode, the agent can fetch additional data during analysis:
`bash
px-fetch-more spans --project my-project --limit 500
px-fetch-more trace --trace-id abc123
`$3
Combine multiple options for complex scenarios:
`bash
Remote instance with authentication, local mode, and increased limit
phoenix-insight --local --base-url https://phoenix.example.com \
--api-key your-api-key --limit 5000 "deep analysis of production traces"Refresh data, enable tracing, and stream output
phoenix-insight --refresh --trace --stream "analyze error patterns over time"
`Example Queries
Phoenix Insight understands natural language queries about your observability data. Here are examples organized by analysis type to help you get started.
$3
`bash
Find and categorize errors
phoenix-insight "What are the most common errors in the last 24 hours?"
phoenix-insight "Show me all failed spans and their error messages"
phoenix-insight "Which services have the highest error rates?"
phoenix-insight "Find traces that contain exceptions or timeouts"
`$3
`bash
Identify performance bottlenecks
phoenix-insight "What are the slowest LLM calls in my application?"
phoenix-insight "Find traces where latency exceeds 5 seconds"
phoenix-insight "Show p50, p95, and p99 latency by endpoint"
phoenix-insight "Which operations have the highest latency variance?"
`$3
`bash
Analyze LLM resource consumption
phoenix-insight "Which LLM calls are consuming the most tokens?"
phoenix-insight "Calculate total token usage for the chatbot project"
phoenix-insight "Show token usage breakdown by model type"
phoenix-insight "Find conversations that exceeded 10,000 tokens"
`$3
`bash
Examine retrieval-augmented generation patterns
phoenix-insight "Show retrieved documents with low relevance scores"
phoenix-insight "Find retrieval calls that returned no results"
phoenix-insight "What's the average number of documents retrieved per query?"
phoenix-insight "Identify queries where retrieval latency dominated total time"
`$3
`bash
Review evaluation results and experiment metrics
phoenix-insight "What's the hallucination rate across my experiments?"
phoenix-insight "Compare accuracy scores between model versions"
phoenix-insight "Show experiments sorted by success rate"
phoenix-insight "Find evaluation runs where quality scores dropped below threshold"
`$3
`bash
Explore datasets and examples
phoenix-insight "Show statistics for my evaluation datasets"
phoenix-insight "Find examples where the model failed quality checks"
phoenix-insight "What's the distribution of example categories in my dataset?"
phoenix-insight "List datasets with the most recent updates"
`$3
`bash
Analyze prompt versions and performance
phoenix-insight "List all prompt versions and their performance metrics"
phoenix-insight "Compare outputs between prompt v1 and v2"
phoenix-insight "Which prompt template has the lowest error rate?"
phoenix-insight "Show the evolution of my summarization prompt"
`$3
`bash
Understand user interaction patterns
phoenix-insight "Show the conversation flow for session abc123"
phoenix-insight "Find sessions with high user abandonment"
phoenix-insight "What's the average conversation length by project?"
phoenix-insight "Identify sessions where users repeated similar queries"
`$3
`bash
Analyze agent tool usage
phoenix-insight "Which tools are being called most frequently?"
phoenix-insight "Find tool calls that failed or timed out"
phoenix-insight "Show the success rate for each tool type"
phoenix-insight "What's the average latency for function calls?"
`Command Reference
Phoenix Insight provides several commands, each with its own options.
$3
The default command analyzes Phoenix data with natural language queries.
`bash
phoenix-insight [options] [query]
`| Option | Description | Default | Example |
| ------------------- | --------------------------------------------- | ----------------------- | ---------------------------------------------- |
|
--config | Custom config file path | ~/.phoenix-insight/config.json | --config ./my-config.json |
| --sandbox | Run in sandbox mode with in-memory filesystem | true | phoenix-insight --sandbox "query" |
| --local | Run in local mode with persistent storage | false | phoenix-insight --local "query" |
| --base-url | Phoenix server URL | http://localhost:6006 | --base-url https://phoenix.example.com |
| --api-key | Phoenix API key for authentication | (none) | --api-key your-api-key |
| --refresh | Force refresh of cached snapshot data | false | phoenix-insight --refresh "show latest data" |
| --limit | Maximum spans to fetch per project | 1000 | --limit 5000 |
| --stream | Stream agent responses in real-time | true | --no-stream to disable |
| -i, --interactive | Start interactive REPL mode | false | phoenix-insight -i |
| --trace | Enable tracing of agent operations to Phoenix | false | phoenix-insight --trace "query" |$3
Creates a configuration file at
~/.phoenix-insight/config.json with your Phoenix connection settings.`bash
phoenix-insight init
`No additional options. The command interactively prompts for:
- Phoenix base URL - Defaults to
http://localhost:6006. For Phoenix Cloud, use https://app.phoenix.arize.com/s/
- Phoenix API key - Optional. Required for Phoenix Cloud or authenticated Phoenix instancesBehavior:
- Creates
~/.phoenix-insight directory if it doesn't exist
- Warns if config file already exists and asks for confirmation before overwriting
- Shows helpful hints about default values when skippedExample session:
`
$ phoenix-insight init
š Phoenix Insight Configuration SetupPlease provide your Phoenix configuration:
Phoenix base URL (http://localhost:6006): https://app.phoenix.arize.com/s/my-space
Phoenix API key (optional, press Enter to skip): phx_abc123...
ā
Configuration saved successfully!
š Config file: /Users/you/.phoenix-insight/config.json
š Configuration:
baseUrl: https://app.phoenix.arize.com/s/my-space
apiKey: phx_abc1...
limit: 1000
stream: true
mode: sandbox
refresh: false
trace: true
š” You can now run 'phoenix-insight' to start analyzing your Phoenix data.
`$3
Sends a traced hello-world message to verify your Phoenix setup is working correctly.
`bash
phoenix-insight seed
`No additional options. The command:
1. Loads configuration from
~/.phoenix-insight/config.json (or uses defaults)
2. Initializes OpenTelemetry tracing to your Phoenix instance
3. Sends a simple message to Claude using ai-sdk
4. Streams the response to the console
5. Flushes the trace to Phoenix
6. Prints a link to view the trace in Phoenix UIRequirements:
-
ANTHROPIC_API_KEY environment variable must be setExample session:
`
$ phoenix-insight seed
š± Phoenix Insight Seed - Verifying Phoenix Setupš Configuration:
Phoenix URL: http://localhost:6006
š Initializing OpenTelemetry tracing...
š¤ Sending hello-world message to Claude...
⨠Response from Claude:
Hello! How can I help you today?
š¤ Flushing traces to Phoenix...
ā
Seed completed successfully!
š View your trace in Phoenix within the 'phoenix-insight-seed' project:
http://localhost:6006/projects
š” If you don't see the trace immediately, wait a few seconds and refresh the page.
`Error handling:
- Missing
ANTHROPIC_API_KEY: Provides instructions to set the environment variable
- Phoenix connection errors: Shows helpful message about checking Phoenix is running
- API errors: Displays the error message with troubleshooting guidance$3
Creates or updates a data snapshot from Phoenix without running a query.
`bash
phoenix-insight snapshot [options]
phoenix-insight snapshot create [options]
`Note:
phoenix-insight snapshot (without subcommand) is equivalent to phoenix-insight snapshot create for backward compatibility.| Option | Description | Default | Example |
| ------------------ | --------------------------------------------- | ----------------------- | ----------------------------------------------- |
|
--config | Custom config file path | ~/.phoenix-insight/config.json | --config ./my-config.json |
| --base-url | Phoenix server URL | http://localhost:6006 | --base-url https://phoenix.example.com |
| --api-key | Phoenix API key for authentication | (none) | --api-key your-api-key |
| --refresh | Force refresh (ignore existing cache) | false | phoenix-insight snapshot --refresh |
| --limit | Maximum spans to fetch per project | 1000 | phoenix-insight snapshot --limit 5000 |
| --trace | Enable tracing of snapshot operations | false | phoenix-insight snapshot --trace |$3
Explicitly creates a new snapshot from Phoenix data. This is the preferred way to create snapshots.
`bash
phoenix-insight snapshot create
`Same options as
phoenix-insight snapshot. Use snapshot create for clarity in scripts and automation.$3
Prints the absolute path to the latest snapshot directory.
`bash
phoenix-insight snapshot latest
`Outputs the path to stdout with no decoration (just the path). Exit code 0 on success, exit code 1 if no snapshots exist.
Example usage:
`bash
Get the latest snapshot path
phoenix-insight snapshot latest
Output: /Users/you/.phoenix-insight/snapshots/1704067200000-abc123/phoenix
Use in scripts
SNAPSHOT_PATH=$(phoenix-insight snapshot latest)
ls "$SNAPSHOT_PATH"Check if snapshots exist
if phoenix-insight snapshot latest > /dev/null 2>&1; then
echo "Snapshots available"
else
echo "No snapshots found"
fi
`$3
Lists all available snapshots with their timestamps.
`bash
phoenix-insight snapshot list
`Outputs one snapshot per line in the format
where timestamp is ISO 8601. Most recent first. Exit code 0 even if empty (just prints nothing).Example usage:
`bash
List all snapshots
phoenix-insight snapshot list
Output:
2024-01-01T12:30:00.000Z /Users/you/.phoenix-insight/snapshots/1704113400000-abc123/phoenix
2024-01-01T10:00:00.000Z /Users/you/.phoenix-insight/snapshots/1704104400000-def456/phoenix
Count snapshots
phoenix-insight snapshot list | wc -lGet oldest snapshot path
phoenix-insight snapshot list | tail -1 | cut -d' ' -f2Process snapshots in a script
phoenix-insight snapshot list | while read timestamp path; do
echo "Snapshot from $timestamp at $path"
done
`$3
Deletes the local snapshot directory to free up disk space.
`bash
phoenix-insight prune [options]
`| Option | Description | Default | Example |
| ----------- | ---------------------------------------- | ------- | ------------------------------- |
|
--dry-run | Preview what would be deleted without actually deleting | false | phoenix-insight prune --dry-run |$3
Starts a web-based UI for visual interaction with the Phoenix Insight agent.
`bash
phoenix-insight ui [options]
`| Option | Description | Default | Example |
| --------------- | ------------------------------------------------ | ------- | -------------------------------- |
|
--port | Port to run the UI server on | 6007 | phoenix-insight ui --port 8080 |
| --no-open | Do not automatically open browser | false | phoenix-insight ui --no-open |The UI server provides:
- HTTP server: Serves the web UI on
http://localhost:6007 (configurable port)
- WebSocket: Real-time bidirectional communication at /ws
- Session management: Multiple concurrent sessions with conversation history
- Report generation: Agent can generate structured reports displayed in the UIUsage notes:
- The server binds to localhost only (127.0.0.1) for security
- Press Ctrl+C to stop the server gracefully
- Configuration is loaded from the standard config file and environment variables
#### Web UI Features
The web UI provides a rich interface for interacting with Phoenix Insight:
Split-pane Layout:
- Left panel: Chat interface with message history
- Right panel: Structured report display
- Resizable panels with drag handle
- Responsive design: stacked tabs on mobile devices
Chat Interface:
- Real-time streaming of agent responses
- Markdown rendering optimized for streaming content
- Session history with dropdown to switch between conversations
- Create, switch, and delete sessions
- Visual indicators for agent tool usage (tool_call/tool_result events)
Report Panel:
- Structured reports generated by the agent using
generate_report tool
- Components: Cards, Tables, Metrics, Alerts, Badges, Lists, Code blocks, and more
- Download reports as Markdown
- Browse and restore previous reports from historyConnection Management:
- Automatic reconnection with exponential backoff (via partysocket)
- Visual connection status indicator (green/yellow/red)
- Toast notifications for connection state changes
- Message buffering during temporary disconnections
Data Persistence:
- Sessions and reports stored in browser's IndexedDB
- Survives page refreshes and browser restarts
- Export reports as Markdown files
#### WebSocket Protocol
The UI communicates with the CLI server over WebSocket at the
/ws endpoint. All messages are JSON-encoded.Client Messages (UI to Server):
`typescript
// Send a query to the agent
{ type: "query", payload: { content: string, sessionId?: string } }// Cancel the current query
{ type: "cancel", payload: { sessionId?: string } }
`Server Messages (Server to UI):
`typescript
// Streaming text content from the agent
{ type: "text", payload: { content: string, sessionId: string } }// Agent is calling a tool
{ type: "tool_call", payload: { toolName: string, args: unknown, sessionId: string } }
// Tool execution result
{ type: "tool_result", payload: { toolName: string, result: unknown, sessionId: string } }
// Agent generated a structured report
{ type: "report", payload: { content: UITree, sessionId: string } }
// Error occurred during processing
{ type: "error", payload: { message: string, sessionId?: string } }
// Agent finished processing the query
{ type: "done", payload: { sessionId: string } }
`Report Content Structure (UITree):
The
report message contains a UITree structure compatible with json-render:`typescript
interface UITree {
root: string; // Key of the root element
elements: Record; // Flat map of all elements
}interface UIElement {
key: string;
type: "Card" | "Text" | "Heading" | "List" | "Table" | "Metric" | "Badge" | "Alert" | "Separator" | "Code";
props: Record; // Component-specific props
children?: string[]; // Keys of child elements
parentKey?: string;
}
`Example WebSocket Session:
`
Client: {"type":"query","payload":{"content":"Show error patterns","sessionId":"session-1"}}
Server: {"type":"text","payload":{"content":"I'll analyze","sessionId":"session-1"}}
Server: {"type":"text","payload":{"content":" the error patterns...","sessionId":"session-1"}}
Server: {"type":"tool_call","payload":{"toolName":"bash","args":{"command":"grep -c 'error' spans.jsonl"},"sessionId":"session-1"}}
Server: {"type":"tool_result","payload":{"toolName":"bash","result":"42","sessionId":"session-1"}}
Server: {"type":"text","payload":{"content":"Found 42 errors.","sessionId":"session-1"}}
Server: {"type":"report","payload":{"content":{"root":"card-1","elements":{...}},"sessionId":"session-1"}}
Server: {"type":"done","payload":{"sessionId":"session-1"}}
`$3
Displays help information and available options.
`bash
phoenix-insight help
`No additional options. Shows usage information, all commands, and their options.
How It Works
Phoenix Insight operates in three phases:
1. Data Ingestion: Fetches data from your Phoenix instance and creates a structured filesystem snapshot
2. AI Analysis: An AI agent explores the data using bash commands (cat, grep, jq, awk, etc.)
3. Natural Language Results: The agent synthesizes findings into clear, actionable insights
$3
Phoenix data is organized into an intuitive REST-like hierarchy:
`
/phoenix/
_context.md # Start here! Human-readable summary
/projects/
index.jsonl # All projects
/{project_name}/
metadata.json # Project details
/spans/
index.jsonl # Trace spans (sampled)
/datasets/
index.jsonl # All datasets
/{dataset_name}/
metadata.json
examples.jsonl
/experiments/
index.jsonl # All experiments
/{experiment_id}/
metadata.json
runs.jsonl
/prompts/
index.jsonl # All prompts
/{prompt_name}/
metadata.json
/versions/
/{version}.md # Prompt templates as markdown
/traces/ # Fetched on-demand
/{trace_id}/
spans.jsonl
metadata.json
/_meta/
snapshot.json # Snapshot metadata
`Examples of Agent Analysis
$3
`
User: "What are the most common errors in my traces?"Agent: I'll analyze the error patterns in your traces. Let me start by examining the context...
reads _context.md
searches for error spans across projects
aggregates by error type
identifies patterns
I found 3 main error patterns in your traces:
1. Database timeouts (42% of errors): Occurring in user-service, primarily during peak hours
2. API rate limits (31% of errors): Third-party integration hitting limits
3. Null pointer exceptions (27% of errors): In the recommendation engine
The database timeouts show a clear pattern during 9-10am and 2-3pm daily.
`$3
`
User: "Find the slowest API endpoints"Agent: I'll analyze your API endpoint performance. Let me examine the span data...
reads project spans
calculates latency percentiles
groups by endpoint
identifies outliers
Here are your slowest API endpoints by p95 latency:
1.
/api/v1/recommendations - 3.2s p95 (8.1s p99)
2. /api/v1/search - 2.8s p95 (5.2s p99)
3. /api/v1/user/history - 1.9s p95 (3.1s p99)The recommendations endpoint has high variability, suggesting cache misses.
`Tips and Best Practices
$3
- Be specific about what you want to analyze
- Mention time ranges if relevant
- Ask for patterns, not just raw data
$3
- Use
--limit to control data volume
- In sandbox mode, start with smaller datasets
- Use local mode for production analysis$3
- Use sandbox mode when trying new queries
- Never put API keys in queries
- Review agent actions with
--streamAdvanced Topics
The following sections cover configuration, execution modes, and internal details for power users.
$3
Phoenix Insight uses a layered configuration system with the following priority (highest to lowest):
1. CLI arguments - Options passed directly to the command
2. Environment variables -
PHOENIX_* environment variables
3. Config file - JSON file at ~/.phoenix-insight/config.json#### Config File
On first run, Phoenix Insight automatically creates a default config file at
~/.phoenix-insight/config.json with all default values. You can edit this file to customize your settings.Config file location:
- Default:
~/.phoenix-insight/config.json
- Override with env var: PHOENIX_INSIGHT_CONFIG=/path/to/config.json
- Override with CLI flag: --config /path/to/config.jsonExample config.json with all options:
`json
{
"baseUrl": "http://localhost:6006",
"apiKey": "your-api-key",
"limit": 1000,
"stream": true,
"mode": "sandbox",
"refresh": false,
"trace": false
}
`| Config Key | Type | Default | Description |
| ---------- | ------------------------ | ----------------------- | --------------------------------------------- |
|
baseUrl | string | http://localhost:6006 | Phoenix server URL |
| apiKey | string | (none) | API key for authentication |
| limit | number | 1000 | Maximum spans to fetch per project |
| stream | boolean | true | Enable streaming responses from the agent |
| mode | "sandbox" \| "local" | "sandbox" | Execution mode |
| refresh | boolean | false | Force refresh of snapshot data |
| trace | boolean | false | Enable tracing of agent operations to Phoenix |#### Environment Variables
| Variable | Config Key | Default | Description |
| ------------------------- | ---------- | ----------------------- | -------------------------- |
|
PHOENIX_BASE_URL | baseUrl | http://localhost:6006 | Phoenix server URL |
| PHOENIX_API_KEY | apiKey | (none) | API key for authentication |
| PHOENIX_INSIGHT_LIMIT | limit | 1000 | Max spans per project |
| PHOENIX_INSIGHT_STREAM | stream | true | Enable streaming |
| PHOENIX_INSIGHT_MODE | mode | sandbox | Execution mode |
| PHOENIX_INSIGHT_REFRESH | refresh | false | Force refresh snapshot |
| PHOENIX_INSIGHT_TRACE | trace | false | Enable tracing |
| PHOENIX_INSIGHT_CONFIG | - | - | Custom config file path |
| DEBUG | - | 0 | Show detailed error info |#### Local Mode Storage
In local mode (
--local), data persists at ~/.phoenix-insight/:`
~/.phoenix-insight/
config.json # Configuration (auto-created on first run)
/snapshots/{timestamp}/ # Snapshot data
/cache/ # API response cache
`Use
phoenix-insight prune to clean up local storage.$3
Phoenix Insight supports two execution modes:
| Mode | Flag | Filesystem | Bash | Use Case |
|------|------|------------|------|----------|
| Sandbox (default) |
--sandbox | In-memory | just-bash (50+ commands) | CI/CD, demos, safe exploration |
| Local | --local | Persistent (~/.phoenix-insight/) | Real system bash | Power users, complex analysis |$3
The AI agent has access to:
#### Bash Commands (Sandbox Mode)
- File operations:
cat, ls, find, head, tail
- Search & filter: grep, awk, sed
- JSON processing: jq (full featured)
- Analysis: sort, uniq, wc
- And more: 50+ commands via just-bash#### Bash Commands (Local Mode)
- All commands available on your system
- Custom tools:
ripgrep, fd, bat, etc.
- Full jq, awk, sed features
- Any installed CLI tools#### Custom Commands
-
px-fetch-more spans: Fetch additional spans for deeper analysis
- px-fetch-more trace: Fetch a specific trace by IDSee On-Demand Data Fetching for usage examples.
#### Understanding Context
The agent always starts by reading
/_context.md which provides:- Summary of available data
- Recent activity highlights
- Data freshness information
- Available commands reminder
$3
Phoenix Insight can trace its own execution back to Phoenix using
--trace. When enabled, all agent operations, tool calls, and responses are traced as spans and sent to the Phoenix instance being queried. This is useful for debugging slow queries and understanding agent decision-making.$3
For connection issues, authentication errors, debug mode, and common issues, see the Troubleshooting Guide.
$3
#### Building from Source
`bash
Clone the repository
git clone https://github.com/Arize-ai/phoenix.git
cd phoenix/js/packages/phoenix-insightInstall dependencies
pnpm installRun in development
pnpm dev "your query"Run tests
pnpm testBuild for production
pnpm buildType checking
pnpm typecheck
`#### Architecture
Phoenix Insight uses:
- Commander.js for CLI interface
- AI SDK with Anthropic Claude for the agent
- just-bash for sandbox execution
- Phoenix Client for data fetching
- TypeScript for type safety
#### Testing
`bash
Run all tests
pnpm testRun with coverage
pnpm test -- --coverageRun specific test file
pnpm test test/modes/sandbox.test.tsType checking
pnpm typecheck
`#### UI Integration Testing
The web UI has manual integration tests using agent-browser for browser automation. These tests are NOT run in CI because they require a live Phoenix server with data.
Prerequisites:
1. Phoenix server running on
localhost:6006 with data
2. Run from the monorepo rootRunning UI tests:
`bash
From monorepo root - builds packages and runs UI integration tests
pnpm test:ui
`The test:ui script will:
1. Build the UI package
2. Build the CLI package (which bundles the UI)
3. Expect a running Phoenix server at localhost:6006
4. Expect the UI server to be running at localhost:6007 (start with
phoenix-insight ui)
5. Run browser automation tests that verify:
- Layout renders correctly (chat panel, report panel)
- Chat input is functional
- WebSocket connection works
- Session management works
- Report panel displays correctlyManual testing workflow:
`bash
Terminal 1: Start Phoenix
phoenix serveTerminal 2: Start the UI server
cd packages/cli && pnpm dev uiTerminal 3: Run UI tests
pnpm test:ui
`Note: If tests skip with "Phoenix server not running" or "UI server not running", ensure both servers are accessible before running tests.
$3
Contributions are welcome! This project uses changesets for version management and automated releases.
#### Making Changes
1. Fork the repository and create a feature branch
2. Make your changes and ensure tests pass (
pnpm test)
3. Create a changeset to document your changes:`bash
pnpm changeset
`4. Follow the prompts to:
- Select the type of change (patch, minor, major)
- Describe what changed for the changelog
5. Commit the generated changeset file along with your changes
6. Open a pull request
#### Release Process
When your PR is merged to
main:1. If there are pending changesets, a "Version Packages" PR is automatically created
2. This PR updates the version in
package.json and generates CHANGELOG.md` entries#### Changeset Guidelines
- patch: Bug fixes, documentation updates, internal refactoring
- minor: New features, new CLI options, non-breaking enhancements
- major: Breaking changes to CLI interface or behavior
This software is provided "as is" without warranty of any kind. Use at your own risk.
You may file GitHub issues at https://github.com/cephalization/phoenix-insight/issues.
Apache-2.0 - See LICENSE for details.