aru-code 0.3.0

A Claude Code clone built with Agno agents

aru

An intelligent coding assistant for the terminal, powered by LLMs and Agno agents.

https://github.com/user-attachments/assets/17674bfc-3d49-4e25-bdc7-dc445d5a089d

Highlights

• Multi-Agent Architecture — Specialized agents for planning, execution, and conversation
• Interactive CLI — Streaming responses, multi-line paste, session management
• 16 Integrated Tools — File operations, code search, shell, web search, task delegation
• Task Planning — Break down complex tasks into steps with automatic execution
• Multi-Provider — Anthropic, OpenAI, Ollama, Groq, OpenRouter, DeepSeek, and others via custom configuration
• Custom Commands and Skills — Extend aru via the .agents/ directory
• MCP Support — Integration with Model Context Protocol servers

Quick Start

1. Install

pip install aru-code

Requirements: Python 3.13+

2. Configure the API Key

Aru uses Claude Sonnet 4.6 from Anthropic as the default model. You need an Anthropic API key to get started.

Set your API key as an environment variable or create a .env file in your project directory:

ANTHROPIC_API_KEY=sk-ant-your-key-here

Using another provider? See the Models and Providers section to configure OpenAI, Ollama, Groq, etc.

3. Run

aru

That's it — aru is available globally after install.

Usage

Commands

Command	Description
Natural language	Just type — aru handles the rest
/plan <task>	Creates a detailed implementation plan
/model [provider/model]	Switch models and providers
/mcp	List available MCP servers and tools
/commands	List custom commands
/skills	List available skills
/sessions	List recent sessions
/help	Show all commands
! <command>	Execute shell commands
/quit or /exit	Exit aru

CLI Options

aru                                    # Start new session
aru --resume <id>                      # Resume session
aru --resume last                      # Resume last session
aru --list                             # List sessions
aru --dangerously-skip-permissions     # Skip permission prompts

Examples

aru> /plan create a REST API with FastAPI to manage users

aru> refactor the authentication module to use JWT tokens

aru> ! pytest tests/ -v

aru> /model ollama/codellama

Configuration

Models and Providers

By default, aru uses Claude Sonnet 4.6 (Anthropic). You can switch to any supported provider during a session with /model:

Provider	Command	API Key (.env)	Extra Installation
Anthropic	/model anthropic/claude-sonnet-4-6	ANTHROPIC_API_KEY	— (included)
Ollama	/model ollama/llama3.1	— (local)	pip install "aru-code[ollama]"
OpenAI	/model openai/gpt-4o	OPENAI_API_KEY	pip install "aru-code[openai]"
Groq	/model groq/llama-3.3-70b-versatile	GROQ_API_KEY	pip install "aru-code[groq]"
OpenRouter	/model openrouter/deepseek/deepseek-chat-v3-0324	OPENROUTER_API_KEY	pip install "aru-code[openai]"

To install all providers at once:

pip install "aru-code[all-providers]"

Ollama (local models)

To run models locally without an API key, install Ollama, start the server, and use any installed model:

ollama serve                    # Start the Ollama server
ollama pull codellama           # Download a model
aru                             # Start aru
# Inside aru:
/model ollama/codellama

Configuring the default model

You can set the default provider/model in aru.json so you don't need to switch manually every session:

{
  "models": {
    "default": "openrouter/deepseek/deepseek-chat-v3-0324",
    "minimax": "openrouter/minimax/minimax-m2.5",
    "deepseek-v3": "openrouter/deepseek/deepseek-chat-v3-0324",
    "sonnet-4-6": "anthropic/claude-sonnet-4-6",
    "opus-4-6": "anthropic/claude-opus-4-6"
  }
}

The default field sets the main model. The other fields are aliases that can be used with /model <alias>.

Custom providers

You can configure custom providers with specific token limits:

{
  "providers": {
    "deepseek": {
      "models": {
        "deepseek-chat-v3-0324": {"id": "deepseek-chat-v3-0324", "max_tokens": 16384}
      }
    },
    "openrouter": {
      "models": {
        "minimax/minimax-m2.5": {"id": "minimax/minimax-m2.5", "max_tokens": 65536}
      }
    }
  }
}

Permissions (aru.json)

The aru.json file in the project root controls which shell commands aru can execute without asking for confirmation:

{
  "permission": {
    "allow": [
      "git *",
      "npm *",
      "pytest *",
      "python *",
      "uv run pytest *"
    ]
  }
}

Each entry is a glob pattern. Any command that doesn't match a listed pattern will prompt for confirmation before executing.

aru.json can also be placed at .aru/config.json.

AGENTS.md

Place an AGENTS.md file in your project root with custom instructions that will be appended to all agent system prompts.

.agents/ Directory

.agents/
├── commands/       # Custom slash commands (filename = command name)
│   └── deploy.md   # Usage: /deploy <args>
└── skills/         # Custom skills/personas
    └── review.md   # Loaded as additional agent instructions

Command files support frontmatter with description and the $INPUT template variable for arguments.

MCP Support (Model Context Protocol)

Aru can load tools from MCP servers. Configure in .aru/mcp_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
    }
  }
}

Agents

Agent	Role	Tools
Planner	Analyzes codebase, creates structured implementation plans	Read-only tools, search, web
Executor	Implements code changes based on plans or instructions	All tools including delegation
General	Handles conversation and simple operations	All tools including delegation

Tools

File Operations

• read_file — Reads files with line range support and binary detection
• read_file_smart — Smart file reading focused on relevant snippets for the query
• write_file / write_files — Writes single or batch files
• edit_file / edit_files — Find-replace edits across multiple files

Search & Discovery

• glob_search — Find files by pattern (respects .gitignore)
• grep_search — Content search with regex and file filtering
• list_directory — Directory listing with gitignore filtering
• rank_files — Multi-factor file relevance ranking (name, structure, recency)

Code Analysis

• code_structure — Extracts classes, functions, imports via tree-sitter AST
• find_dependencies — Analyzes import relationships between files

Shell & Web

• bash — Executes shell commands with permission gates
• web_search — Web search via DuckDuckGo
• web_fetch — Fetches URLs and converts HTML to readable text

Advanced

• delegate_task — Spawns autonomous sub-agents for parallel task execution

Architecture

aru-code/
├── aru/
│   ├── cli.py              # Interactive CLI with streaming display
│   ├── config.py           # Configuration loader (AGENTS.md, .agents/)
│   ├── providers.py        # Multi-provider LLM abstraction
│   ├── agents/
│   │   ├── planner.py      # Planning agent
│   │   └── executor.py     # Execution agent
│   └── tools/
│       ├── codebase.py     # 16 core tools
│       ├── ast_tools.py    # Tree-sitter code analysis
│       ├── ranker.py       # File relevance ranking
│       ├── mcp_client.py   # MCP client
│       └── gitignore.py    # Gitignore-aware filtering
├── aru.json                # Permissions and model configuration
├── .env                    # API keys (not committed)
├── .aru/                   # Local data (sessions)
└── pyproject.toml

Built With

• Agno — Agent framework with tool orchestration
• Anthropic Claude — Sonnet 4.6, Opus 4.6, Haiku 4.5
• tree-sitter — AST-based code analysis
• Rich — Terminal UI
• prompt-toolkit — Advanced input handling

Development

# Clone and install in editable mode with dev dependencies
git clone https://github.com/estevaofon/aru.git
cd aru
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=aru --cov-report=term-missing

---

Built with Claude and Agno