@aiiware/aii 0.10.6 → 0.10.7

package/README.md

@@ -1,6 +1,6 @@
 # @aiiware/aii
 
-**AI-powered CLI assistant** with autonomous tool execution. An intelligent agent that can read, write, search, and execute commands in your terminal.
+**AI-powered CLI agent** with autonomous tool execution, multi-agent delegation, and multi-channel access. An intelligent assistant that can read, write, search, and execute commands in your terminal — or through Telegram.
 
 ## Installation
 
@@ -19,13 +19,13 @@ npm install -g @aiiware/aii
 # Start interactive agent mode
 aii
 
-# Or run a single query
+# Run a single task
 aii "explain what this project does"
 
 # Pipe content for processing
 cat error.log | aii "summarize the errors"
 
-# Auto-approve tool execution
+# Auto-approve all tool executions
 aii --auto
 ```
 
@@ -40,212 +40,211 @@ aii "your task"        # Run single task and exit
 
 ### Available Tools
 
-| Tool          | Description                    |
-|---------------|--------------------------------|
-| **Read**      | Read file contents             |
-| **Write**     | Create or overwrite files      |
-| **Edit**      | Make targeted edits to files   |
-| **Glob**      | Find files by pattern          |
-| **Grep**      | Search code with regex         |
-| **Bash**      | Execute shell commands         |
-| **WebSearch** | Search the web                 |
-| **WebFetch**  | Fetch and parse web pages      |
+| Tool          | Description                              |
+|---------------|------------------------------------------|
+| **Read**      | Read file contents                       |
+| **Write**     | Create or overwrite files                |
+| **Edit**      | Make targeted edits to files             |
+| **Glob**      | Find files by pattern                    |
+| **Grep**      | Search code with regex                   |
+| **Bash**      | Execute shell commands                   |
+| **WebSearch** | Search the web                           |
+| **WebFetch**  | Fetch and parse web pages                |
+| **Task**      | Delegate work to specialized subagents   |
 
 ### Interactive Commands
 
-In agent mode, use these commands:
-
 ```text
 /help              Show available commands
 /clear             Clear conversation history
-/history           Show conversation history
-/stats             Show session statistics (tokens, cost)
+/new               Start a fresh conversation
+/history           Show conversation summary
 /model <model>     Switch LLM model
 /provider <name>   Switch LLM provider
 /context           View context window usage
+/stats             Show session statistics (tokens, cost)
 /init              Generate AGENTS.md for your project
-/init --with-hooks Generate AGENTS.md + hooks.json template
-/init help         Show /init usage and options
-/hooks help        Show /hooks usage and options
 /memory            View loaded project instructions
-/memory reload     Hot-reload instructions without restart
 /hooks             View configured hooks
-/hooks reload      Hot-reload hooks without restart
 /skills            List available skills
-/skills help       Show skills management commands
-/skills reload     Re-discover skills without restarting
 /commit            Generate commit message and commit
+/loop              Start autonomous agent loop
+/mcp               Manage MCP servers
+/agents            List available subagents
+/tasks             Inspect subagent task executions
+/diff              Show recent file changes
+/undo              Undo the last file change
+/mode              Show or switch operation mode (normal/auto/plan)
 /exit              Exit the session
 ```
 
 ### Keyboard Shortcuts
 
-| Key        | Action                     |
-|------------|----------------------------|
-| `Enter`    | Submit input               |
-| `Esc`      | Cancel current request     |
-| `Ctrl+C`   | Exit immediately           |
-| `Up/Down`  | Navigate input history     |
-| `Tab`      | Autocomplete commands      |
+| Key        | Action                              |
+|------------|-------------------------------------|
+| `Enter`    | Submit input                        |
+| `Esc`      | Cancel current request              |
+| `Ctrl+C`   | Exit immediately                    |
+| `Ctrl+D`   | Graceful exit with session summary  |
+| `Ctrl+L`   | Clear conversation                  |
+| `Up/Down`  | Navigate input history              |
+| `Tab`      | Select from command menu            |
 
-## Output Modes
+## Multi-Agent Subagents (v0.10)
 
-```bash
-aii "query" --clean        # Just the result
-aii "query" --standard     # Result + metrics (default)
-aii "query" --thinking     # Full reasoning chain
+Delegate complex tasks to specialized subagents that run in parallel within the same session:
+
+```text
+> analyze my codebase architecture and review the auth module
+
+  ● Running 2 agents...
+    ├─ Explore (Analyze codebase architecture) · 8 tool uses
+    │    └ Running (5s)
+    └─ Review (Review auth module) · 3 tool uses
+         └ Running (2s)
 ```
 
-## Prompt Templates
+### Built-in Subagents
 
