tsugite-cli 0.3.3__tar.gz → 0.8.2__tar.gz

{tsugite_cli-0.3.3 → tsugite_cli-0.8.2}/.github/copilot-instructions.md

@@ -7,19 +7,18 @@ Tsugite is a micro-agent CLI: agents are Markdown + YAML frontmatter, rendered v
 **Flow:** `Agent.md` (YAML + Jinja2) → `renderer.py` → `TsugiteAgent` → LiteLLM → Tools
 
 **Key Modules:**
-- `cli/__init__.py` - Typer CLI (run, chat, render, config, mcp, tools, agents, attachments, cache, benchmark)
+- `cli/__init__.py` - Typer CLI (run, chat, render, config, mcp, tools, agents, attachments, cache)
 - `md_agents.py` - Parse frontmatter + agent resolution + directives
 - `builtin_agents/` - File-based built-in agent definitions (default.md, chat-assistant.md)
 - `agent_inheritance.py` - Agent resolution pipeline + inheritance chain
 - `chat.py` - Chat session management with history
-- `ui/textual_chat.py` - Textual TUI for interactive chat
 - `agent_runner.py` - Execution orchestration, prefetch, tool wiring, multi-step
 - `core/agent.py` - LiteLLM agent loop + streaming
 - `renderer.py` - Jinja2 rendering + helpers (now, today, slugify, env, file_exists, read_text, is_file, is_dir)
 - `tools/` - Tool registry + implementations
 - `shell_tool_config.py` + `tools/shell_tools.py` - Custom shell command wrappers
 - `models.py` - Model string parsing + provider dispatch
