Metadata-Version: 2.5
Name: vtx-coding-agent
Version: 1.1.0
Summary: Minimalist coding agent harness with a Textual TUI and headless CLI. Native vtx event loop. <1k-token system prompt, 50+ LLM providers, AGENTS.md + skills context, session tree, prompt/auto permissions.
License-File: LICENSE
Keywords: agent-loop,cli,coding-agent,llm,tui
Requires-Python: >=3.12
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: aiohttp>=3.13.3
Requires-Dist: anthropic>=0.79.0
Requires-Dist: chardet<6.0.0,>=3.0.2
Requires-Dist: curl-cffi>=0.15.0
Requires-Dist: dulwich<1.0.0,>=0.22.0
Requires-Dist: filelock>=3.25.2
Requires-Dist: hammett>=0.10.0
Requires-Dist: html-to-markdown<3.4.0,>=3.3.0
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: jinja2<4.0.0,>=3.1.0
Requires-Dist: json-repair<1.0.0,>=0.57.0
Requires-Dist: loguru<1.0.0,>=0.7.3
Requires-Dist: lxml-html-clean>=0.4.3
Requires-Dist: oauth-cli-kit<1.0.0,>=0.1.3
Requires-Dist: openai>=2.21.0
Requires-Dist: openpyxl<4.0.0,>=3.1.0
Requires-Dist: pillow>=12.1.1
Requires-Dist: prompt-toolkit<4.0.0,>=3.0.50
Requires-Dist: pydantic-settings<3.0.0,>=2.12.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pypdf<6.0.0,>=5.0.0
Requires-Dist: pytest-xdist>=3.8.0
Requires-Dist: python-docx<2.0.0,>=1.1.0
Requires-Dist: python-pptx<2.0.0,>=1.0.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: questionary<3.0.0,>=2.0.0
Requires-Dist: readability-lxml>=0.8.4
Requires-Dist: rich>=14.3.2
Requires-Dist: textual>=8.0.0
Requires-Dist: tiktoken<1.0.0,>=0.12.0
Requires-Dist: typer<1.0.0,>=0.20.0
Provides-Extra: api
Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'api'
Provides-Extra: azure
Requires-Dist: azure-identity<2.0.0,>=1.19.0; extra == 'azure'
Provides-Extra: discord
Requires-Dist: discord-py<3.0.0,>=2.5.2; extra == 'discord'
Provides-Extra: langsmith
Requires-Dist: langsmith>=0.1.0; extra == 'langsmith'
Provides-Extra: matrix
Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'matrix'
Requires-Dist: matrix-nio[e2e]>=0.25.2; (sys_platform != 'win32') and extra == 'matrix'
Requires-Dist: mistune<4.0.0,>=3.0.0; extra == 'matrix'
Requires-Dist: nh3<1.0.0,>=0.2.17; extra == 'matrix'
Provides-Extra: msteams
Requires-Dist: cryptography>=41.0; extra == 'msteams'
Requires-Dist: pyjwt<3.0,>=2.0; extra == 'msteams'
Provides-Extra: olostep
Requires-Dist: olostep>=0.1.0; extra == 'olostep'
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.25.0; extra == 'pdf'
Provides-Extra: wecom
Requires-Dist: wecom-aibot-sdk-python>=0.1.5; extra == 'wecom'
Provides-Extra: weixin
Requires-Dist: pycryptodome>=3.20.0; extra == 'weixin'
Requires-Dist: qrcode[pil]>=8.0; extra == 'weixin'
Provides-Extra: whatsapp
Requires-Dist: neonize<0.4.0,>=0.3.18.post0; extra == 'whatsapp'
Requires-Dist: segno<2.0.0,>=1.6.1; extra == 'whatsapp'
Description-Content-Type: text/markdown

<div align="center">

<table align="center">
<tr><td align="center">

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

</td></tr>
</table>

</div>

<p align="center"><b>The minimalist, modular coding agent harness</b></p>
<p align="center"><b>Maximum capability. Minimum overhead.</b></p>

<p align="center">
  <a href="https://github.com/OEvortex/vtx-coding-agent"><img alt="GitHub" src="https://img.shields.io/github/stars/OEvortex/vtx-coding-agent?style=for-the-badge&label=Stars" /></a>
  <a href="https://pypi.org/project/vtx-coding-agent/"><img alt="PyPI" src="https://img.shields.io/pypi/v/vtx-coding-agent?style=for-the-badge" /></a>
  <a href="https://pypi.org/project/vtx-coding-agent/"><img alt="Downloads" src="https://img.shields.io/pypi/dm/vtx-coding-agent?style=for-the-badge" /></a>
  <a href="https://www.python.org/downloads/release/python-3120/"><img alt="Python" src="https://img.shields.io/badge/python-3.12%2B-blue?style=for-the-badge" /></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache%202.0-blue?style=for-the-badge" /></a>
</p>

<p align="center">
  A coding agent that keeps its system prompt lean — around <b>~2,600 tokens</b> for the whole runtime —
  so your context window stays free for what matters: <i>your code</i>.
</p>

---

## 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.
- **10 surgical default tools** — `read`, `edit`, `write`, `bash`, `find`, `skill`, `web`, `ask_user`, `task`, `goal`. (`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.
- **Persistent goals** — give the agent a durable, file-backed objective with a task tree, live status widget, auto-continue checkpoints, and an independent completion audit. See [docs/goals.md](docs/goals.md).
- **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

```bash
# 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:

```bash
vtx
```

Run a single task headlessly:

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

---

## The toolset

| Tool | Does | Tool | Does |
| --- | --- | --- | --- |
| `read` | Read/paginate files, view images | `web` | Web search (Exa neural) |
| `edit` | Precise search-and-replace | `ask_user` | Ask a clarifying question |
| `write` | Create/overwrite files | `task` | Dispatch a sub-agent |
| `find` | Glob file discovery | `skill` | Manage skill workflows |
| `bash` | Run shell commands | `goal` | Persistent goals: plan, track, complete w/ audit |

See [docs/tools.md](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](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](docs/agents.md).

---

## Bring your own provider

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

```yaml
# .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
```

```bash
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](docs/providers.md).

---

## Build agents programmatically

```python
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](docs/sdk/README.md).

---

## Documentation

| Topic | Link |
| --- | --- |
| Documentation index | [docs/index.md](docs/index.md) |
| Monorepo structure | [docs/developer/monorepo.md](docs/developer/monorepo.md) |

---

## License

Apache License 2.0
