Metadata-Version: 2.4
Name: vtx-coding-agent
Version: 0.2.4
Summary: 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.
License-File: LICENSE
Keywords: agent-loop,cli,coding-agent,llm,tui,vtx-claw
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: claw
Requires-Dist: boto3>=1.43.0; extra == 'claw'
Requires-Dist: croniter<7.0.0,>=6.0.0; extra == 'claw'
Requires-Dist: ddgs<10.0.0,>=9.5.5; extra == 'claw'
Requires-Dist: dingtalk-stream<1.0.0,>=0.24.0; extra == 'claw'
Requires-Dist: lark-oapi<2.0.0,>=1.5.0; extra == 'claw'
Requires-Dist: mcp>=1.28.1; extra == 'claw'
Requires-Dist: msgpack<2.0.0,>=1.1.0; extra == 'claw'
Requires-Dist: python-socketio<6.0.0,>=5.16.0; extra == 'claw'
Requires-Dist: python-socks[asyncio]<3.0.0,>=2.8.0; (sys_platform != 'win32') and extra == 'claw'
Requires-Dist: python-telegram-bot[socks,webhooks]<23.0,>=22.6; extra == 'claw'
Requires-Dist: qq-botpy<2.0.0,>=1.2.0; extra == 'claw'
Requires-Dist: slack-sdk<4.0.0,>=3.39.0; extra == 'claw'
Requires-Dist: slackify-markdown<1.0.0,>=0.2.0; extra == 'claw'
Requires-Dist: socksio<2.0.0,>=1.0.0; extra == 'claw'
Requires-Dist: websocket-client<2.0.0,>=1.9.0; extra == 'claw'
Requires-Dist: websockets<17.0,>=16.0; extra == 'claw'
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">

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

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

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

Install the advanced gateway backend too:

```bash
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](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.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 |
| --- | --- |
| Configuration | [docs/configuration.md](docs/configuration.md) |
| Providers & custom endpoints | [docs/providers.md](docs/providers.md) |
| Tools | [docs/tools.md](docs/tools.md) |
| Permissions | [docs/permissions.md](docs/permissions.md) |
| Sessions | [docs/sessions.md](docs/sessions.md) |
| Skills | [docs/skills.md](docs/skills.md) |
| Extensions | [docs/extensions.md](docs/extensions.md) |
| Handoff agents | [docs/agents.md](docs/agents.md) |
| Goals | [docs/goal.md](docs/goal.md) |
| Architecture | [docs/architecture.md](docs/architecture.md) |
| Local models | [docs/local-models.md](docs/local-models.md) |
| SDK | [docs/sdk/README.md](docs/sdk/README.md) |
| vtx-claw gateway | [docs/claw/README.md](docs/claw/README.md) |

---

## License

Apache License 2.0
