Metadata-Version: 2.4
Name: queravel-cli
Version: 0.9.33
Summary: Queravel CLI — an agentic coding assistant for the terminal
Author: Queravel
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.40
Requires-Dist: rich>=13.7
Requires-Dist: textual>=0.80
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: mcp>=1.0
Requires-Dist: python-socketio[client]>=5.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: certifi>=2024.0
Requires-Dist: sounddevice>=0.4
Requires-Dist: numpy>=1.24
Requires-Dist: websockets>=12
Requires-Dist: segno>=1.5
Provides-Extra: anthropic
Requires-Dist: anthropic>=1.0; extra == "anthropic"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# Queravel CLI

An agentic coding assistant for your terminal — reads and writes your local codebase, runs
builds/tests/git, and drives long-running tasks — built on Queravel's agent engine. Runs on the
free **Queravel** models by default (Kimi K3 / GLM 5.3 Flash / DeepSeek V4.1 Flash) — **no third-party
API keys required**.

> **Status:** Phase 1 core is live: Textual TUI, diff review, **plan mode + permission modes**,
> **todos**, **sub-agents**, and **context auto-compaction**. It finds code by **agentic search
> (grep/glob/read) — no RAG, no index**. See `memory/phase-status.md`.

## Install

```bash
# One-liner (macOS / Linux) — installs the binary + keeps it auto-updated:
curl -fsSL https://queravel.com/install.sh | sh
#   Windows (PowerShell):  irm https://queravel.com/install.ps1 | iex

# Homebrew:
brew install SiliconBlast/queravel/queravel

# Python (pipx):
pipx install queravel-cli

# From a clone (dev):
git clone <repo> && cd queravel-cli && make dev
```

Then run `queravel` in any repo. First time in a project, `queravel init` writes a
`QUERAVEL.md` so the agent learns your build/test commands and conventions.

```bash
queravel design "a landing page for my app"   # generate a self-contained HTML page locally + open it (/design in the TUI)
queravel --browser "check if example.com loads"   # browser automation via Playwright MCP (navigate/click/type/screenshot)
queravel research "how does WASM GC work" --breadth 5   # multi-agent deep research → cited report (/research in the TUI)
```

Deep research fans out one web sub-agent per angle in parallel, verifies claims against sources, and
writes a cited Markdown report. **Search backend:** when you're **signed in** (`queravel login`),
search routes through **Queravel's own engine** — 15 free providers + neural rerank + cache, **no key
needed**. Signed out, it falls back to `TAVILY_API_KEY` → `BRAVE_API_KEY` → keyless (Wikipedia + DDG
instant answers). Force the local path with `QUERAVEL_WEB_SEARCH=direct`.

Switch models in the TUI with **`/model`** (no id → interactive picker) or `/model <id>`.

**Voice input** — in the TUI, `/voice` records from your mic and drops the transcript into the prompt
(you review before sending). Install the extra and set a speech-to-text key:
`pip install 'queravel-cli[voice]'` + `GROQ_API_KEY` (fast) or `OPENAI_API_KEY`.

## Auth

Uses the free Queravel Fireworks models. The key is read at runtime from `FIREWORKS_API_KEY`, or
(dev convenience) from the Queravel *personal* backend's `.env`. Nothing is stored in this repo.

```bash
export FIREWORKS_API_KEY=fw_...        # optional if the personal backend .env has it
```

To use another provider's model, set its API key and pass `--model <id>`.

## Use

```bash
queravel                       # interactive TUI
queravel "refactor utils.py to remove the duplicate helper"   # TUI, pre-seeded with a first task
queravel -p "run the tests and summarize failures"            # headless (print) mode, no TUI

# Sessions — resume where you left off
queravel -c "and now add tests for it"     # --continue: resume the latest session in this dir
queravel --resume                          # pick from a list (this dir; Ctrl+A = all dirs, / = search)
queravel --resume 20260917-004541-645844   # resume a specific session id directly
queravel --resume <id> --fork-session      # branch it into a NEW session (original untouched)

# In the picker: →/← expand a group's branches, / to search (or paste a PR URL to
# find the session that opened it). In a session, /branch forks the current thread.

# Options
queravel --model glm-5.3-flash --cwd /path/to/repo "..."   # models: kimi-k3 | glm-5.3-flash | deepseek-v4.1-flash
queravel --auto -p "create hello.py and run it"      # auto-approve side effects (scratch targets)
```

