{"_id":"@andypai/orb","_rev":"2-10ea86e6df1c2468dee512d73d4a149e","name":"@andypai/orb","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.1":{"name":"@andypai/orb","version":"0.1.1","keywords":["ai","voice","tts","code-explorer","cli","terminal","openai","anthropic"],"author":{"name":"Andy Pai"},"license":"MIT","_id":"@andypai/orb@0.1.1","maintainers":[{"name":"andypai.me","email":"andy@r2pi.co"}],"homepage":"https://github.com/andypai/orb#readme","bugs":{"url":"https://github.com/andypai/orb/issues"},"bin":{"orb":"src/cli.ts"},"dist":{"shasum":"2f5ba07771718cea4dc9a4cb109325f00698694b","tarball":"https://registry.npmjs.org/@andypai/orb/-/orb-0.1.1.tgz","fileCount":56,"integrity":"sha512-lr+mf5uVpm4UjslHLb5a95tOnYaiM09U44Z3rhHgp98x9GknGQCNPAC2d+7OsJwDmwKwWPFraYNLLXPbbu8M9w==","signatures":[{"sig":"MEUCIQCizPwp+f/jcMNaxEmVudCs/1WCzE+q0L39QSzsxcroHwIgWL/2qbYiVw3YDyOO6o2+yOWnYX/Uc+757nEwYoorBtg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":168013},"type":"module","engines":{"bun":">=1.1.0"},"gitHead":"c4e2d002f1c5d31bcd89ef5ba4a5204ab83da343","scripts":{"dev":"bun --watch src/cli.ts","test":"bun test","check":"bunx prettier --check . && bun run test","start":"bun src/cli.ts","format":"bunx prettier --write ."},"_npmUser":{"name":"andypai.me","email":"andy@r2pi.co"},"repository":{"url":"git+https://github.com/andypai/orb.git","type":"git"},"_npmVersion":"11.11.0","description":"Voice-driven code explorer for your terminal","directories":{},"_nodeVersion":"24.12.0","dependencies":{"ai":"6.0.134","ink":"6.6.0","zod":"4.1.8","react":"19.2.3","@inkjs/ui":"2.0.0","bash-tool":"^1.3.9","commander":"^14.0.3","just-bash":"^2.7.0","@iarna/toml":"^2.2.5","@ai-sdk/openai":"3.0.47","@clack/prompts":"^1.0.1","@anthropic-ai/claude-agent-sdk":"0.2.80"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.3.3","devDependencies":{"prettier":"^3.7.4","@types/bun":"^1.1.22","typescript":"^5.7.2","@types/react":"19.2.9","ink-testing-library":"4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/orb_0.1.1_1774413617226_0.6937531188262493","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@andypai/orb","version":"0.2.0","description":"Voice-driven code explorer for your terminal","homepage":"https://github.com/andypai/orb#readme","bugs":{"url":"https://github.com/andypai/orb/issues"},"type":"module","bin":{"orb":"src/cli.ts"},"engines":{"bun":">=1.1.0"},"packageManager":"bun@1.3.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/andypai/orb.git"},"keywords":["ai","voice","tts","code-explorer","cli","terminal","openai","anthropic"],"author":{"name":"Andy Pai"},"license":"MIT","scripts":{"dev":"bun --watch src/cli.ts","start":"bun src/cli.ts","format":"bunx prettier --write .","typecheck":"bunx tsc --noEmit","check":"bunx prettier --check . && bun run typecheck && bun run test","test":"bun test"},"dependencies":{"@clack/prompts":"^1.1.0","@ai-sdk/openai":"3.0.47","@anthropic-ai/claude-agent-sdk":"0.2.80","@inkjs/ui":"2.0.0","@iarna/toml":"^2.2.5","ai":"6.0.134","bash-tool":"^1.3.9","commander":"^14.0.3","ink":"6.6.0","just-bash":"^2.7.0","react":"19.2.3","zod":"4.1.8"},"devDependencies":{"@types/bun":"^1.1.22","@types/react":"19.2.9","ink-testing-library":"4.0.0","prettier":"^3.7.4","typescript":"^5.7.2"},"gitHead":"3928473eca524b3485d230e6227f777fa98316e6","_id":"@andypai/orb@0.2.0","_nodeVersion":"25.8.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-QRU8k+TxDJF2Zg2l+RaIVNPEF0DO688hJA9brpz105h45JQlJF7PJNJaklbf/4OqQeeNThOVJwEowYIAJfsf3g==","shasum":"0b812ebad25df5874b5d5b8b947634785739f4b2","tarball":"https://registry.npmjs.org/@andypai/orb/-/orb-0.2.0.tgz","fileCount":57,"unpackedSize":175769,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDYJbUh0KpwHvpc/HCCdWoUJMrzsekpd+wa6pzKciDGvAiEA0rrkG09es4/06DtHMNQjUF9+6siS6dxOhBZv/CcOWDw="}]},"_npmUser":{"name":"andypai.me","email":"andy@r2pi.co"},"directories":{},"maintainers":[{"name":"andypai.me","email":"andy@r2pi.co"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/orb_0.2.0_1775270266894_0.43868530169846975"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-25T04:40:17.151Z","modified":"2026-04-04T02:37:47.170Z","0.1.1":"2026-03-25T04:40:17.412Z","0.2.0":"2026-04-04T02:37:47.044Z"},"bugs":{"url":"https://github.com/andypai/orb/issues"},"author":{"name":"Andy Pai"},"license":"MIT","homepage":"https://github.com/andypai/orb#readme","keywords":["ai","voice","tts","code-explorer","cli","terminal","openai","anthropic"],"repository":{"type":"git","url":"git+https://github.com/andypai/orb.git"},"description":"Voice-driven code explorer for your terminal","maintainers":[{"name":"andypai.me","email":"andy@r2pi.co"}],"readme":"<p align=\"center\">\n  <img src=\"./assets/orb-wordmark.svg\" alt=\"orb\" width=\"920\" />\n</p>\n\n<p align=\"center\">\n  Voice-driven code explorer for your terminal. Ask questions about your codebase, watch tool calls live, and optionally hear answers spoken aloud while they stream.\n</p>\n\n<p align=\"center\">\n  <img src=\"./assets/orb-terminal-session.svg\" alt=\"Orb running in the terminal with live tool activity and an architecture summary.\" width=\"1100\" />\n</p>\n\n## Why Orb\n\nOrb is a Bun-native terminal app for exploring real codebases with Anthropic or OpenAI models. It keeps the interface focused, shows tool activity as it happens, remembers project conversations, and can read answers aloud through `tts-gateway` or macOS `say`.\n\n## Features\n\n- **Natural language queries** - Ask questions about your code in plain English\n- **Live tool activity** - See file reads, shell commands, and exploration steps as they happen\n- **Voice input friendly** - Paste transcriptions from MacWhisper for hands-free interaction\n- **Streaming TTS (serve mode)** - Hear answers while they are still being generated\n- **Provider selection** - Choose Anthropic (Claude) or OpenAI via CLI flags\n- **Model switching (Claude)** - Cycle Anthropic models during a conversation with Shift+Tab\n- **Session persistence** - Automatically resume the last session per project\n- **Focused terminal UI** - Ink-based interface with conversation history, tool activity, and the Orb intro\n\n## Installation\n\n### Global install\n\n```bash\n# With Bun\nbun install -g @andypai/orb\n\n# With npm (Bun is still required at runtime)\nnpm install -g @andypai/orb\n```\n\n### Local / one-off use\n\n```bash\n# Run without installing globally\nbunx @andypai/orb\n\n# Add to a Bun project\nbun add @andypai/orb\n\n# npm also works, but Bun is still required at runtime\nnpm install @andypai/orb\n```\n\n## 60-Second Quick Start\n\n### 1. Set up an LLM provider\n\n- Anthropic: sign in with Claude Code / Max, or set `ANTHROPIC_API_KEY`\n- OpenAI: set `OPENAI_API_KEY`\n\nIf you do not pass `--provider` or `--model`, Orb auto-selects a provider in this order:\n\n1. Claude Agent SDK (Claude Code / Max or API key)\n2. `OPENAI_API_KEY`\n3. `ANTHROPIC_API_KEY`\n\n### 2. Pick your speech path\n\n#### Fastest path with no speech\n\n```bash\norb --no-tts\n```\n\n#### Fastest path on macOS (batch speech)\n\n```bash\norb --tts-mode=generate\n```\n\nGenerate mode uses macOS built-ins (`say` and `afplay`) and does not require `tts-gateway`.\n\n#### Recommended path for streaming speech\n\n```bash\nuv tool install tts-gateway[kokoro]\n~/.local/share/uv/tools/tts-gateway/bin/python -m spacy download en_core_web_sm\ntts serve --provider kokoro --port 8000\n```\n\nThat spaCy install is important: Kokoro’s first request will crash in a plain `uv tool` install unless `en_core_web_sm` is installed into the `tts-gateway` tool environment.\n\nOrb expects `tts-gateway` at `http://localhost:8000` by default. Batch speech uses\n`POST /v1/speech`, and streaming playback uses `POST /tts/stream`.\nFor the lowest-latency stream playback, install `mpv` or `ffplay`.\n\n### 3. Run Orb\n\n```bash\n# Explore the current directory\norb\n\n# Guided setup for persistent defaults\norb setup\n\n# Explore a specific project\norb /path/to/project\n```\n\n## Usage\n\n```bash\n# Anthropic with options\norb --model=sonnet --voice=marius\norb --provider=anthropic --model=opus\n\n# OpenAI provider\norb --provider=openai --model=gpt-5.4\norb --model=openai:gpt-5.4\n\n# Fresh conversation\norb --new\n\n# Skip the intro animation\norb --skip-intro\n```\n\n### Options\n\n| Option                   | Description                                                                    | Default                                 |\n| ------------------------ | ------------------------------------------------------------------------------ | --------------------------------------- |\n| `--provider=<provider>`  | LLM provider: `anthropic`\\|`claude`, `openai`\\|`gpt` (alias: `--llm-provider`) | `auto`                                  |\n| `--model=<model>`        | Model ID or alias (`haiku`, `sonnet`, `opus`) or `provider:model`              | `haiku` (anthropic), `gpt-5.4` (openai) |\n| `--voice=<voice>`        | TTS voice: `alba`, `marius`, `jean`                                            | `alba`                                  |\n| `--tts-mode=<mode>`      | `serve` for `tts-gateway`, `generate` for local macOS `say`                    | `serve`                                 |\n| `--tts-server-url=<url>` | Serve-mode gateway URL                                                         | `http://localhost:8000`                 |\n| `--tts-speed=<rate>`     | TTS speed multiplier                                                           | `1.5`                                   |\n| `--new`                  | Start fresh (ignore saved session)                                             | -                                       |\n| `--skip-intro`           | Skip the welcome animation                                                     | -                                       |\n| `--no-tts`               | Disable text-to-speech                                                         | -                                       |\n| `--no-streaming-tts`     | Disable streaming (batch mode)                                                 | -                                       |\n| `--help`                 | Show help message                                                              | -                                       |\n\n### Controls\n\n- Type your question and press **Enter** to submit\n- Paste MacWhisper transcription with **Cmd+V**\n- Press **Esc** or **Ctrl+S** to stop speech\n- Press **Shift+Tab** to cycle Claude models (Anthropic only)\n- Press **Ctrl+O** to toggle live tool-call details\n- Press **Ctrl+C** to exit\n\n## TTS Setup\n\nOrb supports two TTS paths:\n\n- **Serve mode** (default): send speech requests to a local `tts-gateway` server\n- **Generate mode**: use macOS built-in `say` for local fallback speech\n\n### Serve mode\n\nServe mode gives Orb the best experience for low-latency streaming speech.\nOrb streams from the gateway's `/tts/stream` endpoint when streaming TTS is enabled,\nand falls back to the regular `/v1/speech` path for batch generation.\n\n#### Install and start `tts-gateway`\n\n```bash\nuv tool install tts-gateway[kokoro]\n~/.local/share/uv/tools/tts-gateway/bin/python -m spacy download en_core_web_sm\ntts serve --provider kokoro --port 8000\n```\n\n#### Verify the server\n\n```bash\ncurl http://localhost:8000/health\ncurl -X POST http://localhost:8000/v1/speech -F 'text=hello from orb' -o /tmp/orb-check.mp3\n```\n\nThen run Orb with defaults:\n\n```bash\norb\n```\n\nFor true streamed playback, install `mpv` or `ffplay` locally. If neither is available,\nOrb falls back to saved-file playback where the local platform supports it.\n\nIf you use a different host or port:\n\n```bash\norb --tts-server-url=http://localhost:9000\n```\n\nYou can also save that value permanently with `orb setup` or `tts.server_url` in `~/.orb/config.toml`.\n\n#### Voice notes\n\nOrb exposes three portable voice presets: `alba`, `marius`, and `jean`.\n\nSome `tts-gateway` providers use different internal voice names. Orb already retries once without an explicit voice if the gateway rejects a preset, so a working server default will still speak.\n\n### Generate mode\n\nOn macOS, generate mode works out of the box with the built-in `say` command:\n\n```bash\norb --tts-mode=generate\n```\n\nIf you want advanced voices, non-macOS support, or streaming playback while the model is still responding, use serve mode with `tts-gateway` instead.\n\n### Disable TTS\n\n```bash\norb --no-tts\n```\n\n## Provider Setup\n\nOrb supports two LLM providers: **Anthropic (Claude)** and **OpenAI**.\n\n### Anthropic (default)\n\nAnthropic uses the Claude Agent SDK. Orb can reuse a local Claude Code / Max-authenticated session when available, or fall back to `ANTHROPIC_API_KEY` / `CLAUDE_API_KEY`.\n\n#### Quick start\n\n```bash\n# Uses Anthropic by default when available\norb\n\n# Explicitly specify Anthropic\norb --provider=anthropic\n\n# Use model aliases\norb --model=haiku\norb --model=sonnet\norb --model=opus\n\n# Or use a full model ID\norb --model=claude-haiku-4-5-20251001\n```\n\n#### Available models\n\n- `claude-haiku-4-5-20251001` (default, alias: `haiku`)\n- `claude-sonnet-4-6` (alias: `sonnet`)\n- `claude-opus-4-6` (alias: `opus`)\n\nIf you are not already signed in through Claude Code / Max, set `ANTHROPIC_API_KEY` or `CLAUDE_API_KEY` before starting Orb.\n\nFor setup details, see the [Claude Agent SDK quickstart](https://platform.claude.com/docs/en/agent-sdk/quickstart) and the [Claude models overview](https://platform.claude.com/docs/en/about-claude/models/overview).\n\n### OpenAI\n\nOpenAI support uses the official OpenAI Responses API and requires `OPENAI_API_KEY`.\n\n#### Quick start\n\n```bash\nexport OPENAI_API_KEY=sk-...\n\norb --provider=openai\norb --provider=openai --model=gpt-5.4\norb --model=openai:gpt-5.4\n```\n\n#### Common models\n\n- `gpt-5.4` (default for OpenAI)\n- `gpt-5`\n- `gpt-4o`\n- `gpt-5.4-mini`\n\n> Note: OpenAI runs in a sandboxed environment via `bash-tool`. File edits happen in a sandbox overlay and are not applied directly to your working tree. Orb will describe changes it made so you can apply them yourself.\n\n## Global Config\n\nPersistent defaults live in `~/.orb/config.toml`. CLI flags override config values for one-off runs.\n\nThe easiest way to create the file is:\n\n```bash\norb setup\n```\n\nA typical config looks like:\n\n```toml\nprovider = \"anthropic\"\nmodel = \"claude-haiku-4-5-20251001\"\nskip_intro = false\n\n[tts]\nenabled = true\nstreaming = true\nmode = \"serve\"\nserver_url = \"http://localhost:8000\"\nvoice = \"alba\"\nspeed = 1.5\nbuffer_sentences = 1\nclause_boundaries = false\nmin_chunk_length = 15\nmax_wait_ms = 150\ngrace_window_ms = 50\n```\n\nConfig-only advanced tuning keys live under `[tts]`:\n\n- `buffer_sentences`\n- `clause_boundaries`\n- `min_chunk_length`\n- `max_wait_ms`\n- `grace_window_ms`\n\nSessions are stored under `~/.orb/sessions/` (one per project).\n\n## Customizing Prompts\n\nOrb’s built-in instructions live in the root-level `prompts/` directory:\n\n- `prompts/base.md` for shared behavior\n- `prompts/anthropic.md` for Anthropic-specific system instructions\n- `prompts/openai.md` for OpenAI-specific tool and sandbox instructions\n- `prompts/voice.md` for voice-mode guidance added when TTS is enabled\n\nPrompt files are read fresh for each run, so edits apply to the next question without rebuilding the app.\n\n## Requirements\n\n- **Runtime**: Bun >= 1.1\n- **LLM provider**: Anthropic or OpenAI authentication\n- **TTS** (optional): `tts-gateway` for serve mode, or macOS `say` and `afplay` for generate mode\n\n## Development\n\n```bash\ngit clone https://github.com/andypai/orb.git\ncd orb\nbun install\n\n# Run in development\nbun run dev\n\n# Run with OpenAI\nbun run dev --provider=openai --model=gpt-5.4\n\n# Checks\nbun run check\nbun run typecheck\nbun run test\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}