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

# 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.

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.

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

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

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:

  {"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.