@andypai/orb 0.1.1

package/prompts/anthropic.md

@@ -0,0 +1,2 @@
+The current project is "{{projectName}}" at {{projectPath}}.
+Always use this path when reading files or running commands.

package/prompts/base.md

@@ -0,0 +1 @@
+You are a helpful coding assistant.

package/prompts/openai.md

@@ -0,0 +1,7 @@
+The current project is "{{projectName}}", sourced from {{projectPath}}.
+Inside the provided tool sandbox, the project is mounted at `/workspace`.
+Use the provided `bash`, `readFile`, and `writeFile` tools to explore or edit files.
+Edits happen in a sandbox overlay; describe any changes you make.
+Never claim to be Claude or Anthropic; you are an OpenAI model.
+Prefer concise bash commands (`ls`, `rg`, `sed`, `awk`, `jq`) and keep outputs short.
+If you need to modify files, do so via `writeFile` so changes are explicit.

package/prompts/voice.md

@@ -0,0 +1,12 @@
+You are responding via voice.
+
+Guidelines for voice responses:
+
+- Keep responses concise: 2-4 sentences for simple questions, up to a paragraph for complex topics
+- Use conversational, natural language that sounds good when spoken aloud
+- Avoid code blocks, markdown formatting, bullet lists, and technical symbols
+- When discussing code, describe it verbally rather than showing syntax
+- End with a follow-up question or offer to elaborate if the topic warrants it
+- If a question requires showing code, briefly explain what you would write and ask if they'd like details
+
+Remember: your response will be read aloud, so optimize for listening, not reading.

package/src/cli.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+import { run } from './index.js'
+
+run(process.argv.slice(2)).catch((err) => {
+  // Commander throws with exitCode for --help, parse errors, etc.
+  if (err?.exitCode !== undefined) process.exit(err.exitCode)
+  console.error(err?.message ?? err)
+  process.exit(1)
+})

package/src/config.ts

