Documentação do Aluy CLI

Instalação

Instale em um comando, como seu usuário, sem sudo. O instalador resolve as dependências e coloca o aluy no PATH; re-rodar atualiza. A instalação vive em ~/.aluy.

Linux · macOS

Windows (PowerShell)

Requisitos: Linux, macOS ou Windows · Node ≥ 20 (o instalador garante) · ~150 MB livres · conexão no primeiro run.

Primeiros passos

No seu primeiro aluy, um assistente abre e pede, nesta ordem, provider, chave e modelo.

• Provider — por padrão, o Aluy cuida da conexão com o modelo e você não configura nada. Ou escolha um provider direto, com a sua credencial. Troque depois com /provider.
• Chave — vai direto pro cofre do SO (Keychain no macOS, libsecret no Linux, Credential Manager no Windows). Nunca em texto, nunca no repo.
• Modelo — escolha o tier com /model; ajuste o esforço de raciocínio com /effort quando precisar.

Então mande a primeira tarefa: abra a sessão, descreva o objetivo (ou use um /comando) e deixe o agente trabalhar. Cada ação que toca seus arquivos pede permissão.

Duas flags definem isso desde o início: aluy --plan roda somente-leitura (analisa e propõe, sem efeito); aluy --yolo deixa rodar sem supervisão, auto-aprovando todo efeito — exceto as categorias sempre-perguntar (exclusão, rede, escalada de privilégio, instalação de pacote), que seguem travadas, e recusa rodar como root. Detalhes na referência de CLI.

Quer ligar memória de longo prazo, mais fôlego de contexto ou modelos locais? Rode aluy bootstrap — veja a seção Sidecars.

Referência de CLI

São os comandos que você roda na sua shell — aluy e seus subcomandos. Rode aluy --help para a lista embutida e aluy --version para imprimir a versão. O padrão (sem subcomando) abre a sessão interativa.

Sinopse

O comando padrão

Rodar aluy sem subcomando abre a sessão TUI interativa no diretório atual. Uma string entre aspas isolada vira o objetivo inicial: aluy "refatore o módulo de auth". O primeiro token sem flag é o objetivo. No primeiríssimo run — quando ainda não há config — o assistente interativo de primeira execução abre automaticamente antes da sessão, passando por idioma, backend, provider e modelo.

Flags de topo

Modo headless / print

Modelo e backend

Limites e segurança

Sessão, retomada e exibição

Subcomandos

Variáveis de ambiente

Várias flags leem uma env var correspondente como fallback: ALUY_TOKEN, ALUY_ORG, ALUY_BACKEND, ALUY_LOCAL_*, ALUY_MAX_TOKENS, ALUY_BUDGET, ALUY_AUTOCOMPACT_AT, ALUY_SAFE_GLYPHS. NO_COLOR desliga a saída colorida.

Comandos slash

Dentro de uma sessão em execução, digite / no início da linha para abrir o menu — filtre enquanto digita, e Tab/Enter completa. São comandos que você dá, não tools que o agente invoca. Uma visão compacta e agrupada está na página Comandos.

Conta e sessão

Workspace, projeto e config

Autonomia e multi-agente

Estrutura .aluy/

O Aluy mantém duas casas: uma global em ~/.aluy/ (instalação, config, sidecars, memória entre projetos) e uma de projeto — o arquivo de instrução na raiz do repo mais uma pasta .aluy/ opcional. Tudo sob ~/.aluy/ é o kernel-cliente confinado: as próprias regras de path-deny do agente o proíbem de ler, editar ou rodar qualquer coisa ali.

Projeto: o arquivo de instrução

O arquivo de instrução nativo do projeto é o ALUY.md na raiz do repo — o que o /init cria. O Aluy lê vários nomes de arquivo como instruções de projeto, nesta precedência, compondo todos os presentes:

A precedência é ALUY.md › AGENT.md › AGENTS.md › CLAUDE.md. São lidos uma vez na largada e injetados no system prompt, cada um sob um cabeçalho marcando a origem. Symlinks que escapam da raiz do projeto são rejeitados e nada é lido.

Projeto: a pasta .aluy/

Global: ~/.aluy/

