skalpel 1.0.4 → 1.0.5

package/README.md

@@ -1,116 +1,196 @@
-# Skalpel SDK
+# Skalpel
 
-Optimize your OpenAI and Anthropic API calls with Skalpel AI. The SDK transparently reroutes requests through the Skalpel proxy, adding cost optimization, caching, and intelligent model routing — without changing your existing code.
+Optimize Claude Code prompts to reduce credit usage. Skalpel sits between Claude Code and the Anthropic API, optimizing prompts before they reach the provider — saving you money without changing how you work.
 
-## Installation
+## How It Works
 
-```bash
-npm install skalpel
 ```
+Claude Code  -->  Skalpel Proxy (local)  -->  Skalpel Backend (AWS)  -->  Anthropic API
+                  Intercepts requests          Optimizes prompts           Returns response
+                  Adds tracking headers        Reduces token usage
+```
+
+1. A local proxy runs on your machine (port 18100)
+2. Claude Code is configured to send API requests to the proxy instead of `api.anthropic.com`
+3. The proxy forwards requests to the Skalpel backend, which optimizes prompts for lower token usage
+4. The optimized request is sent to Anthropic, and the response streams back to Claude Code
+
+Your Anthropic API key stays in the request chain — Skalpel never stores it.
 
 ## Quick Start
 
-### Wrapper Pattern
+One command to install, detect Claude Code, and start optimizing:
 
-Wrap your existing client to route all calls through Skalpel with automatic fallback:
+```bash
+npx skalpel --api-key sk-skalpel-YOUR_KEY --auto
+```
 
-```typescript
-import OpenAI from 'openai';
-import { createSkalpelClient } from 'skalpel';
+This will:
+- Start the local proxy on ports 18100 (Anthropic) and 18101 (OpenAI)
+- Detect Claude Code on your machine
+- Configure `~/.claude/settings.json` with `ANTHROPIC_BASE_URL=http://localhost:18100`
+- Set shell environment variables in your `.bashrc`/`.zshrc`
+- Begin optimizing all Claude Code API traffic immediately
 
-const openai = createSkalpelClient(new OpenAI(), {
-  apiKey: process.env.SKALPEL_API_KEY!,
-  workspace: 'my-workspace',
-});
+### Interactive Setup
 
-// Use exactly like the OpenAI client
-const response = await openai.chat.completions.create({
-  model: 'gpt-4o',
-  messages: [{ role: 'user', content: 'Hello' }],
-});
+For a guided setup with prompts:
+
+```bash
+npx skalpel
 ```
 
-### URL Swap Pattern
+The wizard walks you through API key entry, agent detection, and proxy configuration.
 
-The simplest integration — one line change:
+### Manual Setup
 
-```typescript
-import { createSkalpelOpenAI } from 'skalpel';
+```bash
+# 1. Start the proxy
+npx skalpel start
 
-const openai = await createSkalpelOpenAI({
-  apiKey: process.env.SKALPEL_API_KEY!,
-});
+# 2. Configure Claude Code
+npx skalpel agent configure
 
-const response = await openai.chat.completions.create({
-  model: 'gpt-4o',
-  messages: [{ role: 'user', content: 'Hello' }],
-});
+# 3. Verify everything is working
+npx skalpel doctor
+```
+
+## What Gets Configured
+
+### Claude Code (`~/.claude/settings.json`)
+
+Skalpel adds an environment override so Claude Code routes API calls through the local proxy:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://localhost:18100"
+  }
+}
 ```
 
-## CLI Setup
+### Shell Environment (`~/.bashrc`, `~/.zshrc`)
+
+Environment variables are added for tools that read them directly:
 
 ```bash
-npx skalpel init
+# BEGIN SKALPEL PROXY - do not edit manually
+export ANTHROPIC_BASE_URL="http://localhost:18100"
+export OPENAI_BASE_URL="http://localhost:18101"
+# END SKALPEL PROXY
 ```
 
-Interactive wizard that detects your project type, AI SDKs, and generates the integration code.
+### Proxy Config (`~/.skalpel/config.json`)
 
-## API Reference
+```json
+{
+  "apiKey": "sk-skalpel-YOUR_KEY",
+  "remoteBaseUrl": "http://skalpel-production-554359744.us-west-2.elb.amazonaws.com",
+  "anthropicPort": 18100,
+  "openaiPort": 18101
+}
+```
 
-### `createSkalpelClient<T>(client: T, options: SkalpelClientOptions): T`
+## CLI Commands
 
-Wraps an existing OpenAI or Anthropic client instance. All API calls are transparently routed through the Skalpel proxy. Supports automatic fallback to the direct provider on errors.
+| Command | Description |
+|---|---|
+| `npx skalpel` | Run the setup wizard |
+| `npx skalpel start` | Start the proxy |
+| `npx skalpel stop` | Stop the proxy |
+| `npx skalpel status` | Show proxy status and uptime |
+| `npx skalpel doctor` | Verify configuration and connectivity |
+| `npx skalpel logs` | View proxy logs |
+| `npx skalpel logs -f` | Follow proxy logs in real time |
+| `npx skalpel uninstall` | Remove proxy, configs, and shell modifications |
 