@@ -0,0 +1,270 @@
+import { Command } from 'commander'
+import type { AnthropicModel, AppConfig, LlmModelId, LlmProvider, Voice } from './types'
+import { ANTHROPIC_MODELS, DEFAULT_CONFIG, VOICES } from './types'
+
+const PROVIDER_ALIASES: Record<string, LlmProvider> = {
+  anthropic: 'anthropic',
+  claude: 'anthropic',
+  openai: 'openai',
+  gpt: 'openai',
+}
+
+const ANTHROPIC_MODEL_ALIASES: Record<string, AnthropicModel> = {
+  opus: 'claude-opus-4-6',
+  haiku: 'claude-haiku-4-5-20251001',
+  sonnet: 'claude-sonnet-4-6',
+}
+
+const DEFAULT_MODEL_BY_PROVIDER: Record<LlmProvider, LlmModelId> = {
+  anthropic: 'claude-haiku-4-5-20251001',
+  openai: 'gpt-5.4',
+}
+
+function normalizeProvider(value: string): LlmProvider | undefined {
+  return PROVIDER_ALIASES[value.trim().toLowerCase()]
+}
+
+function normalizeAnthropicModel(value: string): LlmModelId {
+  const normalized = value.trim()
+  const alias = ANTHROPIC_MODEL_ALIASES[normalized]
+  if (alias) return alias
+  if (ANTHROPIC_MODELS.includes(normalized as AnthropicModel)) return normalized
+  return normalized || DEFAULT_MODEL_BY_PROVIDER.anthropic
+}
+
+function normalizeModelForProvider(provider: LlmProvider, value: string): LlmModelId {
+  if (provider === 'anthropic') return normalizeAnthropicModel(value)
+  return value.trim() || DEFAULT_MODEL_BY_PROVIDER.openai
+}
+
+function isAnthropicModel(value: string): boolean {
+  return ANTHROPIC_MODELS.includes(value as AnthropicModel) || value in ANTHROPIC_MODEL_ALIASES
+}
+
+function resolveModelForConfig(provider: LlmProvider, modelId: string): LlmModelId {
+  const normalized = normalizeModelForProvider(provider, modelId)
+  if (provider === 'openai' && isAnthropicModel(normalized)) {
+    return DEFAULT_MODEL_BY_PROVIDER.openai
+  }
+  return normalized
+}
+
+type ModelOverride = { provider?: LlmProvider; id: string }
+
+function parseModelArg(value: string): ModelOverride | undefined {
+  if (!value) return undefined
+  if (!value.includes(':')) return { id: value }
+
+  const [prefix, id] = value.split(':', 2)
+  const trimmedPrefix = prefix?.trim() ?? ''
+  const trimmedId = id?.trim() ?? ''
+  if (!trimmedPrefix || !trimmedId) return undefined
+
+  const provider = normalizeProvider(trimmedPrefix)
+  return provider ? { provider, id: trimmedId } : { id: value }
+}
+
+function positiveFloat(value: string): number {
+  const n = Number(value)
+  if (!Number.isFinite(n) || n <= 0) throw new Error(`Expected a positive number, got "${value}"`)
+  return n
+}
+
+function positiveInt(value: string): number {
+  const n = Number(value)
+  if (!Number.isInteger(n) || n <= 0) throw new Error(`Expected a positive integer, got "${value}"`)
+  return n
+}
+
+function nonNegativeInt(value: string): number {
+  const n = Number(value)
+  if (!Number.isInteger(n) || n < 0)
+    throw new Error(`Expected a non-negative integer, got "${value}"`)
+  return n
+}
+
+interface ProgramDefaults {
+  config: AppConfig
+}
+
+const HELP_EPILOGUE = `
+Auto provider selection (when --provider and --model are omitted):
+  1) Claude Agent SDK (Claude Code / Max or API key)
+  2) OPENAI_API_KEY
+  3) ANTHROPIC_API_KEY
+
+Examples:
+  orb                           # Current directory with defaults
+  orb /path/to/project          # Specific project
+  orb setup                     # Create ~/.orb/config.toml
+  orb --voice=marius
+  orb --provider=openai --model=gpt-5.4
+  orb --model=openai:gpt-5.4
+
+Controls:
+  - Type your question and press Enter
+  - Paste MacWhisper transcription with Cmd+V
+  - Shift+Tab to cycle models
+  - Ctrl+C to exit
+
+TTS quick start:
+  - Serve mode uses tts-gateway at http://localhost:8000 by default
+  - Run "orb setup" for guided defaults and gateway instructions
+  - Use --tts-mode=generate for local macOS fallback speech
+
+Config:
+  Persistent defaults live in ~/.orb/config.toml
+  CLI flags override config values for one-off runs`
+
+function createProgram({ config: defaults }: ProgramDefaults): Command {
+  const program = new Command()
+    .name('orb')
+    .description('Voice-Driven Code Explorer')
+    .argument('[projectPath]', 'Project directory path')
+    .option('--provider <provider>', 'LLM provider: anthropic|claude, openai|gpt')
+    .option('--llm-provider <provider>', 'LLM provider (alias for --provider)')
+    .option('--model <model>', 'Model ID, alias (haiku, sonnet, opus), or provider:model')
+    .option('--voice <voice>', `TTS voice: ${VOICES.join(', ')}`, defaults.ttsVoice)
+    .option(
+      '--tts-mode <mode>',
+      'TTS mode: serve (tts-gateway HTTP server), generate (local macOS say), server',
+      defaults.ttsMode,
+    )
+    .option('--tts-server-url <url>', 'Serve-mode tts-gateway URL (default: http://localhost:8000)')
+    .option('--tts-speed <rate>', 'TTS speed multiplier', positiveFloat, defaults.ttsSpeed)
+    .option('--new', 'Start fresh (ignore saved session)')
+    .option('--skip-intro', 'Skip the welcome animation')
+    .option('--tts', 'Enable text-to-speech (default: true)')
+    .option('--no-tts', 'Disable text-to-speech')
+    .option('--streaming-tts', 'Enable streaming TTS (default: true)')
+    .option('--no-streaming-tts', 'Disable streaming (batch mode)')
+    .addHelpText('after', HELP_EPILOGUE)
+    .configureOutput({
+      writeOut: (str) => process.stdout.write(str),
+      writeErr: (str) => process.stderr.write(str),
+    })
+    .exitOverride()
+
+  return program
+}
+
+interface ParsedOpts {
+  provider?: string
+  llmProvider?: string
+  model?: string
+  voice: string
+  ttsMode: string
+  ttsServerUrl?: string
+  ttsSpeed: number
+  new?: boolean
+  skipIntro?: boolean
+  tts?: boolean
+  streamingTts?: boolean
+}
+
+export interface ParseResult {
+  config: AppConfig
+  explicit: ExplicitFlags
+}
+
+export interface ExplicitFlags {
+  provider: boolean
+  model: boolean
+  ttsBufferSentences: boolean
+  ttsMinChunkLength: boolean
+  ttsMaxWaitMs: boolean
+  ttsGraceWindowMs: boolean
+  ttsClauseBoundaries: boolean
+}
+
+interface ParseCliOptions {
+  baseConfig?: AppConfig
+  baseExplicit?: Partial<ExplicitFlags>
+}
+
+function isUserSet(program: Command, name: string): boolean {
+  return program.getOptionValueSource(name) === 'cli'
+}
+
+export function parseCliArgs(args: string[], options: ParseCliOptions = {}): ParseResult {
+  const baseConfig = options.baseConfig ?? DEFAULT_CONFIG
+  const baseExplicit = options.baseExplicit ?? {}
+  const program = createProgram({ config: baseConfig })
+  program.parse(args, { from: 'user' })
+
+  const opts = program.opts<ParsedOpts>()
+  const projectPath = program.args[0] ?? baseConfig.projectPath
+
+  const config: AppConfig = {
+    ...baseConfig,
+    projectPath,
+    startFresh: opts.new ?? false,
+    skipIntro: isUserSet(program, 'skipIntro') ? opts.skipIntro === true : baseConfig.skipIntro,
+    ttsEnabled: isUserSet(program, 'tts') ? opts.tts !== false : baseConfig.ttsEnabled,
+    ttsStreamingEnabled: isUserSet(program, 'streamingTts')
+      ? opts.streamingTts !== false
+      : baseConfig.ttsStreamingEnabled,
+    ttsSpeed: opts.ttsSpeed,
+  }
+
+  // Voice validation
+  if (VOICES.includes(opts.voice as Voice)) {
+    config.ttsVoice = opts.voice as Voice
+  }
+
+  // TTS mode (normalize "server" → "serve")
+  const ttsMode = opts.ttsMode
+  if (ttsMode === 'generate' || ttsMode === 'serve') {
+    config.ttsMode = ttsMode
+  } else if (ttsMode === 'server') {
+    config.ttsMode = 'serve'
+  }
+
+  // TTS server URL
+  if (opts.ttsServerUrl) {
+    config.ttsServerUrl = opts.ttsServerUrl.trim()
+    if (config.ttsMode === 'generate') config.ttsMode = 'serve'
+  }
+
+  // Clause boundaries (Commander handles --no- prefix)
+  // Provider and model resolution
+  const providerRaw = opts.provider ?? opts.llmProvider
+  let providerOverride: LlmProvider | undefined
+  if (providerRaw) {
+    providerOverride = normalizeProvider(providerRaw)
+  }
+
+  let modelOverride: ModelOverride | undefined
+  if (opts.model) {
+    modelOverride = parseModelArg(opts.model.trim())
+  }
+
+  if (modelOverride?.provider) {
+    config.llmProvider = modelOverride.provider
+  } else if (providerOverride) {
+    config.llmProvider = providerOverride
+  }
+
+  if (modelOverride) {
+    config.llmModel = resolveModelForConfig(config.llmProvider, modelOverride.id)
+  } else if (providerOverride) {
+    config.llmModel = DEFAULT_MODEL_BY_PROVIDER[config.llmProvider]
+  }
+
+  const explicit: ExplicitFlags = {
+    provider:
+      baseExplicit.provider === true ||
+      isUserSet(program, 'provider') ||
+      isUserSet(program, 'llmProvider'),
+    model: baseExplicit.model === true || isUserSet(program, 'model'),
+    ttsBufferSentences: baseExplicit.ttsBufferSentences === true,
+    ttsMinChunkLength: baseExplicit.ttsMinChunkLength === true,
+    ttsMaxWaitMs: baseExplicit.ttsMaxWaitMs === true,
+    ttsGraceWindowMs: baseExplicit.ttsGraceWindowMs === true,
+    ttsClauseBoundaries: baseExplicit.ttsClauseBoundaries === true,
+  }
+
+  return { config, explicit }
+}
+
+export { DEFAULT_CONFIG, DEFAULT_MODEL_BY_PROVIDER }