-Use pre-built templates for common tasks:
+| Subagent    | Purpose                                |
+|-------------|----------------------------------------|
+| **explore** | Fast codebase exploration (read-only)  |
+| **plan**    | Architecture and implementation design |
+| **review**  | Code quality analysis                  |
 
-```bash
-aii prompt list                       # List available prompts
-aii prompt show <name>                # Show prompt details
-aii prompt use <name> --var value     # Use a prompt template
-```
+### Custom Subagents
 
-## Configuration
+Define your own subagents in `.aii/agents/` with custom system prompts, model tiers, and tool access levels.
+
+### Task Inspection
 
 ```bash
-aii config show                # Show current configuration
-aii config validate            # Validate configuration
-aii config set <key> <value>   # Set a configuration value
-aii config model <model>       # Change LLM model
-aii config provider <provider> # Change LLM provider
+/tasks              # List all task executions with IDs
+/tasks <id>         # Show full transcript for a specific task
 ```
 
-### Config Files
-
-Configuration is stored in `~/.aii/`:
+## Telegram Bot Channel (v0.10)
 
-**config.yaml** - Main configuration:
+Access your AI agent remotely through Telegram — works anywhere, no port forwarding needed:
 
-```yaml
-llm:
-  provider: anthropic
-  model: claude-sonnet-4
-  temperature: 0.7
-
-api:
-  url: http://localhost:26169
-```
+```bash
+# Pair a Telegram bot
+aii telegram pair mybot <bot-token>
 
-**secrets.yaml** - API keys:
+# Start the bot listener
+aii telegram start mybot
 
-```yaml
-anthropic_api_key: sk-ant-...
-openai_api_key: sk-...
-deepseek_api_key: sk-...
+# Manage multiple bots
+aii telegram list
+aii telegram status mybot
+aii telegram unpair mybot
 ```
 
-Or use environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`
+**Bot commands in Telegram**: `/start`, `/help`, `/reset`, `/status`, `/compact`, `/model`
 
-## CLI Options
+## MCP Integration (v0.10)
 
-| Option               | Description                      |
-|----------------------|----------------------------------|
-| `--auto`             | Auto-approve all tool executions |
-| `--clean`            | Clean output mode                |
-| `--standard`         | Standard output mode (default)   |
-| `--thinking`         | Show full reasoning              |
-| `--model <model>`    | Override LLM model               |
-| `--host <host:port>` | API server host                  |
-| `--no-streaming`     | Disable streaming output         |
-| `--quiet`            | Minimal output                   |
-| `--verbose`          | Show detailed stats              |
-| `--no-context`       | Disable context management       |
+Extend the agent with external tools via Model Context Protocol:
 
-## Context Window Management (v0.3.0)
+```bash
+/mcp catalog                    # Browse available servers
+/mcp install github             # One-command install from catalog
+/mcp add myserver cmd args...   # Add custom server
+/mcp list                       # Show configured servers
+/mcp remove myserver            # Remove a server
+```
 
-Prevents "token limit exceeded" errors in long conversations with intelligent auto-summarization.
+Once installed, MCP tools are available to the agent automatically.
 
-**Status Bar Indicator**: Shows real-time usage with color-coded alerts (🟢 🟡 🔴)
+## Autonomous Loops (v0.7)
 
-**Dynamic Thresholds**: Automatically adjusts based on each model's output capacity
+Run the agent in a continuous loop for long-running autonomous tasks:
 
-- Claude Sonnet (32% output) → 63% critical threshold
-- Gemini Flash (3% output) → 92% critical threshold
+```bash
+# Start a loop from CLI
+aii loop --verify "npm test" --duration 5m
 
-**Auto-Summarization**: Older messages summarized when reaching critical threshold (~70%), preserving recent ~30K tokens in full
+# Or start within a session
+/loop --max 10 --promise "All tests passing"
+```
 
-**Commands**:
+**Options**:
 
-- `/context` - View detailed usage breakdown
-- `/context clear` - Manually trigger summarization
+| Option               | Description                              |
+|----------------------|------------------------------------------|
+| `--max <N>`          | Maximum iterations                       |
+| `--verify "<cmd>"`   | Run verification command after each step |
+| `--promise "<text>"` | Stop when output contains this text      |
+| `--budget <$N>`      | Cost limit                               |
+| `--duration <time>`  | Time limit (e.g., `30m`, `2h`)           |
 
-## Project Instructions (v0.5.0)
+## LLM Providers
 
-Teach the agent your project's conventions. Create an `AGENTS.md` file in your project root, and the agent will automatically learn your coding standards, commands, and rules.
+Aii supports multiple LLM providers. Switch anytime with `/model` or `/provider`:
 
