Clarity

Simple Prompt observability that just works.

Clarity gives you instant visibility into your LLM applications with a 2-line integration. See every request, understand your costs, and optimize your prompts—without the complexity.

Why Clarity?

Building with LLMs is like flying blind. When costs spike or quality drops, you're left guessing. Clarity makes your LLM application as debuggable as traditional software.

• 2-line setup - Wrap your OpenAI/Anthropic client and you're done
• Instant visibility - Every request automatically logged with full context
• Cost tracking - See exactly where your money goes, per prompt
• Smart defaults - Zero configuration, just works
• Beautiful UI - No learning curve, intuitive from day one

Quick Start

1. Install the SDK

npm install @clarity/node

2. Initialize and wrap your client

import { init, wrapOpenAI } from "@clarity/node";
import OpenAI from "openai";

// Initialize once at app startup
init({
  apiKey: process.env.CLARITY_API_KEY,
});

// Wrap your OpenAI client
const openai = wrapOpenAI(new OpenAI(), {
  promptId: "email-classifier",
  promptVersion: "v2",
});

// Use normally - all calls are automatically logged!
const response = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Classify this email..." }],
});

3. View your logs

Head to clarity.dev/dashboard to see your requests in real-time.

That's it! 🎉

Features

📊 Complete Request Logging

• Full input/output capture
• Token counts and costs
• Latency tracking
• Error monitoring
• Automatic metadata tagging

💰 Cost Analytics

• Real-time cost calculation
• Cost per prompt breakdown
• Cost trends over time
• Model comparison
• Usage by environment (dev/staging/prod)

🔄 Replay & Compare

• Re-run any request with different parameters
• Compare outputs side-by-side
• Test different models instantly
• Optimize based on real data

🔍 Smart Filtering

• Filter by prompt ID
• Filter by environment
• Filter by status (success/error)
• Date range selection
• Search across all logs

🏷️ Prompt Management

• Tag prompts with IDs and versions
• Track prompt performance
• Compare version metrics
• Organize by use case

Development

This is a monorepo containing the SDK, web dashboard, and demo app.

Setup

# Install dependencies
npm install

# Build the SDK
cd packages/sdk-node && npm run build

# Run the web dashboard
cd packages/web && npm run dev

Code Quality

We maintain strict code quality standards:

• TypeScript with strict mode enabled
• ESLint for catching unused imports, variables, and code quality issues
• Prettier for consistent formatting
• Type checking on all packages
• GitHub Actions for automated checks on all PRs

Before committing:

npm run format    # Format code
npm run lint:fix  # Fix linting issues
npm run type-check # Type check all packages

See CONTRIBUTING.md for detailed guidelines.

Supported Providers

OpenAI

• ✅ GPT-5
• ✅ GPT-4o, GPT-4o-mini
• ✅ GPT-4, GPT-4-turbo
• ✅ GPT-3.5-turbo

Anthropic

• ✅ Claude Opus 4
• ✅ Claude Sonnet 4, Sonnet 3.5
• ✅ Claude Haiku 3.5

Coming Soon

• 🔜 Google Gemini
• 🔜 AWS Bedrock

Smart Defaults

Clarity auto-detects everything it can:

• App ID: Reads from your package.json name
• Environment: Detects from NODE_ENV (development → dev, staging → staging, production → prod)
• Batching: Automatically batches logs for efficiency
• Graceful shutdown: Flushes logs before process exit

Configuration

The SDK works with minimal configuration, but you can customize:

init({
  apiKey: process.env.CLARITY_API_KEY,
  appId: "my-custom-app-name", // Optional: override auto-detected app name
  environment: "prod", // Optional: override auto-detected environment
  enabled: process.env.NODE_ENV !== "test", // Optional: disable in tests
  flushInterval: 5000, // Optional: batch flush interval in ms
});

Wrap Options

wrapOpenAI(client, {
  promptId: "email-classifier", // Identify this prompt
  promptVersion: "v2", // Track versions
  sessionId: conversationId, // Group related requests
  route: "/api/classify", // API endpoint name
  tags: ["production", "important"], // Custom tags
  metadata: { userId: "123" }, // Custom metadata
});

Demo App

Check out our comprehensive demo app in demo-app/ for complete examples:

cd demo-app
npm install
cp .env.example .env  # Add your API keys
npm run dev           # Run combined demo
npm run openai        # OpenAI examples only
npm run anthropic     # Anthropic examples only

The demo showcases:

• ✅ 2-line integration
• ✅ OpenAI and Anthropic usage
• ✅ Multiple models (GPT-4o, Claude, etc.)
• ✅ Multi-turn conversations
• ✅ Error handling
• ✅ Custom metadata and tags
• ✅ Cost tracking
• ✅ Perfect TypeScript support

Examples

Basic Usage

import { init, wrapOpenAI } from "@clarity/node";
import OpenAI from "openai";

init({ apiKey: process.env.CLARITY_API_KEY });

const openai = wrapOpenAI(new OpenAI(), {
  promptId: "chat-bot",
  promptVersion: "v1",
});

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" },
  ],
});

Multi-turn Conversations

// Group conversation turns with sessionId
const openai = wrapOpenAI(new OpenAI(), {
  promptId: "support-chat",
  sessionId: conversationId, // Same ID for entire conversation
});

// Each turn is logged and grouped
for (const turn of conversationTurns) {
  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: conversationHistory,
  });
}

Environment-specific Tracking

// Development
init({
  apiKey: process.env.CLARITY_API_KEY,
  environment: "dev", // Automatically tagged
});

// Production
init({
  apiKey: process.env.CLARITY_API_KEY,
  environment: "prod",
});

// Filter by environment in the dashboard

Using with Anthropic

import { init, wrapAnthropic } from "@clarity/node";
import Anthropic from "@anthropic-ai/sdk";

init({ apiKey: process.env.CLARITY_API_KEY });

const anthropic = wrapAnthropic(new Anthropic(), {
  promptId: "content-generator",
  promptVersion: "v3",
});

const response = await anthropic.messages.create({
  model: "claude-sonnet-4",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Write a blog post about AI." }],
});

Dashboard Features

Request Logs

• Real-time log streaming
• Detailed request/response inspection
• Copy prompts for debugging
• Filter and search across all logs

Analytics

• Cost breakdown by prompt
• Usage by environment
• Request trends over time
• Model performance comparison

Replay

• Re-run any request
• Test different models
• Compare outputs side-by-side
• Optimize based on real data

API Keys

Get your API key from the Clarity dashboard.

Store it securely in your environment variables:

CLARITY_API_KEY=obs_your_key_here

Documentation

• Quick Start Guide
• API Reference
• Examples

Roadmap

• OpenAI support
• Anthropic support
• Cost tracking
• Replay feature
• Prompt versioning
• Usage analytics (in progress)
• Advanced search (in progress)
• Python SDK
• Alerts and notifications
• Team collaboration
• Google Gemini support
• AWS Bedrock support

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Support

• Documentation: clarity.dev/docs
• Issues: GitHub Issues
• Email: support@clarity.dev
• Discord: Join our community

License

MIT License - see LICENSE for details.

---

Made with ❤️ by developers who got tired of debugging LLMs blind.

Get Started • Documentation • Dashboard