Wizard

Documentation Index

Fetch the complete documentation index at: https://docs.voight.xyz/llms.txt

Use this file to discover all available pages before exploring further.

cd your-app
npx -y @voightxyz/sdk init

​

What the wizard does

1. Detects providers. Reads package.json (both dependencies and devDependencies). If neither openai nor @anthropic-ai/sdk is found, the wizard aborts cleanly and explains what to install.
2. Detects package manager. Looks for pnpm-lock.yaml → yarn.lock → bun.lockb → falls back to npm. The install command printed at the end matches what you actually use.
3. Detects framework. Looks for next in deps. If present, the usage snippet at the end uses Next.js Route Handler shape (export async function POST); otherwise Express style (app.post('/api/chat', ...)).
4. Prompts for privacy level. Three options:
   • Minimal — metadata only (tokens, latency, cost). No prompts or responses captured.
   • Standard ★ — full content with 12-pattern PII scrubbing. Required for customer-facing apps where end-user PII flows through prompts.
   • Full — raw, no scrubbing. Debugging only.
5. Prompts for the Voight API key (vk_...). Validates it against api.voight.xyz before writing anything — typo’d keys get caught here, not in production.
6. Prompts for an agent name. Defaults to your package.json name; press enter to accept or type a custom one.
7. Writes src/lib/voight.ts (or lib/voight.ts if your project doesn’t have src/). Contains the wrapped clients for the providers it detected, plus a header comment explaining how to swap if your provider keys come from AWS Secrets Manager / Vault / Doppler instead of env.
8. Appends VOIGHT_KEY to .env.local. Creates the file if absent. Existing VOIGHT_KEY lines are left alone.
9. Prints the install command + usage snippet. The install command uses your package manager (e.g. pnpm add @voightxyz/openai @voightxyz/anthropic if pnpm-lock detected).

​

What it does NOT do

• ❌ Never touches ~/.claude, ~/.cursor, ~/.codex or any other path outside your project’s cwd. This is the key difference from setup (which wires IDE hooks globally).
• ❌ Never asks for or stores your provider keys (OPENAI_API_KEY, ANTHROPIC_API_KEY). Those belong to your app and stay there. The Voight wrapper instruments the requests but never reads the auth header.
• ❌ Never runs npm install for you. We print the command so you can run it in your terminal — that way you stay in control of your lockfile (and we don’t accidentally pin a version you didn’t approve).
• ❌ Never overrides an existing src/lib/voight.ts. If the file already exists, the wizard aborts and asks you to move it aside.

​

Example session

$ cd ~/projects/customer-support-saas
$ npx -y @voightxyz/sdk init

  Voight · init → /Users/jane/projects/customer-support-saas

  ✓ Detected providers: openai (^4.79.2) + @anthropic-ai/sdk (^0.96.0)
  ✓ Detected package manager: pnpm
  ✓ Detected framework: Next.js

  Privacy level for this project?

    1) Minimal · metadata only (tokens, latency, cost)
    2) Standard ★ Required for customer-facing apps — PII scrubbing on
    3) Full · raw, no scrubbing (debugging only)

  > 2

  ✓ Privacy: standard

  Now we need your Voight API key:
    1. Open  → https://voight.xyz/dashboard
    2. Sign in (Google / X / wallet)
    3. Settings → Generate key → copy the vk_… secret

  Paste it here: vk_aBcD…

  ✓ Validating key with api.voight.xyz…
  ✓ Key valid

  Agent name (defaults to "customer-support-saas")? production-chat-api

  ✓ Agent: production-chat-api

  ✓ Wrote src/lib/voight.ts
  ✓ Created .env.local with VOIGHT_KEY

  Use it in your handlers:

    // app/api/chat/route.ts
    import { openai, withTrace } from '@/lib/voight'

    export async function POST(req: Request) {
      return withTrace(
        async () => {
          const r = await openai.chat.completions.create({ ... })
          return Response.json({ reply: r.choices[0].message })
        },
        {
          routeTag: 'POST /api/chat',
          tags: { userId: 'user_123', plan: 'pro' },
        },
      )
    }

  One more step — install the wrappers:
    pnpm add @voightxyz/openai @voightxyz/anthropic

  Then open https://voight.xyz/dashboard/ai-apps

​

Generated file

// ──────────────────────────────────────────────────────────────────
// Voight observability — generated by `npx @voightxyz/sdk init`
//
// Both wrapped clients use the standard `new OpenAI()` /
// `new Anthropic()` constructors, which read OPENAI_API_KEY and
// ANTHROPIC_API_KEY from process.env. This is the convention for
// most apps (the values typically live in .env / .env.local).
//
// If your provider keys come from elsewhere (AWS Secrets Manager,
// HashiCorp Vault, Doppler, a database, etc.), adjust the
// constructor calls below to pass the key explicitly, e.g.:
//
//   const openai = wrapOpenAI(
//     new OpenAI({ apiKey: await loadFromVault('openai') }),
//     { agent: 'production-chat-api', privacy: 'standard' }
//   )
//
// The Voight wrapper never sees the provider key — it wraps
// whatever client you construct.
// ──────────────────────────────────────────────────────────────────

import OpenAI from 'openai'
import Anthropic from '@anthropic-ai/sdk'
import { wrapOpenAI } from '@voightxyz/openai'
import { wrapAnthropic } from '@voightxyz/anthropic'

export const openai = wrapOpenAI(new OpenAI(), {
  agent: 'production-chat-api',
  privacy: 'standard',
})

export const anthropic = wrapAnthropic(new Anthropic(), {
  agent: 'production-chat-api',
  privacy: 'standard',
})

// Re-exports — import everything from one place.
export { withTrace, log } from '@voightxyz/openai'

​

Non-interactive flags

npx -y @voightxyz/sdk init \
  --privacy=standard \
  --key=vk_aBcD... \
  --agent=production-chat-api

​

Manual install (skip the wizard)

​

Troubleshooting

npm install openai
npm install @anthropic-ai/sdk

​

Safety guarantees

• The CLI dispatches by sub-command name (setup / init / hook) — the setup branch runs first and returns before reaching init.
• init.ts has no imports from setup.ts. There’s no shared mutable state, no shared global config.
• init writes only inside process.cwd() — no homedir() calls, no ~/.config paths. The shape is enforced by the test suite (256 tests, including a structural assertion that init never produces a write path outside cwd).

​

Next

• OpenAI SDK — what the wrapped OpenAI client captures
• Anthropic SDK — what the wrapped Anthropic client captures
• Tracing — withTrace and log in depth
• Per-user spend — the tags.userId pattern the wizard’s snippet demonstrates
• AI Apps overview — the dashboard surface the wizard targets