-- `config.py` - Configuration (default_model, model_aliases, default_base_agent, chat_theme)
+- `config.py` - Configuration (default_model, model_aliases, default_base_agent)
 
 **Development:**
 ```bash
@@ -42,8 +41,9 @@ uv run black . && uv run ruff check .
 File-based agents distributed with the package in `tsugite/builtin_agents/` directory.
 
 **Current Built-ins:**
-1. `default.md` - Base agent with task tracking, spawn_agent, and file tools
-2. `chat-assistant.md` - Chat agent with tools (read_file, write_file, list_files, web_search, fetch_text, run), text_mode enabled
+1. `default.md` - General-purpose agent with task tracking, spawn_agent, file tools, web search, memory, and shell execution
+2. `file_searcher.md` - Specialized agent for finding files and searching content
+3. `code_searcher.md` - AST-based structural code search using ast-grep
 
 **Location:** `tsugite/builtin_agents/{name}.md`
 
@@ -71,20 +71,17 @@ File-based agents distributed with the package in `tsugite/builtin_agents/` dire
 
 **Components:**
 - `chat.py:ChatManager` - Session management, history (max_history), turn execution
-- `ui/textual_chat.py:ChatApp` - Textual TUI
-- `ui/widgets/` - MessageList, ThoughtLog
+- `ui/repl_chat.py` - REPL chat interface
 
-**Default Agent:** `chat-assistant`. Override with `.tsugite/chat-assistant.md`.
+**Default Agent:** `default`. Override with `.tsugite/default.md`.
 
 **Flow:**
 1. User input → `ChatManager.run_turn()`
 2. Inject `chat_history` context (list of ChatTurn objects)
-3. Call `agent_runner.run_agent()` with `force_text_mode=True`
+3. Call `agent_runner.run_agent()`
 4. Store result in ChatTurn (timestamp, messages, token_count, cost)
 5. Prune history if `> max_history`
 
-**Text Mode:** `text_mode: true` allows LLM responses without code blocks.
-
 ### Directives
 
 **Types:**
@@ -155,7 +152,6 @@ Chat:
 ---
 name: my_chat
 model: openai:gpt-4o
-text_mode: true
 tools: [read_file, web_search]
 ---
 {% if chat_history %}

{tsugite_cli-0.3.3 → tsugite_cli-0.8.2}/.gitignore

@@ -166,4 +166,14 @@ cython_debug/
 .env
 benchmark_results/
 test_output/
-.claude/settings.local.json
+.claude/settings.local.json
+
+
+# TODO: temp - I need to clean up the docs
+docs/
+examples/
+agents/
+.claude/
+.tsugite/
+benchmarks/
+#### TODO ^^^

tsugite_cli-0.8.2/AGENTS.md

@@ -0,0 +1,354 @@
+# AGENTS.md
+
+This file provides guidance to AI agents (tsugite, Claude Code, etc.) when working with code in this repository.
+
+## Commands
+
+### Development Setup
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run all tests
+uv run pytest
+
+# Run specific test
+uv run pytest tests/test_file.py::test_function
+
+# Run tests with coverage
+uv run pytest --cov=tsugite --cov-report=html
+
+# Lint and format
+uv run black .
+uv run ruff check .
+uv run pylint tsugite
+```
+
+### Testing Agents
+```bash
+# Run a basic agent (both `tsugite` and `tsu` aliases work)
+uv run tsugite run examples/simple_variable_injection.md "test task"
+
+# Run with specific model
+uv run tsu run +agent "task" --model openai:gpt-4o-mini
+
+# Preview agent rendering (see what LLM receives)
+uv run tsu render agent.md "task"
+
+# Validate agent schema
+uv run tsu validate agents/*.md
+```
+
+### Schema Management
+```bash
+# Regenerate JSON schema after modifying AgentConfig
+uv run python scripts/regenerate_schema.py
+```
+
+## Architecture
+
+Tsugite is an agentic CLI that executes AI agents defined as markdown files with YAML frontmatter. The architecture follows a pipeline pattern: parse → prepare → render → execute.
+
+### Core Execution Flow
+
+1. **CLI Entry** (`tsugite/cli/__init__.py`)
+   - Typer-based CLI with subcommands
+   - Main commands: `run` (single-shot), `chat` (interactive), `render` (preview)
+   - Additional: `daemon`, `workspace`, `init`, `validate`, `mcp`, `serve`, `agents`, `config`, `attachments`, `cache`, `tools`, `history`
+
+2. **Agent Resolution & Inheritance** (`tsugite/agent_inheritance.py`)
+   - Resolves agent names to file paths using search order:
+     - Workspace agents directory (if workspace provided)
+     - `.tsugite/{name}.md` (project-local)
+     - `agents/{name}.md` (project convention)
+     - `./{name}.md` (current directory)
+     - `builtin_agents/{name}.md` (package-provided)
+     - Global directories (`~/.config/tsugite/agents/`)
+   - Merges agent inheritance chains (scalars override, lists merge, dicts deep merge)
+
+3. **Agent Parsing** (`tsugite/md_agents.py`)
+   - Parses YAML frontmatter → `AgentConfig` (Pydantic model)
+   - Extracts markdown content
+   - Parses directives:
+     - `<!-- tsu:step -->` - Multi-step workflow stages
+     - `<!-- tsu:ignore -->` - Documentation blocks (stripped before LLM)
+     - `<!-- tsu:tool -->` - Execute tools during rendering
+
+4. **Agent Preparation** (`tsugite/agent_preparation.py`)
+   - **Unified preparation pipeline** (used by both `run` and `render` commands)
+   - Executes prefetch tools (frontmatter `prefetch` field)
+   - Executes tool directives (inline `<!-- tsu:tool -->`)
+   - Builds template context (tasks, variables, helpers)
+   - Renders Jinja2 templates
+   - Expands tool globs and categories
+   - Loads auto_load_skills
+   - Builds system prompt with tools and instructions
+
+5. **Template Rendering** (`tsugite/renderer.py`)
+   - Jinja2 environment with custom helpers:
+     - `{{ user_prompt }}`, `{{ tasks }}`, `{{ task_summary }}`
+     - `{{ now() }}`, `{{ today() }}`, `{{ yesterday() }}`, `{{ tomorrow() }}`
+     - `{{ slugify(text) }}`, `{{ cwd() }}`
+     - `{{ file_exists(path) }}`, `{{ is_file(path) }}`, `{{ is_dir(path) }}`, `{{ read_text(path) }}`
+   - Context also includes: `env` (os.environ), `datetime`, `timedelta`
+   - Supports step-scoped variables for multi-step agents
+   - Strips ignored sections before LLM execution
+
+6. **Agent Execution** (`tsugite/agent_runner/runner.py`)
+   - Orchestrates multi-step or single-step execution
+   - Manages step metrics (duration, success/failure)
+   - Handles looping steps (repeat_while/repeat_until)
+   - Supports continue_on_error and per-step timeouts
+   - Integrates with history system for conversation continuity
+
+7. **LLM Agent Loop** (`tsugite/core/agent.py`)
+   - `TsugiteAgent` - Custom agent using LiteLLM directly
+   - Think-Code-Observation loop (max_turns iterations)
+   - Supports reasoning models (o1, o3, Claude extended thinking)
+   - Direct control over model parameters (temperature, reasoning_effort)
+   - Code execution via `LocalExecutor`
+
+8. **Tool System** (`tsugite/tools/`)
+   - Tool registry with built-in tools (fs, http, shell, tasks, agents, memory, skills, history, interactive)
+   - Category system: `@fs`, `@http`, `@shell`, `@tasks`, `@agents`, `@memory`, `@skills`, `@history`, `@interactive`
+   - Custom shell tools (config-based command wrappers)
+   - MCP integration (`tsugite/mcp_client.py`)
+   - Tool expansion supports globs (`*_search`) and exclusions (`-delete_file`)
+
+9. **Event System** (`tsugite/events/`)
+   - Event-driven architecture for UI decoupling
+   - 20 event types: execution, LLM, meta, progress, skills
+   - `EventBus` dispatches to multiple handlers
+   - Handlers: Rich console, plain text, JSONL, chat, REPL
+
+10. **History System** (`tsugite/history/`)
+    - JSONL-based conversation history (one `.jsonl` file per conversation)
+    - Stores turns (user prompts, assistant responses)
+    - Supports continuation (`--continue` flag, optional `--conversation-id`)
+    - Indexed by conversation_id, agent_name, machine_name
+
+11. **Configuration** (`tsugite/config.py`)
+    - XDG-compliant paths: `~/.config/tsugite/` or `$XDG_CONFIG_HOME/tsugite/`
+    - JSON config with model aliases, default settings
+    - Attachment storage (reusable context)
+    - MCP server registration
+    - Auto-context discovery (CLAUDE.md, AGENTS.md, CONTEXT.md)
+
+### Key Data Structures
+
+**AgentConfig** (`md_agents.py:43`)
+- Pydantic model for agent frontmatter
+- Validates all fields (name, model, tools, max_turns, etc.)
+- Schema exported to `tsugite/schemas/agent.schema.json`
+
+**PreparedAgent** (`agent_preparation.py:17`)
+- Dataclass containing everything for execution/display
+- Ensures `render` shows exactly what `run` executes
+- Contains: agent, config, system_message, user_message, tools, context
+
+**Tool** (`core/tools.py`)
+- Unified tool interface for LLM function calling
+- Supports async/sync execution
+- Parameters with JSON schema validation
+
+**Agent** (`md_agents.py`)
+- Parsed agent with content and step directives
+- Steps contain: name, assign variable, temperature, timeout, continue_on_error, repeat conditions
+
+### Multi-Step Agents
+
+Multi-step agents use `<!-- tsu:step -->` directives to create workflows:
+
+```markdown
+<!-- tsu:step name="research" assign="findings" timeout="60" -->
+Research topic
+
+<!-- tsu:step name="summarize" assign="summary" repeat_while="has_pending_tasks" -->
+Summarize findings
+```
+
+**Step Execution:**
+- Preamble (content before first step) rendered once, shared across steps
+- Each step has isolated execution context
+- Variables persist across steps (findings → summary)
+- Supports timeouts, continue_on_error, repeat conditions
+- Metrics tracked per step (duration, status, errors)
+
+**Looping Steps:**
+- `repeat_while` / `repeat_until` with Jinja2 conditions
+- Helper conditions: `has_pending_tasks`, `all_tasks_complete`, etc.
+- Safety: `max_iterations` (default 10) prevents infinite loops
+- Loop context: `{{ iteration }}`, `{{ max_iterations }}`, `{{ is_looping_step }}`
+
+### Event-Driven UI
+
+All UI output goes through the event system:
+
+**Event Types** (events/base.py:9):
+- Execution: TASK_START, STEP_START, CODE_EXECUTION, OBSERVATION, FINAL_ANSWER, ERROR
+- LLM: LLM_MESSAGE, REASONING_CONTENT, REASONING_TOKENS
+- Meta: COST_SUMMARY, STREAM_CHUNK, STREAM_COMPLETE, INFO, WARNING, DEBUG_MESSAGE
+- Skills: SKILL_LOADED, SKILL_UNLOADED, SKILL_LOAD_FAILED
+- Progress: STEP_PROGRESS, FILE_READ
+
+**Handlers** (ui/):
+- `base.py` - UIHandler interface
+- `plain.py` - Plain text (no colors, copy-paste friendly)
+- `jsonl.py` - JSONL protocol (for subprocess subagents)
+- `chat.py`, `repl_handler.py` - Interactive chat/REPL modes
+
+### Agent Spawning (Multi-Agent)
+
+Agents can spawn other agents using the `spawn_agent` tool:
+
+```bash
+# Multi-agent mode: primary +helper1 +helper2
+tsugite run +coordinator +researcher +writer "task"
+```
+
+**Visibility control:**
+- `visibility: public` (default) - Can be spawned by any agent
+- `visibility: private` - Requires explicit allow list (multi-agent mode)
+- `visibility: internal` - Helper agents, not meant to be public
+- `spawnable: false` - Hard block, cannot be spawned (safety)
+
+**Subagent context:**
+- `{{ is_subagent }}` - Boolean
+- `{{ parent_agent }}` - Parent agent name
+
+### Prompt Caching
+
+Automatic caching for supported providers (OpenAI, Anthropic, Bedrock, Deepseek):
+
+- Attachments sent as separate system content blocks with `cache_control` markers
+- Skills also receive cache markers for reuse across turns
+- Cache markers added automatically by `tsugite/core/agent.py`
+
+### Context Management (Daemon Mode)
+
+When using Claude Code as the LLM provider for daemon mode, disable Claude Code's built-in auto-compaction so that tsugite's compaction logic (80% threshold) can manage context properly. If Claude Code compacts first, tsugite's compaction never triggers and session summaries are lost.
+
+### Multi-Modal Attachments
+
+Tsugite supports vision (images), audio, and document understanding through the attachment system.
+
+**Supported Content Types:**
+- **Images**: JPEG, PNG, GIF, WebP, SVG, BMP, TIFF
+- **Audio**: MP3, WAV, OGG, M4A, FLAC (base64 encoded)
+- **Documents**: PDF, Word (DOCX/DOC), Excel (XLSX/XLS), PowerPoint (PPTX/PPT)
+- **Text**: Plain text, HTML (converted to markdown), JSON, XML, etc.
+
+**How It Works:**
+
+1. **URL Attachments** (Images/Documents):
+   - LiteLLM fetches the URL directly (no download overhead)
+   - Example: `tsu run -f https://example.com/chart.png "Describe this chart"`
+   - Automatically detected via HTTP HEAD request
+
+2. **Local File Attachments**:
+   - Images: Read as bytes, base64 encoded
+   - Documents: Read as bytes, base64 encoded
+   - Text: Read as UTF-8
+   - Example: `tsu run -f image.jpg "What's in this image?"`
+
+3. **LLM Integration**:
+   - Images: Sent as `image_url` content blocks (URL or data URI)
+   - Audio: Sent as `input_audio` content blocks (base64)
+   - Documents: Sent as `file` content blocks (URL or data URI)
+   - Text: Sent as `text` content blocks (wrapped in XML tags)
+
+**Examples:**
+
+```bash
+# Analyze an image from URL
+tsu run -f https://example.com/chart.png "Describe this chart"
+
+# Analyze a local image
+tsu run -f screenshot.png "What error is shown?"
+
+# Analyze a PDF
+tsu run -f report.pdf "Summarize this report"
+
+# Multiple attachments
+tsu run -f image1.jpg -f image2.jpg "Compare these images"
+```
+
+**Model Support:**
+- Vision: Claude 3.5 Sonnet, GPT-4o, GPT-4 Turbo, Gemini Pro Vision, etc.
+- Audio: GPT-4o Audio Preview
+- Documents: Claude (Bedrock/API), GPT-4o, Gemini, Bedrock Anthropic models
+
+**Implementation Details:**
+- `Attachment` dataclass: `tsugite/attachments/base.py`
+- URL handler: `tsugite/attachments/url.py` (detects content type via HEAD request)
+- File handler: `tsugite/attachments/file.py` (detects type by extension)
+- Auto-context handler: `tsugite/attachments/auto_context.py` (discovers CONTEXT.md, AGENTS.md, CLAUDE.md)
+- YouTube handler: `tsugite/attachments/youtube.py` (fetches transcripts)
+- LLM formatting: `tsugite/core/agent.py:_format_attachment()`
+
+## Development Patterns
+
+### Adding a New Built-in Agent
+
+1. Create `tsugite/builtin_agents/my_agent.md`
+2. Add frontmatter with `name`, `tools`, `description`
+3. Write agent template
+4. No code changes needed - auto-discovered
+5. Add tests in `tests/test_builtin_agents.py`
+
+### Adding a New Tool
+
+1. Create tool function in `tsugite/tools/`
+2. Register in tool registry (`tools/__init__.py`)
+3. Define parameters with JSON schema
+4. Add to category if applicable (`@fs`, `@http`, etc.)
+5. Add tests in `tests/test_*_tools.py`
+
+### Adding a New Event Type
+
+1. Add to `EventType` enum (`events/base.py`)
+2. Create event class in `events/events.py`
+3. Update UI handlers to handle new event
+4. Add tests in `tests/events/`
+
+### Modifying AgentConfig
+
+1. Update `AgentConfig` Pydantic model (`md_agents.py`)
+2. Regenerate schema: `uv run python scripts/regenerate_schema.py`
+3. Update documentation in CLAUDE.md (user guide section)
+4. Add validation tests in `tests/test_agent_parser.py`
+
+## Testing Strategy
+
+- **TDD preferred**: Write tests first when building new features. Tests don't need to be elaborate — simple tests that verify the expected behavior are enough. This creates a fast feedback loop and catches integration issues early (e.g., contextvar propagation, tool registration) before manual testing.
+- **Unit tests**: Individual functions and classes
+- **Pipeline tests**: Mock only `TsugiteAgent`/`litellm.acompletion` but exercise the full pipeline (parsing → rendering → preparation → tool expansion → execution). Most tests in the suite are this style.
+- **Smoke tests**: `tests/smoke_test.sh` hits a real LLM API (requires `OPENAI_API_KEY`, not run in CI)
+- **Fixtures**: `conftest.py` provides shared test data
+- **Mocking**: Use `@pytest.fixture` for LLM responses
+- **Async tests**: Mark with `@pytest.mark.asyncio`
+- **Coverage target**: 80%+ (check with `--cov-report=html`)
+
+## Code Style
+
+- Python 3.11+ (type hints on public APIs)
+- Line length: 120 characters (Black)
+- Import order: stdlib → third-party → local (blank lines between groups)
+- Errors: `ValueError` for input validation, `RuntimeError` for execution failures
+- Docstrings: Google style with `Args:` and `Returns:` sections
+- Pydantic models: Use `extra="forbid"` to catch typos in YAML frontmatter
+
+## Common Pitfalls
+
+1. **Don't break render/run parity**: Changes to rendering must update BOTH `renderer.py` and `agent_preparation.py`
+2. **Don't emit print/console directly**: Use event system (`EventBus.emit()`)
+3. **Don't forget schema regen**: After modifying `AgentConfig`, regenerate schema
+4. **Don't hardcode paths**: Use XDG utilities (`get_xdg_config_path()`, etc.)
+5. **Don't use blocking IO in async**: Use `asyncio.to_thread()` for sync tools
+6. **Test both sync and async paths**: Many tools support both execution modes
+7. **Don't embed prompts in adapters/code**: Use context variables + conditional blocks in `default.md` instead. Add new context vars in `_build_agent_context()` (base adapter) and default them in `agent_preparation.py`, then use `{% if var %}` in the agent template. This keeps all prompt content in one place and leverages the existing rendering pipeline.
+
+## Code Review Policy
+
+- **Automatically run the `code-simplifier:code-simplifier` agent** (via the Task tool) after implementing any changes, without waiting for the user to ask. This catches duplication, unnecessary complexity, and keeps the codebase DRY.
+- When making implementation plans, include a final "simplify/review" step that uses the code-simplifier agent on all modified files.

