@aiiware/aii

AI-powered CLI agent with autonomous tool execution, multi-agent delegation, persistent server sessions, and multi-channel access. An intelligent assistant that can read, write, search, and execute commands in your terminal — or through Telegram — with conversations that persist across channels and restarts.

Installation

npm install -g @aiiware/aii

Requirements

• Node.js 18+
• Aii Server running (default: localhost:26169)

Quick Start

# Start interactive agent mode
aii

# Run a single task
aii "explain what this project does"

# Pipe content for processing
cat error.log | aii "summarize the errors"

# Auto-approve all tool executions
aii --auto

Agent Mode (Default)

Aii runs as an intelligent agent that can autonomously execute tools to complete tasks:

aii                    # Start interactive session
aii "your task"        # Run single task and exit

Available Tools

Interactive Commands

/help              Show available commands
/clear             Clear conversation history
/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
/memory            View loaded project instructions
/hooks             View configured hooks
/skills            List available skills
/commit            Generate commit message and commit
/loop              Start autonomous agent loop
/mcp               Manage MCP servers
/sessions          Manage server-managed sessions
/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

Multi-Agent Subagents (v0.10)

Delegate complex tasks to specialized subagents that run in parallel within the same session:

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

Built-in Subagents

Custom Subagents

Define your own subagents in .aii/agents/ with custom system prompts, model tiers, and tool access levels.

Task Inspection

/tasks              # List all task executions with IDs
/tasks <id>         # Show full transcript for a specific task

Telegram Bot Channel (v0.10)

Access your AI agent remotely through Telegram — works anywhere, no port forwarding needed:

# Pair a Telegram bot
aii telegram pair mybot <bot-token>

# Start the bot listener
aii telegram start mybot

# Manage multiple bots
aii telegram list
aii telegram status mybot
aii telegram unpair mybot

Bot commands in Telegram: /start, /help, /reset, /status, /compact, /model

Server Sessions (v0.11)

Conversations are managed by Aii Server with persistent storage. Sessions survive restarts and can be resumed from any channel:

# List recent sessions
aii sessions list

# Resume a previous session
aii sessions resume <id>

# View session details (stats, messages, context)
aii sessions info <id>

# Rename or delete
aii sessions rename <id> "my feature work"
aii sessions delete <id>

Cross-Channel Resume

Start a conversation in Telegram and continue from the CLI — full conversation history and context preserved:

# In Telegram: work on a task via bot
# Later, from CLI:
aii sessions list --channel telegram
aii sessions resume abc123

Interactive Session Management

/sessions list              # Browse recent sessions
/sessions info <id>         # View session details
/sessions resume <id>       # Switch to a server session mid-conversation
/sessions rename <id> name  # Rename a session
/sessions delete <id>       # Archive a session

Session stats track turns, tokens (in/out), cost, tool calls, and files modified. Subagent stats are aggregated to the parent session automatically.

MCP Integration (v0.10)

Extend the agent with external tools via Model Context Protocol:

/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

Once installed, MCP tools are available to the agent automatically.

Autonomous Loops (v0.7)

Run the agent in a continuous loop for long-running autonomous tasks:

# Start a loop from CLI
aii loop --verify "npm test" --duration 5m

# Or start within a session
/loop --max 10 --promise "All tests passing"

Options:

LLM Providers

Aii supports multiple LLM providers. The provider is auto-detected from the model name:

# Switch model mid-session
/model claude-sonnet-4-6
/model ollama/llama3.1:8b

# Use provider:model format for one-shot commands
aii "explain this code" --model deepseek:deepseek-chat
aii "translate hello" --model ollama:gpt-oss:20b

The provider is auto-detected from model names (e.g., gpt-4o routes to OpenAI, deepseek-chat routes to DeepSeek).

Context Window Management (v0.3)

Prevents "token limit exceeded" errors with intelligent auto-summarization:

• 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

/context            # View detailed usage breakdown
/context clear      # Manually trigger summarization

Project Instructions (v0.5)

Teach the agent your project's conventions with AGENTS.md:

/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

The agent discovers AII.md or AGENTS.md in your project root, plus ~/.aii/AGENTS.md for global preferences.

Hooks (v0.5)

Run custom scripts before/after tool execution:

/init --with-hooks      # Generate hooks template
/hooks                  # View configured hooks
/hooks reload           # Hot-reload without restart

Hook types: PreToolUse, PostToolUse, Stop, Iteration

Skills (v0.6)

Extend the agent with reusable skill packages:

Natural language — the agent auto-detects the right skill:

> commit my changes
> review the latest PR

Slash commands (explicit):

/commit              # Generate commit message and execute
/review-pr 123       # Review a pull request

Managing skills:

/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

Creating skills — add SKILL.md files in .aii/skills/:

---
name: my-skill
description: Does something useful
allowed-tools: Bash Read Grep
---

Instructions for the agent...
Use $ARGUMENTS for user input.

Configuration

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 (supports provider:model format)
aii config provider <provider> # Change LLM provider

Configuration is stored in ~/.aii/:

config.yaml — Main configuration:

llm:
  provider: anthropic
  model: claude-sonnet-4-6
  temperature: 0.7

api:
  url: http://localhost:26169

secrets.yaml — API keys:

anthropic_api_key: sk-ant-...
openai_api_key: sk-...
deepseek_api_key: sk-...

Or use environment variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY

CLI Options

System Commands

aii doctor         # System health check
aii stats          # Usage analytics (models, cost)
aii sessions list  # List server-managed sessions
aii --help         # Show help
aii --version      # Show version

Features

• 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
• Server Sessions — Persistent conversations that survive restarts and resume across channels
• Session Persistence — Continue previous conversations with --continue-chat or aii sessions resume

License

Proprietary - Copyright 2025-present AiiWare.com. All Rights Reserved.