-### `createSkalpelOpenAI(options): Promise<OpenAI>`
+### Flags
 
-Factory function that creates a pre-configured OpenAI client pointing at the Skalpel proxy.
+| Flag | Description |
+|---|---|
+| `--api-key <key>` | Provide Skalpel API key (skips interactive prompt) |
+| `--auto` | Non-interactive mode (requires `--api-key`) |
 
-### `createSkalpelAnthropic(options): Promise<Anthropic>`
+## Streaming Support
+
+Skalpel fully supports Anthropic's SSE streaming protocol. When Claude Code sends a streaming request (`"stream": true`), the proxy:
+
+- Detects the streaming flag in the request body
+- Forwards to the backend with all original headers
+- Pipes SSE events (`message_start`, `content_block_delta`, `message_stop`) directly back to Claude Code
+- Preserves upstream headers like `anthropic-request-id`
+
+No buffering, no modification of the stream — chunks flow through in real time.
 
-Factory function that creates a pre-configured Anthropic client pointing at the Skalpel proxy.
+## Headers
 
-### `extractMetadata(headers): SkalpelMetadata | null`
+The proxy adds these headers to every request forwarded to the Skalpel backend:
 
-Extracts optimization metadata from Skalpel response headers (`x-skalpel-*`).
+| Header | Value | Purpose |
+|---|---|---|
+| `X-Skalpel-API-Key` | Your Skalpel key | Backend authentication |
+| `X-Skalpel-Source` | `claude-code` | Traffic source identification |
+| `X-Skalpel-Agent-Type` | `claude-code` | Agent type for optimization routing |
+| `X-Skalpel-SDK-Version` | `proxy-1.0.0` | SDK version tracking |
 
-## Error Handling
+The original `x-api-key` header (your Anthropic key) is forwarded as-is.
 
-The SDK provides typed error classes:
+## Codex Support
 
-- `SkalpelAuthError` (401) — authentication failed. Never falls back.
-- `SkalpelTimeoutError` — request timed out.
-- `SkalpelRateLimitError` (429) — rate limit exceeded, includes `retryAfter`.
-- `SkalpelUnavailableError` (5xx) — proxy unavailable.
+Skalpel also supports OpenAI Codex on port 18101. The same `--auto` flow detects and configures both agents if present.
 
-When `fallbackOnError: true` (default), the SDK retries with exponential backoff, then falls back to the direct provider. Auth errors always throw immediately.
+## SDK Integration
 
-## Configuration
+For programmatic use in your own applications:
+
+```typescript
+import { createSkalpelClient } from 'skalpel';
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = createSkalpelClient(new Anthropic(), {
+  apiKey: process.env.SKALPEL_API_KEY!,
+});
+
+const response = await client.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+```
+
+See the [API Reference](#api-reference) for all SDK options.
+
+## API Reference
+
+### `createSkalpelClient<T>(client: T, options: SkalpelClientOptions): T`
+
+Wraps an existing OpenAI or Anthropic client. All API calls route through the Skalpel proxy with automatic fallback on errors.
+
+### `createSkalpelAnthropic(options): Promise<Anthropic>`
+
+Creates a pre-configured Anthropic client pointing at the Skalpel proxy.
+
+### `createSkalpelOpenAI(options): Promise<OpenAI>`
+
+Creates a pre-configured OpenAI client pointing at the Skalpel proxy.
+
+### Configuration Options
 
 ```typescript
 interface SkalpelClientOptions {
   apiKey: string;                  // Skalpel API key (sk-skalpel-*)
   workspace?: string;              // Workspace ID
-  baseURL?: string;                // Proxy URL (default: https://api.skalpel.ai)
+  baseURL?: string;                // Proxy URL (default: production ALB)
   fallbackOnError?: boolean;       // Fall back to direct provider (default: true)
   timeout?: number;                // Request timeout in ms (default: 30000)
   retries?: number;                // Max retries (default: 2)
-  headers?: Record<string, string>;// Additional custom headers
-  verbose?: boolean;               // Log fallback events (default: false)
-  onFallback?: (error, provider) => void;  // Callback on fallback
-  onMetadata?: (metadata) => void;         // Callback with optimization info
 }
 ```
 
-## TypeScript
-
-The SDK is written in TypeScript and ships with full type declarations. All types are exported:
+## Uninstall
 
-```typescript
-import type {
-  SkalpelClientOptions,
-  SkalpelMetadata,
-  SkalpelConfig,
-  SupportedProvider,
-  InitConfig,
-} from 'skalpel';
+```bash
+npx skalpel uninstall
 ```
+
+This removes the proxy, restores `~/.claude/settings.json` from backup, and cleans up shell environment variables.

package/dist/cli/index.js

@@ -1,5 +1,3 @@
-#!/usr/bin/env node
-
 // src/cli/index.ts
 import { Command } from "commander";
 import { createRequire as createRequire2 } from "module";