Pular para conteúdo

Aru

Aru é um assistente de programação inteligente que roda no terminal. Você descreve a tarefa em linguagem natural e agentes especializados planejam, exploram o código e aplicam mudanças — com suporte a múltiplos providers (Anthropic, OpenAI, Ollama, Groq, OpenRouter, DeepSeek e outros).

Aru demo

Destaques

  • Arquitetura Multi-Agente (catalog-driven)

    Agentes nativos (build, plan, executor, explorer) declarados como specs em aru/agents/catalog.py e instanciados por um factory único.

  • CLI Interativo

    REPL com respostas em streaming, suporte a multi-linha, histórico de sessões e mentions de arquivos com @.

  • 17 Ferramentas Integradas

    I/O de arquivos (single + batch), busca, shell, web, delegação a subagentes e tracking estruturado de planos/subtarefas.

  • Multi-Provider

    Anthropic, OpenAI, Ollama, Groq, OpenRouter, DeepSeek e outros providers customizados via aru.json.

  • Suporte a Imagens

    Anexe imagens com @arquivo.png para análise multimodal (Claude, GPT-4o, Gemini).

  • Extensível

    Comandos, skills, agentes, ferramentas Python e plugins com hooks compatíveis com OpenCode.

Instalação

pip install aru-code

Configure sua chave da Anthropic em um .env:

ANTHROPIC_API_KEY=sk-ant-sua-chave-aqui

E execute:

aru

Pronto. Veja o Início Rápido para mais detalhes.

Como funciona

main.py → cli.run_cli() → REPL
                           ├─ build      (conversa + ferramentas, self-triggers plan mode)
                           ├─ plan       (read-only, gera plano em Markdown)
                           ├─ executor   (executa plano passo a passo)
                           └─ explorer   (subagent read-only, via delegate_task)

Os specs dos agentes nativos vivem em aru/agents/catalog.py e são instanciados pelo agent_factory. O agente build resolve tarefas diretas e, quando detecta uma tarefa que exige 3+ mudanças coordenadas, chama enter_plan_mode(task) sozinho — o plan gera o plano, que é armazenado na sessão e reaparece a cada turno como um lembrete PLAN ACTIVE. Você também pode forçar o fluxo manualmente com /plan <tarefa>.

Configuração

A configuração é o coração do Aru. É nela que você define qual modelo usar, quais providers conectar, o que cada ferramenta pode fazer e quais regras o agente deve seguir. O Aru lê dois níveis de configuração, com o projeto sobrescrevendo o global via merge profundo:

Nível Caminho Propósito
Global ~/.aru/config.json Padrões para todos os projetos (modelo, aliases, permissões, providers)
Projeto aru.json ou .aru/config.json Overrides específicos do projeto (modelo, permissões, MCP, plugins)

Exemplo mínimo de aru.json

{
  "default_model": "anthropic/claude-sonnet-4-6",
  "model_aliases": {
    "sonnet": "anthropic/claude-sonnet-4-6",
    "opus": "anthropic/claude-opus-4-6"
  },
  "permission": {
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "write": "ask",
    "bash": { "pytest *": "allow", "rm *": "deny" }
  },
  "instructions": ["AGENTS.md"],
  "plugins": ["./plugins/meu_plugin.py"]
}

Campos principais

Campo Descrição
default_model Modelo padrão no formato provider/model
model_aliases Atalhos para /model <alias>
providers Providers customizados (tokens, endpoints, headers)
permission Regras granulares allow/ask/deny por ferramenta e padrão
instructions Arquivos ou URLs anexados ao system prompt (ex: AGENTS.md)
mcp Servidores Model Context Protocol a conectar
plugins Lista explícita de plugins a carregar
agent Overrides por agente customizado (modelo, prompt, ferramentas)

Áreas de configuração

  • Visão Geral

    Como os arquivos ~/.aru/config.json e aru.json são carregados, mesclados e aplicados em runtime. Ponto de partida para entender toda a configuração.

    Visão geral

  • Modelos e Providers

    Configure Anthropic, OpenAI, Ollama, Groq, OpenRouter, DeepSeek ou providers OpenAI-compatíveis customizados. Aliases, tokens e endpoints.

    Modelos e Providers

  • Permissões

    Sistema granular allow / ask / deny por ferramenta, com regras por padrão (ex: bash: { "pytest *": "allow" }). Controle fino do que o agente pode executar.

    Permissões

  • Regras (AGENTS.md)

    Instruções de projeto anexadas automaticamente ao system prompt. Use para convenções de código, arquitetura, padrões de commit e contexto do repositório.

    AGENTS.md

  • MCP Servers

    Integre servidores Model Context Protocol (GitHub, Slack, Postgres, filesystem…) declarados no aru.json para expor ferramentas externas ao Aru.

    MCP Servers

  • Overrides por Agente

    Use o campo agent para trocar modelo, prompt ou conjunto de ferramentas de um sub-agente específico sem afetar o agente geral.

    Agentes customizados

Extensibilidade

Aru foi projetado para ser extensível em todas as camadas. Cada tipo de extensão tem sua própria seção na documentação:

  • Skills

    Capacidades plugáveis carregadas sob demanda a partir de .aru/skills/. Defina prompts, ferramentas permitidas e arquivos auxiliares em uma pasta por skill.

    Ver Skills

  • MCP Servers

    Conecte servidores Model Context Protocol para expor ferramentas externas (GitHub, Slack, bancos de dados) ao Aru via aru.json.

    Configurar MCP

  • Tools Integradas

    17 ferramentas nativas cobrindo leitura/edição (single + batch), busca, shell, web, delegação, plano autônomo (enter_plan_mode) e tracking de subtarefas.

    Ferramentas integradas

  • Tools Customizadas

    Crie suas próprias ferramentas em Python e registre-as no Aru. Ideal para integrar APIs internas, automações específicas do projeto ou fluxos proprietários.

    Ferramentas customizadas

  • Custom Agents

    Crie sub-agentes especializados com prompt, modelo e conjunto de ferramentas próprios. Delegue tarefas isoladas sem poluir o contexto do agente principal.

    Agentes customizados

  • Plugins

    Sistema de hooks compatível com OpenCode para interceptar eventos do ciclo de vida (tool calls, mensagens, sessões) e estender o comportamento do Aru.

    Sistema de Plugins · Hooks

Próximos passos