vtx-coding-agent 1.0.0

██╗   ██╗████████╗██╗  ██╗
██║   ██║╚══██╔══╝╚██╗██╔╝
██║   ██║   ██║    ╚███╔╝
╚██╗ ██╔╝   ██║    ██╔██╗
 ╚████╔╝    ██║   ██╔╝ ██╗
  ╚═══╝     ╚═╝   ╚═╝  ╚═╝

The minimalist, modular coding agent harness

Maximum capability. Minimum overhead.

A coding agent that keeps its system prompt lean — around ~2,600 tokens for the whole runtime — so your context window stays free for what matters: your code.

Why Vtx?

Most coding agents bury you in thousands of hidden prompt tokens before you type a single line. Vtx is transparent about its footprint. The full runtime — base system prompt, tool guidelines, environment block, and all tool definitions — fits in roughly 2,600 tokens (o200k_base). That means:

• More of the model's context is spent on your files, not boilerplate instructions.
• Faster, cheaper turns with any provider you choose.
• A prompt you can actually read, audit, and shrink.

Vtx is also modular: a keyboard-driven TUI, a headless CLI, a Python SDK, and an optional extension manager — pick the surface that fits the job.

Features

• Lean by design — ~2,600-token runtime; no hidden prompt bloat.
• 9 surgical default tools — read, edit, write, bash, find, skill, web, ask_user, task. (grep is a built-in but not enabled by default.)
• TUI & CLI — a Textual-powered terminal UI, plus a non-interactive headless mode for scripts and CI.
• Any model, any endpoint — 50+ built-in providers (OpenAI, Anthropic, Azure, DeepSeek, Copilot, Zhipu, Groq, Mistral, Together, Ollama, …) plus OpenAI/Anthropic-compatible custom providers and local models (Ollama, llama.cpp, vLLM).
• Dynamic context — auto-loads AGENTS.md/CLAUDE.md guidelines and triggers modular Skills.
• Switchable handoff agents — named profiles (review, security audit, fast impl) cycled live with Shift+Tab, or activated with /agent <name>.
• Task sub-agents — delegate self-contained work to isolated sessions that stream progress back.
• Safe by default — prompt permission mode gates mutating tools; destructive commands are blocked.
• Self-extensible — drop a Python file to add tools, intercept calls, register slash commands, or hook lifecycle events.
• YAML hooks — declarative .vtx/hooks.yml for shell and HTTP lifecycle automation.
• Extension manager — install extensions and agent packages from PyPI or GitHub with vtx install <name>.

Quick start

# Install with uv (recommended)
uv tool install vtx-coding-agent

# Or the one-liner installer
curl -fsSL https://raw.githubusercontent.com/OEvortex/vtx-coding-agent/main/scripts/install.sh | bash

Launch the terminal UI:

vtx

Run a single task headlessly:

vtx -p "Write unit tests for src/ai/agent/tools/task.py"

The toolset

See docs/tools.md for full parameter specs.

Permissions & switching agents

Toggle permission mode on the fly. Vtx gates mutating tools (bash, edit, write) behind a permission system. In the TUI:

• Press Alt+Ctrl+P to cycle between prompt (asks before mutating) and auto (unrestricted) mode.
• Type /permissions to open the permission menu and switch mode explicitly.
• Set the default in config.yml (permissions.mode: prompt | auto).

Destructive commands (rm -rf, git reset --hard, force-push, dropping tables) are blocked unless you explicitly ask. See docs/permissions.md.

Switch handoff agents with Shift+Tab. Define named profiles in .vtx/agent/<name>.py (e.g. security-audit, code-review, explorer) and cycle between them live — each bundles its own instructions, tool allow/deny list, and optional model override. See docs/agents.md.

Bring your own provider

Point Vtx at any OpenAI- or Anthropic-compatible endpoint — no source edits required:

# .vtx/providers/acme.yaml
slug: acme
display_name: "Acme AI Gateway"
family: openai_compat
base_url: "https://ai.acme.internal/v1"
api_key_env: ACME_API_KEY
fetch_models: true

export ACME_API_KEY=sk-...
vtx --provider acme -m acme-large

Custom providers show up in the /model picker and auto-fetch their model catalog. Full reference in docs/providers.md.

Build agents programmatically

from vtx.ai.agent.sdk import Agent, Runner, tool

@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"Sunny in {city}"

agent = Agent(
    name="Weather bot",
    instructions="Be concise.",
    model="gpt-4o-mini",
    tools=[get_weather],
)

result = Runner.run_sync(agent, "Weather in Tokyo?")
print(result.final_output)

See the SDK docs.

Documentation

License

Apache License 2.0