Metadata-Version: 2.4
Name: aru-code
Version: 0.2.0
Summary: A Claude Code clone built with Agno agents
Author-email: Estevao <estevaofon@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/estevaofon/aru
Project-URL: Repository, https://github.com/estevaofon/aru
Project-URL: Issues, https://github.com/estevaofon/aru/issues
Keywords: ai,coding-assistant,claude,cli,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agno<3,>=2.5.10
Requires-Dist: anthropic
Requires-Dist: httpx
Requires-Dist: pathspec>=0.12
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: rich
Requires-Dist: tree-sitter>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: mcp>=1.0
Requires-Dist: openai>=2.29.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: ollama
Requires-Dist: ollama>=0.4; extra == "ollama"
Provides-Extra: groq
Requires-Dist: groq>=0.4; extra == "groq"
Provides-Extra: all-providers
Requires-Dist: openai>=1.0; extra == "all-providers"
Requires-Dist: ollama>=0.4; extra == "all-providers"
Requires-Dist: groq>=0.4; extra == "all-providers"
Dynamic: license-file

# aru

An intelligent coding assistant for the terminal, powered by LLMs and [Agno](https://github.com/agno-agi/agno) agents.
</br></br>
<img width="600" alt="image" src="https://github.com/user-attachments/assets/36001faa-3163-4374-84fd-da8704a4ed9d" />



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

```bash
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](https://console.anthropic.com/) to get started.

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

```env
ANTHROPIC_API_KEY=sk-ant-your-key-here
```

> Using another provider? See the [Models and Providers](#models-and-providers) section to configure OpenAI, Ollama, Groq, etc.

### 3. Run

```bash
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

```bash
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:

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

#### Ollama (local models)

To run models locally without an API key, install [Ollama](https://ollama.com/), start the server, and use any installed model:

```bash
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:

```json
{
  "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:

```json
{
  "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**:

```json
{
  "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`:

```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](https://github.com/agno-agi/agno)** — Agent framework with tool orchestration
- **[Anthropic Claude](https://www.anthropic.com/)** — Sonnet 4.6, Opus 4.6, Haiku 4.5
- **[tree-sitter](https://tree-sitter.github.io/)** — AST-based code analysis
- **[Rich](https://rich.readthedocs.io/)** — Terminal UI
- **[prompt-toolkit](https://python-prompt-toolkit.readthedocs.io/)** — Advanced input handling

## Development

```bash
# 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
