<div align="center">

# Voxcode

### AI coding assistant for the terminal

**read · bash · edit · write** — in your terminal, with any LLM.

[![npm version](https://img.shields.io/npm/v/%40voxcode-dev%2Fvoxcode?color=6366f1&label=latest)](https://www.npmjs.com/package/@voxcode-dev/voxcode)
[![License: MIT](https://img.shields.io/badge/license-MIT-6366f1)](https://github.com/voxcode-dev/voxcode/blob/main/LICENSE)
[![Platform](https://img.shields.io/badge/-macOS%20|%20Linux%20|%20Windows-6366f1)](https://github.com/voxcode-dev/voxcode/blob/main/packages/voxcode/docs/windows.md)

</div>

---

```bash
npm i -g @voxcode-dev/voxcode

vox                           # interactive TUI
vox -p "Summarize this repo"  # one-shot
vox -c                        # resume session
vox -u                        # self-update
```

---

## At a Glance

| | |
|---|---|
| **Interactive TUI** | Full-screen terminal with diffs, file tree, session management |
| **One-shot mode** | `vox -p "prompt"` for CI, automation, quick queries |
| **Multi-LLM** | OpenAI, Anthropic, Gemini, Mistral, Groq, OpenRouter, Bedrock, Azure, Together AI, + custom |
| **Sessions** | Persist, resume, branch, compact across restarts |
| **Skills** | Packaged prompt workflows — review, test, migrate |
| **Extensions** | Custom tools, providers, lifecycle hooks |
| **Read-only** | `-t read,grep,find,ls` — audit without modification |

---

## Flags

```
  -p, --print                 Non-interactive (process and exit)
  -c, --continue              Continue previous session
  -r, --resume                Select session to resume
  -u, --update                Self-update
  -s, --session <id>          Use specific session
  -h, --help                  Show help
  -v, --version               Show version

  --provider <name>           LLM provider (default: google)
  --model <pattern>           Model ID (supports provider/id and :thinking)
  --thinking <level>          off | minimal | low | medium | high | xhigh
  --models <patterns>         Ctrl+P cycling (comma-separated, globs)
  -t, --tools <list>          Enable only these tools
  -nt, --no-tools             Disable all tools
  -e, --extension <path>      Load extension (repeatable)
  --skill <path>              Load skill file/dir (repeatable)
  -nc, --no-context-files     Disable AGENTS.md / CLAUDE.md
  --list-models [search]      List available models
  --export <file>             Export session to HTML
  --offline                   Skip network checks
```

## Commands

```
  install <source>       Install extension
  remove  <source>       Remove extension
  list                   List installed extensions
  config                 Manage resources (TUI)
  update self            Update voxcode
```

## Built-in Tools

```
  read    Read file contents       (always on)
  bash    Execute shell commands   (always on)
  edit    Find/replace edits       (always on)
  write   Create/overwrite files   (always on)
  grep    Search file contents     (off by default)
  find    Glob pattern search      (off by default)
  ls      List directories         (off by default)
```

## API Keys

```
  ANTHROPIC_API_KEY          Anthropic Claude
  OPENAI_API_KEY             OpenAI GPT
  GEMINI_API_KEY             Google Gemini
  MISTRAL_API_KEY            Mistral AI
  DEEPSEEK_API_KEY           DeepSeek
  OPENROUTER_API_KEY         OpenRouter (100+ models)
  GROQ_API_KEY               Groq
  AWS_PROFILE + AWS_REGION   Amazon Bedrock
  AZURE_OPENAI_API_KEY       Azure OpenAI
  XAI_API_KEY                xAI Grok
  FIREWORKS_API_KEY          Fireworks AI
  TOGETHER_API_KEY           Together AI
  CEREBRAS_API_KEY           Cerebras
  CLOUDFLARE_API_KEY         Cloudflare Workers AI
```

## Packages

| Package | Purpose |
|---------|---------|
| `voxcode` | CLI + runtime |
| `voxcode-ai` | LLM providers & models |
| `voxcode-agent` | Agent loop & orchestration |
| `voxcode-tui` | Terminal UI components |

Full docs: [github.com/voxcode-dev/voxcode](https://github.com/voxcode-dev/voxcode)

## License

MIT
