skalpel 1.3.0 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Skalpel AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,116 +1,188 @@
-# 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 coding agents on your machine
+- Configure Claude Code and Codex agents automatically
+- Set shell environment variables in your `.bashrc`/`.zshrc`
+- Begin optimizing 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. Run the setup wizard to configure Claude Code
+npx skalpel setup
 
-const response = await openai.chat.completions.create({
-  model: 'gpt-4o',
-  messages: [{ role: 'user', content: 'Hello' }],
-});
+# 3. Verify everything is working
+npx skalpel doctor
 ```
 
-## CLI Setup
+## What Gets Configured
+
+### Claude Code
+
+Claude Code is auto-configured during setup. `ANTHROPIC_BASE_URL` is set in `~/.claude/settings.json` to route API calls through the proxy. Only API endpoints (`/v1/messages`, `/v1/complete`) are routed through Skalpel for optimization; auth endpoints pass directly to Anthropic.
+
+### 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
 
-Factory function that creates a pre-configured Anthropic client pointing at the Skalpel proxy.
+Skalpel fully supports Anthropic's SSE streaming protocol. When Claude Code sends a streaming request (`"stream": true`), the proxy:
 
-### `extractMetadata(headers): SkalpelMetadata | null`
+- 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`
 
-Extracts optimization metadata from Skalpel response headers (`x-skalpel-*`).
+No buffering, no modification of the stream — chunks flow through in real time.
 
-## Error Handling
+## Headers
 
-The SDK provides typed error classes:
+The proxy adds these headers to every request forwarded to the Skalpel backend:
 
-- `SkalpelAuthError` (401) — authentication failed. Never falls back.
-- `SkalpelTimeoutError` — request timed out.
-- `SkalpelRateLimitError` (429) — rate limit exceeded, includes `retryAfter`.
-- `SkalpelUnavailableError` (5xx) — proxy unavailable.
+| 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 |
 
-When `fallbackOnError: true` (default), the SDK retries with exponential backoff, then falls back to the direct provider. Auth errors always throw immediately.
+The original `x-api-key` header (your Anthropic key) is forwarded as-is.
 
-## Configuration
+## Codex Support
+
+Skalpel also supports OpenAI Codex on port 18101. The same `--auto` flow detects and configures both agents if present.
+
+## SDK Integration
+
+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 and cleans up shell environment variables. If a previous version of Skalpel modified `~/.claude/settings.json`, uninstall will also clean up those changes.