-### Quick Setup
+| Provider | Models | Setup |
+| --- | --- | --- |
+| **Anthropic** | Claude Sonnet, Opus, Haiku | API key |
+| **OpenAI** | GPT-4o, GPT-4, o1, o3 | API key |
+| **Google** | Gemini Pro, Flash | API key |
+| **DeepSeek** | DeepSeek Chat, Coder | API key |
+| **Ollama** | Llama, Mistral, and more | Local, no API key |
+| **OpenRouter** | 300+ models via single API key | API key |
 
 ```bash
-# Auto-generate AGENTS.md by analyzing your project
-/init
-
-# View what instructions are loaded
-/memory
+# Switch provider and model mid-session
+/model claude-sonnet-4
+/model ollama/llama3.1:8b
+/provider openrouter
 ```
 
-The `/init` command detects your language, framework, build commands, and generates a customized `AGENTS.md`. Edit it to add your team's conventions.
-
-### Supported Files
+The provider is auto-detected from model names (e.g., `gpt-4o` routes to OpenAI).
 
-The agent discovers instruction files in this priority order:
+## Context Window Management (v0.3)
 
-- `AII.md` or `AGENTS.md` in project root
-- `~/.aii/AGENTS.md` for global preferences
+Prevents "token limit exceeded" errors with intelligent auto-summarization:
 
-### Example AGENTS.md
+- **Status bar** shows real-time context usage with color-coded alerts
+- **Auto-summarization** triggers when approaching the limit, preserving recent context
+- **Dynamic thresholds** adjust per model's output capacity
 
-```markdown
-# My Project
-
-## Commands
-- Build: `npm run build`
-- Test: `npm test`
-- Lint: `npm run lint`
-
-## Coding Standards
-- Use TypeScript strict mode
-- Prefer async/await over callbacks
-- Maximum line length: 100
-
-## Safety Rules
-Never modify without asking:
-- .env files
-- Database migrations
+```bash
+/context            # View detailed usage breakdown
+/context clear      # Manually trigger summarization
 ```
 
-## Hooks (v0.5.0)
+## Project Instructions (v0.5)
 
-Extend agent behavior with custom scripts. Create `.aii/hooks.json` to run scripts before/after tool execution:
+Teach the agent your project's conventions with `AGENTS.md`:
 
 ```bash
-# Generate a hooks template
-/init --with-hooks
+/init                   # Auto-generate by analyzing your project
+/init --with-hooks      # Also generate hooks.json template
+/memory                 # View loaded instructions
+/memory reload          # Hot-reload without restart
+```
 
-# View configured hooks
-/hooks
+The agent discovers `AII.md` or `AGENTS.md` in your project root, plus `~/.aii/AGENTS.md` for global preferences.
 
-# Show usage and options
-/hooks help
-```
+## Hooks (v0.5)
 