Artefatos — construindo os arquivos .aluy/

A pasta .aluy/ é onde você ensina um projeto. Cada arquivo é Markdown puro, lido uma vez a partir da raiz confinada do workspace — um symlink que escapa da raiz é rejeitado e nada é lido. Os mesmos arquivos também são descobertos sob .claude/ (compat Claude Code); em colisão de nome, .claude/ vence. Abaixo, cada arquivo: o que é, onde fica, o formato exato e um exemplo mínimo.

ALUY.md — instruções do projeto

Fica na raiz do repo (não dentro de .aluy/). É o arquivo de instrução do projeto — comandos de build/test, convenções, o objetivo — injetado no system prompt na largada. ALUY.md é o nome nativo (o que o /init escreve). Outros três nomes são lidos como compat, nesta precedência, compondo todos os presentes:

Precedência: ALUY.md › AGENT.md › AGENTS.md › CLAUDE.md. Sem frontmatter — o arquivo inteiro é o texto de instrução. Um teto de tamanho corta arquivos gigantes antes de injetar.

agents/*.md — perfis de sub-agente

Um .md por sub-agente nomeado em .aluy/agents/ (lido plano, sem recursão). Frontmatter YAML-mínimo (um chave: valor por linha) define o agente; o corpo é o system prompt.

• name — a identidade que /subagent <nome> invoca (normalizada para [a-z0-9_-]). Obrigatório.
• description — o que ele faz. Opcional.
• tools — lista por vírgula (ou [a, b]) que restringe o toolset (⊆ pai). Omita para herdar as tools do pai. Nomes do Claude Code (Read, Bash) são aceitos e mapeados. Presente-porém-vazio é erro de carga (nunca "herda tudo").
• model — preferência de tier (ex.: sonnet), resolvida no broker. Opcional.

commands/*.md — comandos slash custom

Um .md por comando em .aluy/commands/. O nome do arquivo é o nome do comando — deploy.md vira /deploy. O corpo é um template de prompt submetido como seu objetivo; o frontmatter opcional summary alimenta o menu. Placeholders: $ARGUMENTS (a string inteira de args) e $1, $2, … (posicionais). Sem placeholder, os args são anexados.

skills/<nome>/SKILL.md — capacidades empacotadas

Uma skill é um diretório sob .aluy/skills/ com um manifesto SKILL.md (mais recursos auxiliares ao lado). O corpo é injetado sob demanda quando você invoca a skill por nome. Frontmatter name (cai para o nome do diretório) e description opcional; o corpo são as instruções e não pode ser vazio.

workflows/*.md — fluxos de atividades

Um .md por workflow em .aluy/workflows/. Frontmatter name (obrigatório) e description opcional; o corpo é uma lista numerada de atividades. Cada linha é N. <id> [<agente>] — <objetivo>, onde o [<agente>] é opcional e o separador é — ou -. Pelo menos uma atividade é exigida.

memory/project.md — memória do projeto

A memória do agente com escopo de projeto fica em .aluy/memory/project.md (dentro do workspace; a contraparte global é ~/.aluy/memory/global.md). Você não curadora ela à mão como os arquivos acima — o agente lembra fatos sozinho, e você dá o leme de dentro da sessão com /memory: /memory para listar, /memory forget <id>, /memory edit <id> …, /memory pin <id> / unpin. A memória é sempre relembrada como dado, nunca como instrução — fixar é só retenção.

/cycle — roda até terminar

Com o /cycle, você descreve a tarefa e o agente trabalha em ciclos por conta própria até terminar — sem babá. É o "dispare e vá fazer outra coisa".

Vem com um freio de mão: tetos duros de tempo e de passos, e parada automática se algo sair do trilho. O anti-runaway — nada de robô fugindo do controle.

• Bom para: consertar testes, varreduras em massa, migrações repetitivas, tarefas longas com um critério claro de "pronto".
• Todo efeito que toca seus arquivos ainda passa pela trava de permissão.

Subagentes

Cada subagente é um perfil (arquivo .md) com o seu próprio foco. Você pede o especialista e o próprio agente cria o subagente para você — descreva o que precisa ("um revisor de segurança", "um QA de E2E") e ele gera o perfil com o papel, o tom e os limites. Você não escreve o .md na mão (mas pode editar ou criar um se quiser).

Eles trabalham em paralelo, sem misturar contextos: cada subagente tem sua própria sub-sessão dedicada. Uma frota, não um agente sozinho.

Salas

As salas (/rooms) colocam vários agentes conversando entre si sobre o mesmo problema — debatendo, dividindo e combinando o trabalho. Você acompanha a conversa em tempo real e entra quando fizer sentido.

MCP — conecte ferramentas

Pelo MCP (o padrão aberto de conectores), o agente fala com ferramentas e integrações externas — bancos, APIs, serviços. É o que dá ao agente acesso real ao que você já usa, não só conversa.

Compatibilidade — Codex e Claude Code

Já usa Codex ou Claude Code? O Aluy entende a sua estrutura. Sem reconfig. Aponte o Aluy para o seu projeto e ele lê os mesmos arquivos de instrução e configuração que você já mantém.

Arquivos de instrução do projeto

• ALUY.md — o arquivo nativo do Aluy (o que o /init escreve).
• AGENT.md — alias de compat (nome anterior/genérico de agente).
• AGENTS.md — o mesmo arquivo que o Codex (OpenAI) usa.
• CLAUDE.md — o mesmo arquivo que o Claude Code usa.

A precedência é ALUY.md › AGENT.md › AGENTS.md › CLAUDE.md — todos os presentes compõem juntos.

Paridade de estrutura

• Agentes .md aceitam os nomes de ferramentas do Claude Code — mapeados para os nativos.
• Hooks no formato settings.json do Claude Code, e comandos de usuário em .md.
• /rewind + checkpoints, com paridade ao Claude Code.

Sidecars

Sidecars são reforços locais opcionais que rodam na sua máquina (escutando só em 127.0.0.1) para dar ao agente memória de longo prazo, mais fôlego de contexto e modelos locais. O Aluy funciona sem eles — só perde esses recursos. Nada quebra. Ligue com aluy bootstrap.

Modo turbo

Três complementos opcionais que rodam na sua máquina — memória de longo prazo, folga de contexto e modelos locais. Você liga com aluy bootstrap; o agente funciona sem eles. O que são, como instalar, o que pode dar errado e como resolver. (O perfil oposto, leve, não instala nenhum.)

O que o turbo liga

Os três escutam só em 127.0.0.1 e são opt-in — nada sobe sem você aceitar. Eles sobem no boot se já instalados; instalar é o passo explícito aluy bootstrap.

• mem0 · :11435 — memória persistente: o agente guarda fatos e preferências e os relembra na próxima sessão. Você vê, fixa ou esquece com /memory.
• headroom · :8787 — compressão de contexto: condensa o que já passou e traz de volta só o que importa, mantendo a janela do modelo sob controle.
• ollama · :11434 — runtime de modelos locais: um judge pequeno (qwen2.5:0.5b) e um embedder (nomic-embed-text) para tarefas internas que nunca saem da máquina.

Dois caminhos para provisionar

Depois de npm i -g @hiperplano/aluy-cli e aluy onboard, rode um destes:

• Via agente (padrão) — o aluy detecta o SO, instala os pré-requisitos que faltam (Python, pip, venv, com sudo quando preciso) e os complementos, tratando os problemas no caminho. Roda em --yolo — optar pelo turbo é o consentimento.
• Direto (--no-agent) — caminho determinístico: artefato pinado do Ollama + criação dos venvs, sem usar modelo. Requer Python já pronto.

Quando algo cai, o agente conserta

Na TUI, o /doctor mostra o diagnóstico ao vivo. Se um complemento está fora, ele pergunta — e o /doctor fix entrega o conserto ao próprio agente: ele lê os ~/.aluy/logs/*.log, roda o bootstrap, instala o que falta e re-tenta até os três ficarem verdes.

Sintomas e conserto

Os logs de cada sidecar (truncados por boot) ficam em ~/.aluy/logs/ollama.log, mem0.log, headroom.log — o primeiro lugar a olhar.

• mem0 ✗ · log can't open file '…aluy-mem0-server.py' — falta o script do servidor no venv. Rode aluy bootstrap (copia o script). Em rc ≥ 33 o boot também o copia ao abrir.
• mem0 ✗ · log KeyError: '_type' / no such column — store de versão anterior. mv ~/.aluy/memory{,.bak}; mv ~/.mem0/history.db{,.bak} e reabra. Em rc ≥ 29 o servidor se auto-cura.
• ollama ✓ mas ollama list → command not found — serviço sobe em :11434 mas o binário não está no PATH. rc ≥ 30 cria symlink em ~/.local/bin; ou abra um shell novo.
• bootstrap trava em verificando ollama + erro de broker — instalação via agente sem modelo acessível. Use aluy bootstrap --no-agent (rc ≥ 35 cai nisso sozinho).
• headroom ✗ · log No module named 'fastapi' — o venv instalou headroom-ai sem o extra [proxy]. ~/.aluy/hr-venv/bin/pip install 'headroom-ai[proxy]==0.25.0'. Corrigido na fonte em rc ≥ 36.
• os três ✗ numa máquina nova — nada provisionado ainda. aluy bootstrap --no-agent.

Provisionar à mão

Se preferir montar você mesmo (ou entender o que o bootstrap faz). Tudo mora em ~/.aluy/.

Arquitetura

Por baixo dos panos, o Aluy CLI é um único processo no seu terminal — entrega monolítica, sem servidor escondido. A interface (a TUI) fala com o core, o motor que lê e edita arquivos, roda comandos e decide os próximos passos. Entre o agente e o seu projeto fica a trava de permissão: o único ponto por onde todo efeito passa antes de acontecer.

O estado vive na sua máquina: a memória da sessão (e a de longo prazo via mem0), sua chave no cofre do SO, seus arquivos e sua shell. Sidecars são reforços locais opcionais que escutam só em 127.0.0.1.

• As únicas coisas que cruzam a borda são a chamada ao modelo e os conectores MCP que você liga.
• Sessão, histórico, arquivos, memória e sua chave nunca saem do seu computador.

Memória

O agente lembra decisões e contexto do projeto de uma conversa para a outra — fatos globais e por projeto. Você controla tudo com /memory: veja o que ele guardou, fixe o que importa e esqueça o que não serve mais.

• A memória de longo prazo depende do sidecar mem0; sem ele, só vale a memória da sessão atual.
• /clear memory apaga tudo o que o agente guardou (pede confirmação).

Temas

A sessão vem em três temas — light, dark e slate — para você deixar do jeito que gosta de olhar o dia todo. Troque com /theme aluy-dark | aluy-light | aluy-slate; a sua escolha é salva.

Os temas vêm dos tokens do Aluy Design System: cor, tipografia e densidade saem de variáveis, nunca de estilo cru.

Doctor

/doctor é o diagnóstico somente-leitura da sua instalação: checa modelo, chave, conexão, MCP e config — e aponta uma dica de conserto quando algo está fora do lugar. Não muda nada, só lê.

FAQ

Meus dados vão para a nuvem?

Não. A sessão, o histórico, os arquivos do projeto e a memória ficam na sua máquina. A única coisa que cruza a borda é a chamada ao modelo.

Onde mora a minha chave?

No cofre do SO (Keychain, libsecret, Credential Manager) — nunca em texto, nunca no repo. O Aluy mostra o tier do modelo, nunca a credencial.

Como o Aluy fala com o modelo?

Por padrão, o Aluy cuida da conexão com o modelo — você não configura nada. Se preferir, ligue o seu próprio provider direto, com a sua credencial (API key ou OAuth): é o seu uso, sob o seu controle.

Tem custo?

O Aluy CLI é código aberto, sob MIT. No modo direto, o uso do modelo corre pela sua própria conta no provider. Os sidecars rodam localmente, sem custo de API.

É seguro deixar o /cycle rodando sozinho?

O /cycle tem tetos duros de tempo e de passos, e parada automática. E toda ação que toca seus arquivos passa por uma trava de permissão.

Posso ler e modificar o código?

Sim — é código aberto sob MIT. Leia, audite, abra issues e faça fork. O que age na sua máquina, você merece poder inspecionar. O Aluy está em beta; espere arestas e iteração rápida.