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

{vtx_coding_agent-0.2.3 → vtx_coding_agent-0.2.5}/AGENTS.md

@@ -26,21 +26,13 @@
 - If the user asks you to push code, run these first before doing so: `uv run ruff format .`, `uv run ruff check .`, `uvx ty check  .` and `uv run python -m pytest` in parallel (same tool call)
 - Only if these all pass without issues should you push otherwise report the warnings/errors back to user and ask for next steps
 
-## CodeBase Search
+## Codebase Search
 
-Search the codebase using semantic + BM25 hybrid retrieval. PREFER this over grep/rg/Glob for finding code.
+Use vortexa (not grep/rg/file reads) to search code or understand a repo. It
+indexes the current directory (or pass --root <dir>).
 
-Use this tool when you need to:
-- Find where a function, class, or pattern is implemented
-- Understand how a feature or concept works across the codebase
-- Locate code by describing what it does (not just exact strings)
-- Find examples of a pattern or API usage
-- Explore unfamiliar parts of the codebase
-- Identify relevant code for a task without knowing exact names or locations
-- Preferable than grep/rg/Glob for code search because it can understand the meaning and intent behind the query, rather than just matching exact strings. This allows for more flexible and powerful searching, especially in large and complex codebases.
-Advantages over text search: understands synonyms, paraphrases, and intent.
-Returns file paths, line ranges, relevance scores, and matching code.
+  vortexa resolve "<query>" --plain          # default: matches + tests + callers/callees + deps
+  vortexa search "<query>" --hybrid --plain  # ranked hits + per-file graph context
+  vortexa explain "<file>:<line>|<symbol>"   # deep dive into a known location
 
-- For codebase Search use `vortexa -q "you natural query here"` to get relevant code snippets from the codebase. This will help you understand the existing code and avoid duplicating functionality.
-
-- Instead of using grep use rg (ripgrep) for faster and more efficient searching. For example, `rg "def my_function"` to find all occurrences of a function definition.
+Install: pip install vortexa  (add [full] for tree-sitter AST chunking).

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

@@ -5,6 +5,33 @@ 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.5] - 2026-07-12
+
+### Added
+- **Meta AI provider** — registered Meta AI as a new OpenAI-compatible provider (slug `meta`) with base URL `https://api.meta.ai/v1`, resolving `META_API_KEY` from the environment, and fetching its Llama model catalog from `/models`.
+- **AGENTS.md codebase search** — replaced the CodeBase Search section with `vortexa` CLI usage (`resolve` / `search --hybrid` / `explain`) so the agent prefers a semantic index over grep/rg for code search.
+
+### Fixed
+- **Typing** — widened `_slim_schema()` parameter and return types from `object` to `Any` in `src/vtx/tools/__init__.py` to satisfy `ty`.
+- **System-prompt migration tests** — updated stale assertions from "You are Vtx, an expert coding assistant." to "You are Vtx, an expert coding agent." in `tests/test_config_migration.py`.
+
+## [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
@@ -851,6 +878,8 @@ to keep the model's context window free for what matters.
   via `uv tool install vtx-coding-agent`.
 - Licensed under **Apache License 2.0**.
 
+[0.2.5]: https://github.com/OEvortex/vtx-coding-agent/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/OEvortex/vtx-coding-agent/compare/v0.2.3...v0.2.4
 [0.2.2]: https://github.com/OEvortex/vtx-coding-agent/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/OEvortex/vtx-coding-agent/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/OEvortex/vtx-coding-agent/compare/v0.1.9...v0.2.0

vtx_coding_agent-0.2.5/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: vtx-coding-agent
+Version: 0.2.5
+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">
+
+<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 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.5/README.md

@@ -0,0 +1,203 @@
+<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 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.5}/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.5/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.