-Hooks let you add validation, logging, or approval gates. See the [hooks documentation](https://aiiware.com/docs/hooks) for details.
+Run custom scripts before/after tool execution:
 
-## Skills (v0.6.0)
+```bash
+/init --with-hooks      # Generate hooks template
+/hooks                  # View configured hooks
+/hooks reload           # Hot-reload without restart
+```
+
+Hook types: `PreToolUse`, `PostToolUse`, `Stop`, `Iteration`
 
-Skills are reusable agent prompts that extend Aii with specialized capabilities.
+## Skills (v0.6)
 
-### Invoking Skills
+Extend the agent with reusable skill packages:
 
-**Natural language** -- just describe what you want, and the agent detects the right skill:
+**Natural language** — the agent auto-detects the right skill:
 
 ```text
-> explain what's an LLM
 > commit my changes
 > review the latest PR
 ```
@@ -254,83 +253,107 @@ Skills are reusable agent prompts that extend Aii with specialized capabilities.
 
 ```bash
 /commit              # Generate commit message and execute
-/commit --dry-run    # Preview commit message only
 /review-pr 123       # Review a pull request
 ```
 
-### Managing Skills
+**Managing skills**:
 
 ```bash
-/skills              # List all skills (built-in, project, user)
-/skills help         # Show all skills management commands
-/skills reload       # Re-discover skills without restarting
+/skills                                        # List all skills
+/skills install aiiware/skills/code-review     # Install from GitHub
+/skills install aiiware/skills/refactor --user # Install globally
+/skills uninstall code-review                  # Remove a skill
+/skills reload                                 # Re-discover skills
 ```
 
-### Built-in Skills
+**Creating skills** — add `SKILL.md` files in `.aii/skills/`:
 
-| Skill        | Description                              |
-|--------------|------------------------------------------|
-| `/commit`    | Generate conventional commit messages    |
-| `/review-pr` | Review PRs with quality checklist        |
+```markdown
+---
+name: my-skill
+description: Does something useful
+allowed-tools: Bash Read Grep
+---
 
-### Installing Skills
+Instructions for the agent...
+Use $ARGUMENTS for user input.
+```
 
-Install skills from GitHub repositories:
+## Configuration
 
 ```bash
-# Shorthand format (owner/repo/skill-name)
-/skills install aiiware/skills/code-review    # Install to project (.aii/skills/)
-/skills install aiiware/skills/refactor --user # Install globally (~/.aii/skills/)
+aii config show                # Show current configuration
+aii config validate            # Validate configuration
+aii config set <key> <value>   # Set a configuration value
+aii config model <model>       # Change LLM model
+aii config provider <provider> # Change LLM provider
+```
 
-# Absolute GitHub URL format
-/skills install https://github.com/aiiware/skills/tree/main/code-review
-/skills install https://github.com/aiiware/skills/tree/main/refactor --user
+Configuration is stored in `~/.aii/`:
 
-# Uninstall
-/skills uninstall code-review
-```
+**config.yaml** — Main configuration:
 
-**Shorthand format**: `owner/repo/skill-name` resolves to `github.com/owner/repo/skill-name/SKILL.md`
+```yaml
+llm:
+  provider: anthropic
+  model: claude-sonnet-4
+  temperature: 0.7
 
-**URL format**: Use absolute GitHub URLs when you need to install from a specific branch or path.
+api:
+  url: http://localhost:26169
+```
 
-### Creating Custom Skills
+**secrets.yaml** — API keys:
 
-Create skills in `.aii/skills/my-skill/SKILL.md`:
+```yaml
+anthropic_api_key: sk-ant-...
+openai_api_key: sk-...
+deepseek_api_key: sk-...
+```
 
-```markdown
----
-name: my-skill
-description: Does something useful
-allowed-tools: Bash Read Grep
----
+Or use environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`
 
-# My Skill
+## CLI Options
 
-Instructions for the agent...
-Use $ARGUMENTS for user input.
-```
+| Option                     | Description                      |
+|----------------------------|----------------------------------|
+| `--auto`                   | Auto-approve all tool executions |
+| `--model <model>`          | Override LLM model               |
+| `--provider <provider>`    | Override LLM provider            |
+| `--host <host:port>`       | API server host                  |
+| `-c, --continue-chat <id>` | Continue a previous session      |
+| `-n, --new-chat`           | Force a new session              |
+| `--offline`                | Disable web and MCP tools        |
+| `--clean`                  | Clean output mode                |
+| `--standard`               | Standard output mode (default)   |
+| `--thinking`               | Show full reasoning              |
+| `--no-streaming`           | Disable streaming output         |
+| `-q, --quiet`              | Minimal output                   |
+| `-y, --yes`                | Auto-confirm shell commands      |
 
 ## System Commands
 
 ```bash
 aii doctor         # System health check
+aii stats          # Usage analytics (models, cost)
 aii --help         # Show help
 aii --version      # Show version
 ```
 
 ## Features
 
-- **Autonomous Agent**: Executes multi-step tasks with tool use
-- **Real-time Streaming**: Token-by-token response display
-- **Interactive Mode**: Multi-turn conversations with full context
-- **Tool Execution**: Read, write, search, and run commands
-- **Multiple Providers**: Claude, GPT, Gemini, DeepSeek
-- **Prompt Templates**: Pre-built templates for common tasks
-- **Project Instructions**: Teach the agent your conventions with AGENTS.md
-- **Skills System**: Extend with reusable agent skills, invokable via slash commands or natural language
-- **Input History**: Navigate previous inputs with arrow keys
-- **Cancellation**: Press Esc to cancel any request
+- **Autonomous Agent** — Executes multi-step tasks with tool use
+- **Multi-Agent Delegation** — Parallel subagents for complex tasks
+- **Telegram Access** — Use your agent remotely via Telegram bots
+- **MCP Integration** — Extend with external tools via Model Context Protocol
+- **Autonomous Loops** — Continuous agent execution with verification and budgets
+- **Multiple Providers** — Claude, GPT, Gemini, DeepSeek, Ollama, OpenRouter
+- **Real-time Streaming** — Token-by-token response display
+- **Context Management** — Auto-summarization prevents token limit errors
+- **Project Instructions** — Teach the agent your conventions with AGENTS.md
+- **Skills System** — Extend with reusable skills, invokable via commands or natural language
+- **Hooks** — Custom scripts for validation, logging, and approval gates
+- **Session Persistence** — Continue previous conversations with `--continue-chat`
 
 ## Links