package/src/index.ts

@@ -0,0 +1,82 @@
+import React from 'react'
+import { render } from 'ink'
+import { App } from './ui/App'
+import { DEFAULT_CONFIG, DEFAULT_MODEL_BY_PROVIDER, parseCliArgs } from './config'
+import type { ExplicitFlags } from './config'
+import type { AppConfig } from './types'
+import { applyGlobalConfig, loadGlobalConfig } from './services/global-config'
+import { resolveSmartProvider } from './services/provider-defaults'
+import { loadSession } from './services/session'
+import { runSetupCommand } from './setup'
+
+export { App } from './ui/App'
+export { parseCliArgs, DEFAULT_CONFIG } from './config'
+export type { AnthropicModel, AppConfig, LlmModelId, LlmProvider, Voice } from './types'
+
+const OPENAI_STREAMING_DEFAULTS = {
+  ttsBufferSentences: 3,
+  ttsMinChunkLength: 60,
+  ttsMaxWaitMs: 600,
+  ttsGraceWindowMs: 200,
+  ttsClauseBoundaries: true,
+}
+
+function applyOpenAiStreamingDefaults(config: AppConfig, explicit: ExplicitFlags) {
+  if (config.llmProvider !== 'openai') return
+  if (!config.ttsEnabled || !config.ttsStreamingEnabled) return
+
+  if (!explicit.ttsBufferSentences) {
+    config.ttsBufferSentences = OPENAI_STREAMING_DEFAULTS.ttsBufferSentences
+  }
+  if (!explicit.ttsMinChunkLength) {
+    config.ttsMinChunkLength = OPENAI_STREAMING_DEFAULTS.ttsMinChunkLength
+  }
+  if (!explicit.ttsMaxWaitMs) {
+    config.ttsMaxWaitMs = OPENAI_STREAMING_DEFAULTS.ttsMaxWaitMs
+  }
+  if (!explicit.ttsGraceWindowMs) {
+    config.ttsGraceWindowMs = OPENAI_STREAMING_DEFAULTS.ttsGraceWindowMs
+  }
+  if (!explicit.ttsClauseBoundaries) {
+    config.ttsClauseBoundaries = OPENAI_STREAMING_DEFAULTS.ttsClauseBoundaries
+  }
+}
+
+export async function run(args: string[]): Promise<void> {
+  const command = args[0]
+  if (command === 'setup') {
+    await runSetupCommand(args.slice(1))
+    return
+  }
+
+  const globalConfig = await loadGlobalConfig()
+  for (const warning of globalConfig.warnings) {
+    console.warn(`[orb] ${warning}`)
+  }
+
+  const baseConfig = applyGlobalConfig(DEFAULT_CONFIG, globalConfig.config)
+  const { config, explicit } = parseCliArgs(args, {
+    baseConfig,
+    baseExplicit: globalConfig.explicit,
+  })
+  if (!explicit.provider && !explicit.model) {
+    const smartProvider = await resolveSmartProvider(config)
+    if (!smartProvider) {
+      console.error(
+        'No available LLM credentials found. Set up Claude (Max/OAuth), OPENAI_API_KEY, or ANTHROPIC_API_KEY before starting.\n' +
+          'Tip: Use --provider anthropic (with ANTHROPIC_API_KEY) or --provider openai (with OPENAI_API_KEY) to bypass auto-detection.',
+      )
+      process.exit(1)
+    }
+    config.llmProvider = smartProvider.provider
+    if (!explicit.model) {
+      config.llmModel = DEFAULT_MODEL_BY_PROVIDER[smartProvider.provider]
+    }
+  }
+  applyOpenAiStreamingDefaults(config, explicit)
+  const initialSession = config.startFresh ? null : await loadSession(config.projectPath)
+
+  render(React.createElement(App, { config, initialSession }), {
+    patchConsole: true,
+  })
+}

