Vtx

A coding agent that lives in your terminal.

Vtx is a coding agent harness. Give it a goal and a working folder, and it reads files, runs commands, edits code, and works through multi-step tasks without stopping to confirm each one. The same core runs three ways: a keyboard-driven TUI, a headless CLI for scripts and CI, and a Python SDK for embedding.

It ships 11 packages under the single vtx-coding-agent distribution, with 62 providers, 14 tools, and an agent runtime whose every subsystem is replaceable without editing the harness.

Quick start

uv tool install vtx-coding-agent

vtx                              # terminal UI
vtx -p "add tests for vtx.git"   # headless, one task, then exit

Python 3.12 or newer. The console script is vtx.

Connect a model with --provider and --model, or export a key and start:

export ANTHROPIC_API_KEY=sk-ant-...
vtx --provider anthropic --model claude-sonnet-4-5

Resume a session with vtx -c, or a specific one with vtx -r <id>.

What makes it different

Everything is a row. vtx boots a plugin composition: a profile's ordered bundles, then its own patch layer, then --patch overlays, last write per row id. The tool registry, the provider seam, the session log, the permission gate, and the agent loop are all rows, so each is replaceable from configuration rather than by forking the harness.

vtx --dump-config                          # the composed row list
vtx plugin --profile default disable tool-grep
vtx --profile minimal                      # a four-row composition, for embedding

A plugin declares what it needs with inject and registers through a context that records teardown, so unmounting a row unwinds exactly what it registered.

It extends itself. Vtx ships a skill that teaches the model which surface to reach for when it lacks a capability - a directory of instructions, a plugin row that registers a real tool, or an extension file - and mounts it in place. It will not upgrade the Vtx package itself; that stays a user action.

The sandbox is honest about what it is. A codemode script runs in a separate worker process as you, with the full standard library, the filesystem, subprocesses, and the network. There is no interpreter-level confinement and none is attempted. What a script cannot reach is the host's own state, because that lives in another process - so a deadline is a kill, not a cooperative request.

62 providers, 16 API families. The catalog ships 62 providers across 16 API families; --provider takes a family name, and dropping a YAML file into ~/.vtx/providers/ adds your own.

Sessions are durable and branchable. Resume the last one, fork a new one mid-task to explore a different approach, and revert a turn with snapshots.

Documentation

Full reference, generated from the source:

Using it

Extending it

Building on it

Packages

Dependencies flow protocol and telemetry into core, git, and ai; those into agent; agent into coding_agent, with mcp, tui, and plugins above. Each package carries its own README with the public surface and internal notes.

Twelve tools are on by default - read, edit, write, bash, find, skill, web, ask_user, tool_search, codemode, goal, delegate_subagent - resolved by the composition, not by a constant. grep and web_search are registered but off. The sub-agent tool is defined internally as task and exposed as delegate_subagent. Agent profiles load only from .vtx/agent/<name>.py; none ship built in. Configuration lives in ~/.vtx/config.yml.

Contributing

AGENTS.md holds the project rules for humans and agents alike. In short:

uv run ruff format .
uv run ruff check .
uvx ty check .
uv run python -m pytest path/to/test_file.py    # one file, not the full suite

Run a single file's tests rather than the full suite; it is slow and resource intensive. See docs/development.md.

License

Apache License 2.0