aionrs

A Rust-based LLM tool-use agent for the command line. It connects to LLM APIs, autonomously invokes local tools (file I/O, shell, search, etc.), and completes tasks end-to-end.

Features

• Multi-provider — Anthropic, OpenAI (and compatibles like DeepSeek/Ollama/Gemini), AWS Bedrock, Google Vertex AI
• ProviderCompat layer — Configuration-driven compatibility for provider quirks (no hardcoded conditionals)
• Reasoning model support — Configurable thinking and reasoning effort for supported models
• Local tool suite — Read, Write, Edit, ExecCommand, Grep, Glob, ViewImage, and Spawn (sub-agents), plus Skills, plan mode, and deferred tool discovery
• OpenAI Responses API — Use either Chat Completions or Responses through the compatibility layer
• MCP client — Connect to any Model Context Protocol server (stdio / SSE / streamable-http)
• Dynamic MCP injection — Host clients can inject MCP servers at runtime via the JSON stream protocol
• Skills — Named prompt snippets with variable substitution, shell expansion, conditional activation, and per-skill model/permission overrides (see docs/skills.md)
• Hook system — Event-driven automation on tool lifecycle (auto-format, lint, audit)
• Sub-agent spawning — Parallel task execution via the Spawn tool
• Session persistence — Save and resume conversation history
• Persistent memory — Project-specific memory with auto-indexing across sessions (see docs/advanced.md)
• Plan mode — Read-only exploration mode for designing implementation plans before coding (see docs/advanced.md)
• Context compression — Stable tool-output limits, token-based autocompact, and an emergency guard (see docs/advanced.md)
• Output compaction — Configurable output compression (off/safe/full) with TOON encoding (see docs/advanced.md)
• File state cache — LRU cache with read deduplication and write tracking
• Prompt caching — Anthropic cache_control for up to 90% cost reduction
• Profile inheritance — Named profiles with extends for quick provider/model switching
• OAuth login — Use Claude.ai subscription directly, no API key needed
• AGENTS.md injection — Hierarchical loading of project instructions with @include support

Quick Start

# Build from source
cargo build --release

# Generate default config, then add your API key
./target/release/aionrs config init
# Edit the generated config (run `aionrs config path` to find it)

# Single-shot mode
aionrs "Read Cargo.toml and explain the dependencies"

# Interactive REPL
aionrs

# Full CLI reference
aionrs --help

Interactive terminal sessions keep finalized conversation in the terminal's native scrollback with an inline composer at the bottom. Type / to browse available commands; use Enter to send, Shift+Enter (or Ctrl+J as a fallback) for a newline, and Ctrl+C to stop the active turn. Use the mouse wheel to read earlier finalized conversation content. Mouse capture stays disabled so terminal text can be selected and copied normally. Consecutive tool calls are collected under one • Tools step with an appended status row for each call. Status keeps an explicit label and semantic color, while tool input and output use a responsive one-line preview instead of occupying the conversation viewport.

TUI-owned commands include /status, /model, /permissions, /new, /resume, /mcp, and /skills. Running /resume without an ID opens a full-screen, mouse- and keyboard-navigable picker containing every saved session up to the configured session.max_sessions retention limit. Session switches rebuild the agent runtime without exiting the interactive UI. A fresh TUI does not create a session until the first conversation message is sent.

Runtime Limits

max_turns is the broad model-turn limit per run. It is unset by default, so runs have no broad model-turn limit unless you configure one. Set it to 0 to explicitly disable the broad limit. max_tool_call_malformed_turns stops repeated same tool-call-malformed rounds earlier; it defaults to 3. max_tool_call_failure_turns finalizes repeated failed tool-call patterns based on failed tool names and inputs, regardless of assistant text or successful sibling calls in the same round; it also defaults to 3. The failure guard additionally detects consecutive all-error rounds and short repeating call cycles. Set either guard to 0 to disable that breaker and rely on max_turns if a broad turn limit is configured.

