vtx-coding-agent 0.2.3__tar.gz → 0.2.4__tar.gz

{vtx_coding_agent-0.2.3 → vtx_coding_agent-0.2.4}/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to Vtx are documented in this file. The format is based on
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.2.4] - 2026-07-11
+
+### Added
+- **Documentation rewrite** — rewrote the user-facing docs from scratch for accuracy: `docs/tools.md`, `permissions.md`, `configuration.md`, `providers.md`, `sessions.md`, `skills.md`, `extensions.md`, `agents.md`, `goal.md`, `hooks.md`, `ui.md`, `theming.md`, `headless.md`, `storage-layout.md`, `local-models.md`, `architecture.md`, `development.md`, and `docs/README.md`; refreshed the README and SDK README token figures (full runtime ~2,600 tokens, 11 tools).
+- **README revamp** — redesigned the top-level README for clarity and marketing: badges, "Why Vtx?" pitch, two-backend table, feature grid, quick-start, an ASCII demo block, toolset matrix, custom-provider snippet, and a docs index.
+- **README/SDK docs**: corrected provider count to **50+** built-in providers and added a "Permissions & switching agents" section documenting `Shift+Tab` (toggle permission mode and cycle handoff agents) and `/permissions`.
+- **Fix shortcut labels** — `Shift+Tab` now correctly labelled "switch agent" in the TUI welcome and session-info shortcuts (it cycles handoff agents; permission mode is `Alt+Ctrl+P` or `/permissions`). Fixed the README to match.
+- **Editable build indicator** — when vtx is installed as an editable package (`pip install -e .`), the TUI now displays `v-editable` instead of a release version number. Detection uses the installed distribution's `direct_url.json` `dir_info.editable` flag.
+
+### Changed
+- **Minimalist system prompt** — drastically reduced the model context footprint:
+  - Rewrote the system prompt sections to be terse while preserving all behavioral guidance.
+  - Trimmed every tool description and field description.
+  - Slimmed the LLM-facing tool JSON schemas: dropped `title`/`minLength`/`maxLength` noise and collapsed `anyOf: [type, null]` optional unions. Pydantic still enforces all validation constraints on real tool calls.
+  - Removed redundant tool-usage guidelines that duplicated the tool descriptions.
+  - Total system prompt + tool definitions lowered from ~5,500 tokens to ~2,600 tokens (o200k_base).
+
 ## [0.2.3] - 2026-07-10 — Custom Provider Support
 
 ### Added

vtx_coding_agent-0.2.4/PKG-INFO

@@ -0,0 +1,284 @@
+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

vtx_coding_agent-0.2.4/README.md

@@ -0,0 +1,198 @@
+<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

{vtx_coding_agent-0.2.3 → vtx_coding_agent-0.2.4}/docs/README.md

@@ -8,12 +8,15 @@ This folder is the reference companion to the top-level [README](../README.md).
 | --- | --- |
 | [configuration.md](configuration.md) | Every YAML config field with its default, validation rule, and CLI override |
 | [providers.md](providers.md) | Built-in LLM providers, OAuth and API-key auth, dynamic catalog providers, env vars |
-| [tools.md](tools.md) | The 6 core tools + 2 web tools — parameters, mutating flag, and worked examples |
-| [permissions.md](permissions.md) | The `prompt`/`auto` modes, the safe-command allowlist, and the decision algorithm |
-| [sessions.md](sessions.md) | JSONL session format, resume, handoff, `/export`, compaction, and tree navigation |
-| [skills.md](skills.md) | Authoring skills — frontmatter, `$ARGUMENTS`, `register_cmd`, discovery paths |
-| [agents.md](agents.md) | Switchable handoff agents — `.vtx/agent/<name>.py`, `AgentAPI`, `Shift+Tab` cycling |
+| [tools.md](tools.md) | The 11 tools — parameters, mutating flag, and worked examples |
+| [permissions.md](permissions.md) | The `prompt`/`auto` modes, safety guarantees, and the approval decision flow |
+| [sessions.md](sessions.md) | JSONL session format, resume, handoff, `/export`, compaction |
+| [skills.md](skills.md) | Authoring skills — frontmatter, `register_cmd`, discovery paths |
+| [agents.md](agents.md) | Switchable handoff agents — `.vtx/agent/<name>.py`, `Shift+Tab` cycling |
 | [theming.md](theming.md) | The full theme catalog and palette tokens |
+| [ui.md](ui.md) | TUI input, shell execution, slash commands, thinking blocks |
+| [goal.md](goal.md) | Continuous `/goal` work with an evaluator loop |
+| [hooks.md](hooks.md) | The extension-based hook lifecycle (tool_call, tool_result, lifecycle events) |
 | [headless.md](headless.md) | The `-p`/`--prompt` non-interactive flow, exit codes, stdin handling |
 | [local-models.md](local-models.md) | Tested local models, llama-server setup, model-specific config tuning |
 | [storage-layout.md](storage-layout.md) | Every file Vtx touches on disk — config, sessions, models, auth |

vtx_coding_agent-0.2.4/docs/agents.md