package/src/pipeline/adapters/anthropic.ts

@@ -0,0 +1,111 @@
+import { query, type SDKMessage } from '@anthropic-ai/claude-agent-sdk'
+import { buildProviderPrompt } from '../../services/prompts'
+import type { Frame } from '../frames'
+import { createFrame } from '../frames'
+import type { AgentAdapter, AgentAdapterConfig } from './types'
+import {
+  getContentBlocks,
+  isTextBlock,
+  isToolUseBlock,
+  isToolResultBlock,
+  extractToolResultText,
+} from './utils'
+
+export function createAnthropicAdapter(config: AgentAdapterConfig): AgentAdapter {
+  return {
+    async *stream(prompt: string): AsyncIterable<Frame> {
+      const { appConfig, session, abortController } = config
+      let activeSessionId = session?.provider === 'anthropic' ? session.sessionId : undefined
+      let accumulatedText = ''
+      let toolIndex = 0
+      const toolIdToIndex = new Map<string, number>()
+      const systemPrompt = await buildProviderPrompt({
+        provider: 'anthropic',
+        projectPath: appConfig.projectPath,
+        ttsEnabled: appConfig.ttsEnabled,
+      })
+
+      const response = query({
+        prompt,
+        options: {
+          cwd: appConfig.projectPath,
+          model: appConfig.llmModel,
+          maxTurns: 10,
+          resume: activeSessionId,
+          permissionMode: 'default',
+          abortController,
+          systemPrompt,
+        },
+      })
+
+      for await (const message of response) {
+        const typed = message as SDKMessage
+
+        if (typed.type === 'system' && typed.subtype === 'init') {
+          const newSessionId = (typed as { session_id?: string }).session_id
+          if (newSessionId) {
+            activeSessionId = newSessionId
+            yield createFrame('agent-session', {
+              session: { provider: 'anthropic', sessionId: newSessionId },
+            })
+          }
+          continue
+        }
+
+        if (typed.type === 'assistant') {
+          const blocks = getContentBlocks(typed.message)
+          for (const block of blocks) {
+            if (isTextBlock(block)) {
+              accumulatedText += block.text
+              yield createFrame('agent-text-delta', {
+                delta: block.text,
+                accumulatedText,
+              })
+              continue
+            }
+            if (isToolUseBlock(block)) {
+              const toolId = block.id ?? block.tool_use_id ?? `tool-${toolIndex}`
+              const index = toolIdToIndex.get(toolId) ?? toolIndex++
+              toolIdToIndex.set(toolId, index)
+              yield createFrame('tool-call-start', {
+                toolCall: {
+                  id: toolId,
+                  index,
+                  name: block.name,
+                  input: block.input ?? {},
+                  status: 'running',
+                },
+              })
+            }
+          }
+          continue
+        }
+
+        if (typed.type === 'user') {
+          const blocks = getContentBlocks(typed.message)
+          for (const block of blocks) {
+            if (!isToolResultBlock(block)) continue
+            const toolUseId = block.tool_use_id ?? block.id
+            const index = toolUseId ? toolIdToIndex.get(toolUseId) : undefined
+            if (index === undefined) continue
+            const resultText = extractToolResultText(block.content)
+            yield createFrame('tool-call-result', {
+              toolIndex: index,
+              result: resultText,
+              status: block.is_error ? 'error' : 'complete',
+            })
+          }
+        }
+
+        if (typed.type === 'result' && typed.subtype === 'success') {
+          yield createFrame('agent-text-complete', {
+            text: typed.result || accumulatedText,
+            session: activeSessionId
+              ? { provider: 'anthropic', sessionId: activeSessionId }
+              : undefined,
+          })
+        }
+      }
+    },
+  }
+}