### Approval / permission modes

```bash
queravel                 # default: prompt every side effect (edits show a diff to accept/reject)
queravel --accept-edits  # auto-approve file edits; still confirm shell commands
queravel --plan          # read-only: research & propose a plan, change nothing
queravel --auto          # approve everything except denied/dangerous commands
```

Cycle modes live with **Ctrl+P → "Cycle approval mode"**. Manage **allow / ask / deny** rules
interactively with **`/permissions`** (add/remove, user or project scope), or edit
`~/.queravel/settings.json` / `.queravel/settings.json` directly:
`{"permissions": {"allow": ["Bash(npm test:*)", "Read(src/*)"], "ask": ["Bash(git push*)"], "deny": ["WebFetch(domain:evil.com)"]}}`.
Rule syntax: `Bash(<glob>)`, `Read/Write/Edit(<glob>)`, `WebFetch(domain:x)`,
`mcp__server__tool`, a bare tool name, or `*`. Precedence is **deny > ask > allow**; dangerous
commands (`rm -rf`, fork bombs, `curl|sh`, force-push, …) never auto-run.

### Power features

- **Todos** — the agent plans multi-step work; a live panel tracks progress.
- **Sub-agents** — it delegates large investigations to an isolated **read-only** sub-agent (`task`)
  that returns a findings report, keeping the main context clean.
- **Context auto-compaction** — long sessions summarize older turns automatically to stay in-window.
- **Checkpoint / undo** — every file edit is snapshotted; `/undo` reverts the last change.
- **Hooks** — run shell commands at `PreToolUse` (non-zero exit blocks the tool) / `PostToolUse`
  (e.g. auto-format after edits) via `settings.json`; matched by a regex on the tool name.
- **QUERAVEL.md `@`-imports** — recursively include other files into your project memory.
- **Agentic search, not RAG** — it navigates your repo with grep/glob/read on demand (always fresh,
  no index to build).

## Project memory — `QUERAVEL.md`

Drop a `QUERAVEL.md` in your repo (and/or `~/.queravel/QUERAVEL.md` for global prefs). Its contents
are injected into the agent's system prompt every run, so your project conventions, build/test
commands, and do's/don'ts persist without re-explaining.

Sessions are saved under `~/.queravel/sessions/`; the system prompt (and thus `QUERAVEL.md`) is
rebuilt on every run, so editing `QUERAVEL.md` always takes effect — even on `--continue`.

## Web & MCP

- **Web tools**: the agent can `web_fetch` a URL and `web_search` (set `TAVILY_API_KEY` for a
  reliable search API; otherwise a best-effort keyless search is used).
- **MCP servers**: connect external tool servers (standard MCP config) in
  `~/.queravel/mcp.json` or `.queravel/mcp.json`:
  ```json
  {"mcpServers": {"github": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"]}}}
  ```
  Their tools appear as `mcp__<server>__<tool>` and are gated by your approval mode.

## Tools (Phase 0/1)

`read_file` · `write_file` · `edit_file` (surgical) · `multi_edit` (atomic multi-change) ·
`list_dir` · `glob` · `grep` · `run_command` (bash). All execute **in-process on your machine**,
whole-repo, no cloud caps.

## Architecture (short)

A local, provider-agnostic tool-use loop (`adapters/base.py`) — Fireworks (OpenAI-compatible) by
default, with optional BYOK providers — driving in-process local tools, rendered through a UI abstraction
(`ui.py`) that backs both the Textual TUI (`tui.py`) and the headless `-p` mode. Mirrors the shape
of Queravel's backend agent engine so it can be extracted and shared (Phase 1 next step). See
`memory/` for the concept, decisions, and engine-extraction plan.
