Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 21 additions & 9 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<coding_guidelines>
# Vox — Personal Terminal Agent
# Vox — Self-Learning Terminal Agent

## Build & Test
```bash
Expand All @@ -15,18 +15,29 @@ uv sync --extra voice
```

## Architecture
- `src/vox/cli.py` — Subcommand dispatcher: REPL, listen, speak, agent, config
- `src/vox/engine.py` — Ollama API client, response cleaning, general LLM queries
- `src/vox/cli.py` — Subcommand dispatcher: REPL, listen, speak, agent, learn, config
- `src/vox/engine.py` — Ollama API client, context-enriched prompts, response cleaning
- `src/vox/config.py` — TOML config (~/.config/vox/config.toml) with env overrides
- `src/vox/safety.py` — Dangerous command detection and non-shell response filtering
- `src/vox/executor.py` — Command execution and clipboard utilities
- `src/vox/knowledge.py` — SQLite self-learning store (6 context layers)
- `src/vox/voice/recorder.py` — Microphone capture via sounddevice
- `src/vox/voice/asr.py` — Speech-to-text (Parakeet 0.6B via mlx-audio)
- `src/vox/voice/tts.py` — Text-to-speech (Kokoro 82M via mlx-audio)
- `src/vox/agents/base.py` — Base agent interface with subprocess execution
- `src/vox/agents/router.py` — Auto-route tasks to best installed agent via LLM
- `src/vox/agents/{claude,codex,gemini,amp,droid}.py` — Headless agent wrappers
- `scripts/finetune/` — Dataset building and LoRA fine-tuning pipeline
- `install.sh` / `uninstall.sh` — curl-installable scripts
- `docs/index.html` — GitHub Pages landing

## Self-Learning (knowledge.py)
SQLite store at ~/.config/vox/knowledge.db with 6 layers:
1. Command patterns — validated NL-to-shell mappings (FTS5 indexed)
2. User corrections — rejected commands + corrected versions
3. Error patterns — commands that failed + error output
5. Agent learnings — which agent handles which task best
6. Session context — directory-aware recent commands

After 3+ successful uses, a pattern is served from cache (skipping LLM).

## Backend
Ollama API (local inference, no cloud). Default model: qwen2.5-coder:0.5b.
Expand All @@ -37,18 +48,19 @@ Agents: auto-discovers claude, codex, gemini, amp, droid in PATH.
```
vox # Interactive REPL
vox "find large files" # Single NL-to-shell
vox listen # Voice shell command
vox listen # Voice -> shell command
vox speak "hello" # Text-to-speech
vox agent "fix tests" # Delegate to AI agent (auto-routed)
vox agent --list # Show detected agents
vox agent --use claude "x" # Force specific agent
vox learn show # Show top learned patterns
vox learn stats # Knowledge store statistics
vox learn export -f p.json # Export patterns
vox config init # Create config template
vox config show # Display current config
```

## Conventions
- Python 3.10+, ruff for lint/format
- Keep core dependencies minimal (httpx, rich)
- Keep core dependencies minimal (httpx, rich, sqlite3)
- Voice/finetune deps are optional extras
- All shell commands single-line, no heredocs
</coding_guidelines>
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,15 @@ vox > find all python files bigger than 1MB
## Install

```bash
curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/install.sh | bash
```

