# 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
```bash
Other supported install paths:
```bash
# 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
```bash
# 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
```bash
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
```bash
qvl run "review the current diff for bugs"
qvl exec --quiet "format the summary as markdown"
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
```bash
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
```bash
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
```text
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](docs/README.md)
- [CLI workflows](docs/guides/cli-workflows.md)
- [TUI guide](docs/guides/tui.md)
- [Providers and auth](docs/guides/providers-and-auth.md)
- [Configuration guide](docs/guides/configuration.md)
- [CLI reference](docs/reference/cli.md)
- [Slash command reference](docs/reference/slash-commands.md)
- [Operations: verification](docs/operations/verification.md)
- [Internals: architecture](docs/internals/architecture.md)
- [Source-to-doc map](docs/_meta/source-map.md)
Compatibility landing pages remain under `docs/*.md` for older links.
## Repository Layout
```text
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
```bash
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](docs/operations/building.md),
[Verification](docs/operations/verification.md), and
[Releasing](docs/operations/releasing.md) for the full workflow.
## Contributing And Support
- [Contributing guide](CONTRIBUTING.md)
- [Support](SUPPORT.md)
- [Security policy](SECURITY.md)
- [Code of conduct](CODE_OF_CONDUCT.md)
License: [GPL-3.0-or-later](LICENSE)