See Core Concepts for the distinction between runs, turns, tool rounds, and tool calls.

[default]
max_turns = 20  # optional broad model-turn limit
max_tool_call_malformed_turns = 3
max_tool_call_failure_turns = 3

# Profile names are user-defined; this is not a built-in profile.
[profiles.my-weak-provider]
max_turns = 10
max_tool_call_malformed_turns = 2
max_tool_call_failure_turns = 2

CLI override:

aionrs --max-turns 10 "Run the task"
aionrs --max-tool-call-malformed-turns 2 "Run the task"
aionrs --max-tool-call-failure-turns 2 "Run the task"

Architecture

┌──────────────────────────────────────────────────────────────┐
│                      main.rs (CLI / REPL)                    │
├──────────────────────────────────────────────────────────────┤
│  Config          │  Engine (agent loop)  │  Session Manager  │
│  (3-level merge) │  streaming + tools    │  save / resume    │
├──────────────────┼───────────────────────┼───────────────────┤
│  Providers       │  Tool Registry        │  Hook Executor    │
│  ├ Anthropic     │  ├ Local + agent tools│  ├ pre_tool_use   │
│  ├ OpenAI        │  ├ MCP tools (N)      │  ├ post_tool_use  │
│  ├ Bedrock       │  └ Plan Mode tools    │  └ stop           │
│  └ Vertex AI     │                       │                   │
│                  │  MCP Client           │  Memory System    │
│  ProviderCompat  │  ├ Stdio transport    │  (per-project)    │
│  (compat layer)  │  ├ SSE transport      │                   │
│                  │  └ HTTP transport     │  Sub-Agent        │
│  Compact Engine  │                       │  Spawner          │
│  ├ Microcompact  │  File State Cache     │                   │
│  ├ Autocompact   │  (LRU)                │  Output Compactor │
│  └ Emergency     │                       │  (off/safe/full)  │
└──────────────────┴───────────────────────┴───────────────────┘

Documentation

Document	Description
Getting Started	Installation, CLI reference, configuration, usage examples
Built-in Tools	Detailed reference for bundled local and agent tools
MCP Integration	Model Context Protocol client setup and usage
Providers & Auth	Multi-provider config, profiles, Bedrock, Vertex, OAuth
Advanced Features	Sub-agents, hooks, prompt caching, VCR, AGENTS.md
Troubleshooting	Common errors and solutions
JSON Stream Protocol	Host integration protocol (--json-stream mode)

Supported Providers

Provider	Auth	Notes
Anthropic	API Key / OAuth	Prompt caching, streaming, vision
OpenAI	API Key	Reasoning models (o1/o3), compatible with DeepSeek, Qwen, Ollama, Gemini, vLLM
AWS Bedrock	SigV4	Regional endpoints, AWS credential chain, schema sanitization, actionable error hints
Google Vertex AI	GCP OAuth2 / Service Account	Metadata server auto-detection

ProviderCompat

All provider-specific behaviors are driven by the ProviderCompat configuration layer — no hardcoded URL or model-name checks. Each provider type has sensible defaults; override any field via config:

[providers.my-openai.compat]
max_tokens_field = "max_completion_tokens"   # Field name for max tokens
merge_assistant_messages = true              # Merge consecutive assistant messages
clean_orphan_tool_calls = true               # Remove tool_use without tool_result
dedup_tool_results = true                    # Deduplicate same tool_call_id results
ensure_alternation = false                   # Insert filler for user/assistant alternation
merge_same_role = false                      # Merge consecutive same-role messages
sanitize_schema = false                      # Bedrock-style schema sanitization
strip_patterns = ["<think>", "</think>"]     # Strip text patterns from history
auto_tool_id = false                         # Auto-generate missing tool IDs
api_path = "/v1/chat/completions"            # Custom chat completions endpoint path

Provider defaults: Anthropic/Vertex — alternation, merge, auto tool ID; Bedrock — same + schema sanitization; OpenAI — assistant merge, orphan cleanup, dedup.

License

Apache-2.0