vtx-coding-agent 0.2.4

Minimalist coding agent harness with a Textual TUI and headless CLI. Ships two agentic backends: the native vtx event loop and the advanced vtx-claw gateway loop (install the [claw] extra for multi-channel + subagent + cron features). <1k-token system prompt, 50+ LLM providers, AGENTS.md + skills context, session tree, prompt/auto permissions.

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

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 11 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 gateway backend — pick the surface that fits the job.

---

Two backends, one runtime

Backend	What it's for	Powers
vtx native loop	Single-session, event-stream agent loop with thinking streaming, tool permissions, and compaction.	The TUI + headless CLI (vtx -p "...")
vtx_claw gateway	Production-grade multi-session loop: concurrent tool batching, context governance, crash-restore, subagents, MCP, cron, channel integrations.	The vtx-claw gateway, WebUI, and 16+ chat channels ([claw] extra)

---

Features

• Lean by design — ~2,600-token runtime; no hidden prompt bloat.
• 11 surgical tools — read, edit, write, bash, find, grep, skill, fetch_webpage, web_search, ask_user, task.
• 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.
• 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.
• Programmable SDK — build multi-agent apps on the same runtime with vtx.sdk.

---

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/vtx/utils.py"

Install the advanced gateway backend too:

uv tool install "vtx-coding-agent[claw]"

---

The toolset

Tool	Does	Tool	Does
read	Read/paginate files, view images	fetch_webpage	Fetch a URL as markdown
edit	Precise search-and-replace	web_search	Semantic web search
write	Create/overwrite files	ask_user	Ask a clarifying question
bash	Run commands in the cwd	task	Dispatch a sub-agent
find	Glob file discovery	skill	Manage skill workflows
grep	Regex search over files

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

Topic	Link
Configuration	docs/configuration.md
Providers & custom endpoints	docs/providers.md
Tools	docs/tools.md
Permissions	docs/permissions.md
Sessions	docs/sessions.md
Skills	docs/skills.md
Extensions	docs/extensions.md
Handoff agents	docs/agents.md
Goals	docs/goal.md
Architecture	docs/architecture.md
Local models	docs/local-models.md
SDK	docs/sdk/README.md
vtx-claw gateway	docs/claw/README.md

---

License

Apache License 2.0