@@ -0,0 +1,64 @@
+# Switchable Handoff Agents
+
+Vtx supports named, switchable agent profiles ("handoff agents"). Each profile is a focused system-prompt + tool surface + model configuration you can cycle between in the TUI with `Shift+Tab`. They are ideal for distinct modes like read-only review, security audit, or fast implementation.
+
+## Locations & discovery
+
+Profiles are Python files defining a module-level `AGENT` constant:
+
+- Project: `<cwd>/.vtx/agent/<name>.py` (searched up to the git root; deeper wins)
+- Global: `~/.vtx/agent/<name>.py`
+
+Multiple profiles can be configured explicitly via `agents.files:` in `config.yml` or the `--agent-file` CLI flag. The default active profile is set with `agents.default:`; `agents.switch_mode` is `lock` or `unlock`.
+
+See `examples/agents/` for working profiles (`code-review.py`, `security-audit.py`, `explorer.py`, `data-engineer.py`, `yolo.py`).
+
+## Profile schema
+
+```python
+AGENT = {
+    "name": "security-audit",            # required, [a-z0-9-]
+    "description": "Read-only security review.",  # required
+    "icon": "🛡",                          # optional (max 4 chars)
+    "color": "red",                       # optional theme color
+
+    # Model / provider overrides
+    "model": "gpt-5.5",
+    "provider": "openai-codex",
+    "base_url": None,
+    "thinking_level": "high",
+    "max_turns": 100,
+
+    # System prompt composition
+    "instructions": "You are a security auditor...",
+    "instructions_mode": "append",        # append | replace
+
+    # Tool surface (built-in tool names, or tool-group names like "read-only"/"full")
+    "tools_allow": ["read", "grep", "find"],
+    "tools_deny": [],
+
+    # Permissions
+    "permission_mode": "prompt",          # prompt | auto
+    "permission_gates": [],
+
+    # Handoffs to other profiles
+    "handoffs": ["code-review"],
+    "handoff_back": True,
+
+    # Agent-scoped extensions to load when active
+    "extensions": [],
+}
+```
+
+All fields are optional except `name` and `description`.
+
+## Using profiles
+
+- `Shift+Tab` in the TUI cycles through loaded profiles.
+- `/handoff <query>` summarizes the current session and starts a fresh session under a chosen profile, carrying the summary forward.
+- A profile's `instructions` is appended to (or replaces) the base system prompt per `instructions_mode`.
+- A profile may `handoff` to other named profiles, letting the model route work between specialists.
+
+## `task` sub-agents vs handoff agents
+
+Handoff agents run in the **same** session and context. The `task` tool dispatches **separate** sub-agent sessions (see [tools.md](tools.md)). Use `task` for parallel, isolated work; use handoff agents for in-session persona switching.

vtx_coding_agent-0.2.4/docs/architecture.md

@@ -0,0 +1,47 @@
+# Architecture
+
+Vtx is a minimalist coding-agent harness built around a small, transparent runtime. This page maps the core `src/vtx` package.
+
+## Two backends
+
+`vtx-coding-agent` ships two agentic execution engines:
+
+- **`vtx` native event loop** (`src/vtx/loop.py`, `src/vtx/turn.py`) — the original single-session, event-stream loop. It powers the TUI and the headless CLI (`vtx -p "..."`). Handles thinking streaming, tool permissions, file edits, and compaction between turns.
+- **`vtx_claw` advanced backend** (`src/vtx_claw/...`) — a production-grade multi-session gateway loop with concurrent tool batching, context governance, crash-checkpoint restore, mid-turn message injection, subagent orchestration, MCP servers, cron turns, and a hook lifecycle. Powers the `vtx-claw` gateway, WebUI, and 16+ chat-channel integrations. Requires the `[claw]` extra.
+
+## Core runtime (`src/vtx`)
+
+| Module | Responsibility |
+|--------|----------------|
+| `turn.py` | `run_single_turn` — one agent turn: build messages, call the model, execute tool calls, emit events. |
+| `loop.py` | The interactive turn loop: compaction, goal checks, lifecycle events. |
+| `events.py` | Typed event stream (`TextDeltaEvent`, `ToolStartEvent`, `ToolResultEvent`, `TurnEndEvent`, …). |
+| `core/types.py` | Message and content types (`AssistantMessage`, `ToolCall`, `ToolResult`, `Usage`, …). |
+| `tools/` | The 11 built-in tools as Pydantic-validated `BaseTool` subclasses. |
+| `prompts/` | System-prompt assembly (`identity.py`, `tooling.py`, `env.py`, `builder.py`). |
+| `llm/` | Provider catalog, model fetching, and provider SDK adapters. |
+| `session.py` | JSONL session persistence and resumption. |
+| `extensions.py` | Extension discovery, the `ExtensionAPI`, and the event bus. |
+| `agents/` | Switchable handoff-agent discovery and schema. |
+| `goal.py` | Goal-mode manager and evaluator. |
+| `config.py` | Configuration schema, loading, and migration. |
+| `ui/` | The Textual TUI and `app.py`. |
+| `sdk/` | The programmatic multi-agent SDK (see [sdk/README.md](sdk/README.md)). |
+
+## Message flow (one turn)
+
+1. The loop builds the message list (system prompt + history + user input).
+2. `run_single_turn` calls the model and streams `TextDeltaEvent`s.
+3. On a tool call, the permission gate runs (if `prompt` mode); the tool executes and emits `ToolStartEvent` / `ToolResultEvent`.
+4. The tool result is appended and the turn continues until the model stops or a stop reason is hit.
+5. Between turns, compaction and goal evaluation may run; lifecycle events fire through the extension bus.
+
+## Context management
+
+- The system prompt is intentionally lean (base + tool guidelines + env block). See [README](../README.md) for token figures.
+- `compaction` summarizes old turns when context exceeds `compaction.threshold_percent`.
+- `git_context` optionally attaches a `git status`/`git diff` snapshot at startup.
+
+## Sub-agents
+
+The `task` tool (`src/vtx/tools/task.py`) dispatches isolated sub-agent sessions with their own tool surface. Built-in presets (`general-purpose`, `Explore`, `Plan`) are configured under `task.subagent_presets`. See [tools.md](tools.md).