tsugite_cli-0.8.2/CLAUDE.md

@@ -0,0 +1 @@
+See [AGENTS.md](AGENTS.md) for project instructions.

{tsugite_cli-0.3.3 → tsugite_cli-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsugite-cli
-Version: 0.3.3
+Version: 0.8.2
 Summary: Micro-agent runner for task automation using markdown definitions
 Author: Justyn Shull
 License: GNU AFFERO GENERAL PUBLIC LICENSE
@@ -248,15 +248,23 @@ Requires-Dist: jinja2>=3.1
 Requires-Dist: litellm>=1.77.7
 Requires-Dist: mcp>=1.0
 Requires-Dist: nest-asyncio>=1.6.0
+Requires-Dist: pathspec>=0.11.0
+Requires-Dist: portalocker>=2.8.0
+Requires-Dist: prompt-toolkit>=3.0.43
 Requires-Dist: pydantic>=2.12.3
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: questionary>=2.1.1
 Requires-Dist: rich>=13.0
-Requires-Dist: ruff>=0.13.2
-Requires-Dist: textual-autocomplete>=4.0.6
-Requires-Dist: textual>=6.2.1
 Requires-Dist: typer>=0.12
+Requires-Dist: tzlocal>=5.3.1
 Requires-Dist: youtube-transcript-api>=0.6.0
+Provides-Extra: daemon
+Requires-Dist: cronsim>=2.6; extra == 'daemon'
+Requires-Dist: discord-py>=2.3.2; extra == 'daemon'
+Requires-Dist: py-vapid>=1.9.0; extra == 'daemon'
+Requires-Dist: pywebpush>=2.0.0; extra == 'daemon'
+Requires-Dist: starlette>=0.36; extra == 'daemon'
+Requires-Dist: uvicorn>=0.25; extra == 'daemon'
 Description-Content-Type: text/markdown
 
 # tsugite
@@ -265,12 +273,24 @@ Tsugite (Japanese: 継ぎ手, the art of joinery in woodworking) is a developer-
 
 Define AI agents as markdown files with YAML frontmatter. Chain multiple steps together, pass data between them, and use any LLM (OpenAI, Anthropic, Ollama, etc).
 
-## Quick Start
+## Installation
 
 ```bash
-# Install
-uv sync --dev
+# Recommended: Install with uv
+uv tool install tsugite-cli
+
+# Alternative: Install with pipx
+pipx install tsugite-cli
+
+# Or with pip
+pip install tsugite-cli
+```
 
+**Note:** The package name is `tsugite-cli`, but the command is `tsugite` (or `tsu` for short).
+
+## Quick Start
+
+```bash
 # Run an agent
 tsugite run examples/simple_variable_injection.md "test it"
 
@@ -322,4 +342,89 @@ tsugite history list
 tsugite history show CONV_ID
 ```
 
+## Sandbox
+
+Agent code can run inside a [bubblewrap](https://github.com/containers/bubblewrap) sandbox with filesystem and network isolation.
+
+```bash
+# Sandbox with specific domains allowed
+tsu run +default "task" --sandbox --allow-domain "github.com" --allow-domain "*.openai.com"
+
+# Full network isolation
+tsu run +default "task" --sandbox --no-network
+```
+
+**How it works:**
+
+```
+CLI --sandbox --allow-domain "*.github.com"
+ └─ SubprocessExecutor writes harness script
+     └─ bwrap --unshare-pid --unshare-net --die-with-parent ...
+         └─ TCP↔UDS bridge (HTTP_PROXY → Unix socket)
+             └─ ConnectProxy filters CONNECT requests by domain:port
+```
+
+**Default mounts:**
+
+- Read-only: `/usr`, `/lib`, `/lib64`, `/bin`, `/sbin`, `/etc/ssl`, `/etc/resolv.conf`, CA certs, Python venv + `sys.path`
+- Read-write: workspace directory, internal state directory
+- Tmpfs: `/tmp` (fresh each run)
+
+Extra bind mounts can be added programmatically via `SandboxConfig.extra_ro_binds` and `extra_rw_binds`, but these are not yet exposed through CLI flags or agent frontmatter.
+
+**Network:**
+- Network is namespace-isolated; outbound HTTP/HTTPS goes through a filtering CONNECT proxy
+- Direct connections to bare IP addresses are always blocked
+- `--no-network` skips the proxy entirely — no connectivity at all
+
+**`--allow-domain` syntax:**
+
+| Pattern | Allows |
+|---|---|
+| `github.com` | ports 80, 443 |
+| `github.com:22` | port 22 only |
+| `*.github.com:8080` | port 8080 on subdomains |
+| `*:*` | all domains, all ports |
+
+## Hooks
+
+Hooks fire shell commands at lifecycle points. Configure in `.tsugite/hooks.yaml`:
+
+```yaml
+hooks:
+  post_tool:
+    - tools: [write_file]
+      run: git add {{ path }}
+      wait: true
+
+  pre_message:
+    - run: uridx search "{{ message }}" --limit 5
+      capture_as: rag_context
+    - run: cat memory/preferences.md
+      capture_as: user_preferences
+
+  pre_compact:
+    - run: ./scripts/extract-facts.sh {{ turns_file }}
+      wait: true
+
+  post_compact:
+    - run: echo "Compacted {{ turns_compacted }} turns"
+```
+
+**Hook fields:** `run` (Jinja2 shell command), `tools` (tool filter, `post_tool` only), `match` (Jinja2 condition), `wait` (block until done), `capture_as` (capture stdout into a template variable, implies `wait`).
+
+**Hook types:**
+- **`post_tool`** — After successful tool calls. Context: `tool`, plus tool arguments.
+- **`pre_message`** — Before agent execution. Context: `message`, `user_id`, `agent_name`. Use `capture_as` to inject results into agent templates as `{{ var_name }}`.
+- **`pre_compact`** / **`post_compact`** — Around session compaction. Context: `conversation_id`, `user_id`, `agent_name`, `turns_file`, `turn_count`.
+
+## Development
+
+```bash
+# Clone and install for development
+git clone https://github.com/justyns/tsugite.git
+cd tsugite
+uv sync --dev
+```
+
 See `examples/` for working agents and `CLAUDE.md` for AI-generated documentation.