**Requirements:** Python 3.9+, [Ollama](https://ollama.ai) for local inference.

## Uninstall

```bash
curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/uninstall.sh | bash
curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/uninstall.sh | bash
```

## Usage
Expand Down Expand Up @@ -106,7 +106,7 @@ Vox is a step toward a world where the terminal understands you — not the othe

## Model

Vox is powered by [NL2Shell](https://github.com/aryateja2106/nl2shell), a fine-tuned Qwen3.5-0.8B model trained specifically for natural language to shell command translation.
Vox is powered by [NL2Shell](https://github.com/nl2shell/nl2shell), a fine-tuned Qwen3.5-0.8B model trained specifically for natural language to shell command translation.

- **Parameters:** ~859M (runs on CPU, no GPU needed)
- **Training data:** 12,000+ deduplicated NL→bash pairs including 960+ expert-curated commands
Expand All @@ -118,7 +118,7 @@ You can also use any other Ollama model: `vox --model llama3.2`
## Contributing

```bash
git clone https://github.com/aryateja2106/vox.git
git clone https://github.com/nl2shell/vox.git
cd vox
uv sync
uv run python -m vox
Expand Down
16 changes: 8 additions & 8 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -300,7 +300,7 @@
<a href="#examples">Examples</a>
<a href="#why">Why Vox</a>
</div>
<a href="https://github.com/aryateja2106/vox" class="nav-github" target="_blank" rel="noopener">
<a href="https://github.com/nl2shell/vox" class="nav-github" target="_blank" rel="noopener">
&#9733; Star on GitHub
</a>
</nav>
Expand Down Expand Up @@ -331,11 +331,11 @@ <h1>Talk to your terminal.</h1>
<button class="tab-btn" onclick="switchTab('uninstall', this)">Uninstall</button>
</div>
<div id="tab-install" class="tab-content active">
<code>curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/install.sh | bash</code>
<code>curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/install.sh | bash</code>
<button class="copy-btn" onclick="copyCmd('install')">Copy</button>
</div>
<div id="tab-uninstall" class="tab-content">
<code>curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/uninstall.sh | bash</code>
<code>curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/uninstall.sh | bash</code>
<button class="copy-btn" onclick="copyCmd('uninstall')">Copy</button>
</div>
</div>
Expand Down Expand Up @@ -481,7 +481,7 @@ <h2>Three ways to use it.</h2>
<h2>Your terminal, finally fluent.</h2>
<p>Install in under 10 seconds. No setup. No config. No excuses.</p>
<div class="btn-group">
<a href="https://github.com/aryateja2106/vox" class="btn-primary" target="_blank" rel="noopener">
<a href="https://github.com/nl2shell/vox" class="btn-primary" target="_blank" rel="noopener">
&#9733; Star on GitHub
</a>
<a href="#" class="btn-secondary" onclick="document.querySelector('.install-box').scrollIntoView({behavior:'smooth'});return false;">
Expand All @@ -493,17 +493,17 @@ <h2>Your terminal, finally fluent.</h2>
<!-- FOOTER -->
<footer>
<p>
<a href="https://github.com/aryateja2106/vox" target="_blank" rel="noopener">github.com/aryateja2106/vox</a>
<a href="https://github.com/nl2shell/vox" target="_blank" rel="noopener">github.com/nl2shell/vox</a>
&nbsp;&mdash;&nbsp;
Built by <a href="https://github.com/aryateja2106" target="_blank" rel="noopener">Arya Teja</a>.
Built by <a href="https://github.com/nl2shell" target="_blank" rel="noopener">Arya Teja</a>.
Powered by <a href="https://huggingface.co/AryaYT/nl2shell-0.8b" target="_blank" rel="noopener">NL2Shell</a>.
</p>
</footer>

<script>
const cmds = {
install: 'curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/install.sh | bash',
uninstall: 'curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/uninstall.sh | bash'
install: 'curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/install.sh | bash',
uninstall: 'curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/uninstall.sh | bash'
};

function switchTab(name, btn) {
Expand Down
2 changes: 1 addition & 1 deletion install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ fi
echo -e " ${GREEN}✓${NC} Python $PY_VERSION"

# ── Install vox ──────────────────────────────────────────────────────────────
REPO="https://github.com/aryateja2106/vox.git"
REPO="https://github.com/nl2shell/vox.git"

if command -v pipx &>/dev/null; then
echo -e " ${DIM}Installing with pipx...${NC}"
Expand Down
11 changes: 6 additions & 5 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[project]
name = "vox-shell"
version = "0.3.0"
description = "Personal terminal agent. Voice, AI agents, and natural language to shell — all local."
version = "0.4.0"
description = "Self-learning terminal agent. Voice, AI agents, and natural language to shell — all local."
readme = "README.md"
license = "MIT"
requires-python = ">=3.10"
Expand Down Expand Up @@ -44,9 +44,9 @@ prerelease = "if-necessary-or-explicit"
vox = "vox.cli:main"

[project.urls]
Homepage = "https://aryateja2106.github.io/vox"
Repository = "https://github.com/aryateja2106/vox"
Issues = "https://github.com/aryateja2106/vox/issues"
Homepage = "https://nl2shell.github.io/vox"
Repository = "https://github.com/nl2shell/vox"
Issues = "https://github.com/nl2shell/vox/issues"

[build-system]
requires = ["hatchling"]
Expand Down Expand Up @@ -75,4 +75,5 @@ allowed-unresolved-imports = [
[dependency-groups]
dev = [
"pytest>=8.4.2",
"ruff>=0.15.9",
]
2 changes: 1 addition & 1 deletion src/vox/__init__.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
"""Vox — Talk to your terminal."""

__version__ = "0.3.0"
__version__ = "0.4.0"
Loading