Quavil Agent

Quavil Agent is a terminal-first AI coding agent. The published package name is quavil; the executable is qvl.

Quavil combines:

• an interactive TUI with lanes, slash commands, and guided connect flows
• non-interactive run and exec entry points for scripts and CI
• multi-provider model routing, auth, and model selection
• persistent sessions, replay, export, and handoff workflows
• MCP integration, web tooling, indexing, hooks, teams, and verification tools

Install

curl -fsSL https://get.quavil.com | sh

Other supported install paths:

# Cargo
cargo install quavil

# npm
npm install -g quavil

# from source
git clone https://github.com/Quavil/code
cd code
cargo build --release -p quavil

The npm package installs qvl and pulls a platform package containing the binary for macOS or Linux on x64 and arm64.

Quick Start

# launch the interactive TUI
qvl

# guided provider setup inside the TUI
/connect

# one-shot prompt with text output
qvl run "summarize this repository architecture"

# CI-friendly execution with JSONL events
qvl exec --json "run tests and summarize failures"

# export the latest matching session
qvl export "architecture"

Core Workflows

Interactive

qvl

Use the TUI when you want:

• guided provider/model setup with /connect
• slash-command workflows such as /research, /team, /gate, /harness
• session search, recall, handoff, and export
• model switching, themes, notifications, and diagnostics

One-shot

qvl run "review the current diff for bugs"
qvl exec --quiet "format the summary as markdown"
cat build.log | qvl exec "explain the failure"

Use run for human-readable output and exec for scripting and CI. exec streams progress to stderr, prints the final result to stdout, and supports --json, --ephemeral, --sandbox, and --full_auto.

Project bootstrap and automation

qvl init
qvl import claude
qvl import cursor
qvl import mcp-json --path .mcp.json
qvl deepinit
qvl ci-fix --log-file ci.log

Sessions, teams, and tooling

qvl sessions
qvl session rename abc123 "routing cleanup"
qvl replay abc123 --filter tool
qvl mcp list
qvl teams list
qvl harness run runtime
qvl update --list-backups

Trust And Sandbox Model

Quavil separates approval behavior from execution boundaries.

Trust modes:

• off: ask before sensitive actions
• limited: allow more automation, still guarded
• autoedit: optimized for edit-heavy flows
• full: auto-approve tool calls

Sandbox levels:

• read-only
• workspace-write
• full-access

qvl exec --full_auto sets trust mode to full and sandbox to workspace-write.

Configuration

Primary config files:

• global: ~/.quavil/config.toml
• project: .quavil/config.toml

Quavil merges global and project config with source-backed rules in quavil_config::Config::merge. Important behaviors:

• provider entries merge by provider name
• project config can extend hooks, commands, MCP servers, agent roles, and index excludes
• project config cannot override the global release URL used for self-update
• config.local.toml exists as a loader helper but is not part of the default CLI/TUI merge path

Key sections include:

• [provider] and [provider.<id>]
• [models]
• [tui]
• [agent]
• [mcp]
• [shell]
• [browser]
• [memory]
• [update]
• [index]
• [external_notify]

Architecture

                    qvl (CLI binary)
                           |
            +--------------+---------------+
            |                              |
        quavil-tui                      quavil-core
                                           |
                     +---------------------+---------------------+
                     |                     |                     |
                quavil-provider         quavil-auth           quavil-index
                     |
                quavil-config

Workspace responsibilities:

• crates/cli: CLI parsing, command dispatch, runtime wiring
• crates/tui: TUI event loop, lanes, slash commands, export
• crates/core: agent loop, tools, sessions, teams, hooks, updater, harness
• crates/provider: provider abstraction and transport adapters
• crates/auth: OAuth, API keys, token storage, auth status
• crates/config: schema, defaults, merge rules, built-in providers
• crates/index: codebase indexing and auto-context
• crates/harness-support: harness helpers and snapshot utilities

Documentation

Start with the local docs portal:

• Docs index
• CLI workflows
• TUI guide
• Providers and auth
• Configuration guide
• CLI reference
• Slash command reference
• Operations: verification
• Internals: architecture
• Source-to-doc map

Compatibility landing pages remain under docs/*.md for older links.

Repository Layout

crates/                 Rust workspace crates
docs/                   local product, ops, and internals docs
infra/                  Cloudflare workers and analytics dashboard
npm/                    npm package manifests and platform wrappers
tools/                  repo policy and Bazel parity tooling
.github/workflows/      CI, release, and edge deployment pipelines

Build And Verify

cargo build -p quavil
cargo nextest run --workspace
cargo run -p quavil -- harness run runtime
cargo test -p quavil-tui --test snapshots -- --nocapture

See Building, Verification, and Releasing for the full workflow.

Contributing And Support

• Contributing guide
• Support
• Security policy
• Code of conduct

License: GPL-3.0-or-later