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, a lista de pastas onde o seu terminal procura programas; 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 · internet na primeira vez.

Primeiros passos

Entre na pasta de um projeto e rode aluy. Na primeira vez, antes da sessão abrir, um assistente faz três perguntas.

• Qual provider. É quem vai atender as chamadas ao modelo — Anthropic, OpenAI, OpenRouter ou um modelo que roda na sua máquina. Dá para trocar depois com /provider.
• Sua chave. Você cola a chave daquele provider uma vez. Ela vai para o cofre de credenciais do seu sistema — Keychain no macOS, libsecret no Linux, Credential Manager no Windows. Numa máquina sem cofre, vai para um arquivo cifrado. Nos dois casos: nunca em texto, nunca no repositório, e o Aluy não mostra ela de volta na tela.
• Qual modelo. Você escolhe o tier, que é a faixa de modelo que a sessão vai usar. Troque depois com /model, e ajuste o esforço de raciocínio com /effort.

Respondidas as três, a sessão abre. A partir daí você escreve o objetivo em português mesmo, e o agente trabalha.

Três comandos para o começo

Dentro da sessão, tudo que começa com barra é um comando seu, não um pedido ao modelo. Estes três resolvem os primeiros minutos.

O /init vale o minuto que leva. Ele escreve um ALUY.md na raiz do projeto com os comandos de build e de teste e as convenções da casa. É o que faz o agente parar de chutar como o seu projeto funciona.

Quem autoriza o quê

O agente lê arquivos à vontade. Para mudar alguma coisa — escrever num arquivo, rodar um comando no shell — ele para e pergunta. Essa parada é a catraca de permissão, e todo efeito passa por ela.

Você responde a para aprovar uma vez, s para aprovar sempre aquele tipo de ação nesta sessão, ou n para negar.

Se você quer só uma análise, sem mudar nada, abra a sessão em modo planejamento: aluy --plan. Nesse modo o agente lê, pensa e propõe, e não consegue produzir efeito nenhum — nem se você aprovar.

Quer memória de longo prazo, conversas longas sem perder o fio, ou modelos locais? Isso é o modo turbo, e liga com um comando só.

A linha de comando

Estes são os comandos que você digita no seu shell, fora da sessão. Rodar aluy sozinho abre a sessão interativa na pasta atual; tudo o mais é subcomando ou flag.

Como se lê uma linha de comando

Uma linha do aluy tem três partes, e só a primeira é obrigatória.

• O comando. Se a primeira palavra for um subcomando conhecido — login, doctor, mcp —, é ele que roda. Se não for, o Aluy abre a sessão.
• O objetivo. É a primeira palavra que não começa com -. Um texto entre aspas vira o objetivo inicial da sessão: aluy "refatore o módulo de autenticação".
• As flags. Vêm em qualquer ordem, depois do objetivo. Quase toda flag tem uma variável de ambiente equivalente, usada quando você omite a flag.

Na primeiríssima vez, quando ainda não existe configuração, o assistente de primeira execução abre sozinho antes da sessão e passa por idioma, modo de conexão, provider e modelo.

Os quatro que você vai mesmo usar

O resto você procura quando precisar.

Modo planejamento e modo yolo

Duas flags mudam quem autoriza o quê, e vale conhecer as duas antes de qualquer outra.

aluy --plan abre em modo planejamento: o agente lê, analisa e propõe, e não produz efeito nenhum.

aluy --yolo faz o contrário: aprova todo efeito sozinho. Mesmo nele, cinco categorias de comando continuam perguntando — apagar coisas, acessar a rede, virar administrador, instalar pacote e mexer nos arquivos que rodam quando o computador liga — e toda ferramenta de servidor MCP também. O Aluy recusa rodar como root. Se você passar as duas juntas, o --plan vence.

Como o modelo é alcançado

Por padrão o CLI fala direto com o seu provider, com a sua credencial — ninguém no meio, e ninguém contando quanto você usou. É o que a flag --backend local diz, e é o valor de fábrica.

Existe também um backend central (--backend broker), que rotearia a chamada por um servidor da Aluy. Ele hoje não está disponível.

Comandos da sessão

Com a sessão aberta, digite / no começo da linha e o menu abre. Filtre digitando; Tab ou Enter completa. Ctrl+P abre a mesma lista como paleta de comandos.

Estes são comandos seus. Eles não passam pelo modelo: você manda, o Aluy executa. É diferente das ferramentas, que são o que o agente usa por conta própria enquanto trabalha.

Os primeiros que valem a pena

• /doctor — o diagnóstico da instalação. Quando alguma coisa não funciona, comece por ele.
• /init — lê o repositório e escreve o ALUY.md. Você confere o diff antes de aceitar.
• /undo e /rewind — desfazem a última edição do agente, ou voltam a um ponto anterior da sessão.
• /compact — resume a conversa quando a janela de contexto aperta.
• /permissions — mostra o que está liberado e o que continua perguntando.

São mais de quarenta ao todo, agrupados por tarefa: trabalho, multi-agente, ferramentas, sessão e configuração. Dentro da sessão, /help lista a versão ao vivo.

Estrutura .aluy/

O Aluy mantém duas casas: uma global em ~/.aluy/ (instalação, configuração, sidecars, memória entre projetos) e uma de projeto — o arquivo de instrução na raiz do repositório mais uma pasta .aluy/ opcional. A pasta ~/.aluy/ é a casa do próprio Aluy, e o agente não entra nela: não lê, não edita e não roda nada lá dentro, mesmo que você peça. A exceção é o --yolo, que alcança essa pasta — uma decisão deliberada daquele modo, explicada na arquitetura.

Projeto: o arquivo de instrução

O arquivo de instrução nativo do projeto é o ALUY.md na raiz do repositório — o que o /init cria. O Aluy lê vários nomes de arquivo como instrução de projeto. Se houver mais de um, ele junta todos, nesta ordem de prioridade:

A precedência é ALUY.md › AGENTS.md › CLAUDE.md. Os três são lidos uma vez, quando a sessão abre, e entram na instrução permanente do agente, cada um sob um cabeçalho que diz de onde veio. A leitura é confinada à raiz do projeto: um atalho que aponta para fora dela é recusado, e nada é lido.

Projeto: a pasta .aluy/

Global: ~/.aluy/

Artefatos — os arquivos do projeto

Você não precisa de nenhum destes arquivos para usar o Aluy. Eles existem para quando você quer que o agente se comporte de um jeito específico neste projeto, e que esse jeito fique versionado junto com o código.

Cada um é Markdown puro. Comece pelo ALUY.md, que o /init escreve para você; os outros só valem a pena quando você sentir falta.

ALUY.md — as instruções do projeto

Fica na raiz do repositório, não dentro do .aluy/. É onde moram os comandos de build e de teste, as convenções da casa e o que o agente nunca deve tocar. O Aluy lê esse arquivo uma vez, quando a sessão abre.

O arquivo inteiro é a instrução — não há cabeçalho de configuração, não há campos. Escreva como você escreveria para uma pessoa nova no time. Arquivos muito grandes são cortados antes de entrar.

O Aluy também lê AGENTS.md e CLAUDE.md, por compatibilidade, e junta todos os que existirem. Veja a precedência completa.

agents/*.md — perfis de subagente

Um arquivo por subagente, em .aluy/agents/. Crie um quando quiser um especialista com foco estreito — um revisor que só lê diffs, um QA que só escreve teste — em vez do agente generalista.

O cabeçalho de configuração — o bloco entre --- no topo do arquivo, que a documentação de outras ferramentas chama de frontmatter — define quem ele é; o corpo do arquivo é a instrução permanente dele.

• name — o nome que /subagent <nome> chama. Obrigatório. Aceita letras minúsculas, números, hífen e sublinhado.
• description — o que ele faz. Opcional, mas ajuda você a lembrar depois.
• tools — a lista de ferramentas que ele pode usar, separada por vírgula. Ela só restringe: um subagente nunca ganha ferramenta que o agente principal não tenha. Omita a chave para ele herdar tudo. Se a chave existir mas estiver vazia, o perfil falha ao carregar — vazio nunca quer dizer "herda tudo".
• model — o tier preferido, por exemplo sonnet; o Aluy encontra o modelo correspondente no catálogo do seu provider. Opcional.

Nomes de ferramenta do Claude Code, como Read e Bash, são aceitos e convertidos para os nativos.

commands/*.md — seus próprios comandos

Um arquivo por comando, em .aluy/commands/. Crie um quando você se pegar digitando o mesmo pedido pela terceira vez.

O nome do arquivo vira o nome do comando: deploy.md vira /deploy. O corpo é o texto que será enviado como se você tivesse digitado. O campo opcional summary é o que aparece no menu.

Para receber argumentos, use $ARGUMENTS para tudo que veio depois do comando, ou $1, $2 e assim por diante para pegar um de cada vez. Se você não usar nenhum deles, os argumentos vão para o fim do texto.

skills/<nome>/SKILL.md — instruções com material junto

Uma skill é uma pasta, não um arquivo. Ela existe para quando as instruções vêm acompanhadas de material — um gabarito, uma tabela, um exemplo — que você quer guardar junto.

O SKILL.md é a ficha da skill: o cabeçalho de configuração traz name (que assume o nome da pasta se você omitir) e description opcional, e o corpo com as instruções, que não pode ficar vazio. O corpo só entra no contexto quando você chama a skill pelo nome — não pesa nas outras conversas.

workflows/*.md — sequências de atividades

Um arquivo por workflow, em .aluy/workflows/. Use quando a tarefa tem etapas fixas e você quer que cada uma caia no especialista certo.

O cabeçalho de configuração pede name (obrigatório) e aceita description. O corpo é uma lista numerada, no formato N. <id> [<agente>] — <objetivo>. O agente entre colchetes é opcional; sem ele, a etapa roda no agente principal. Pelo menos uma etapa é obrigatória.

memory/project.md — a memória do projeto

Este é o único da lista que você não escreve. Quem escreve é o agente: ele guarda fatos sobre o projeto conforme trabalha, em .aluy/memory/project.md, e fatos que valem para tudo em ~/.aluy/memory/global.md.

Você conduz de dentro da sessão, com /memory: sem argumento ele lista o que o agente guardou; forget, edit, pin e unpin apagam, corrigem e fixam um fato pelo id.

A memória volta para o agente sempre como dado, nunca como instrução. Fixar um fato garante que ele não seja esquecido; não transforma o fato em ordem.

Como esses arquivos são lidos

O Aluy também procura os mesmos arquivos em .claude/, para quem já mantém um projeto com o Claude Code. Se o mesmo nome existir nos dois lugares, o de .claude/ vence.

A leitura é confinada à raiz do projeto: um atalho que aponta para fora dela é recusado, e nada é lido.

/cycle — roda até terminar

Com o /cycle, você descreve a tarefa e o agente trabalha em ciclos por conta própria até terminar. Você manda e vai cuidar de outra coisa.

Ele tem tetos de tempo e de passos, e para sozinho se algo sair do trilho. É o que impede o agente de rodar sem fim.

• 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 continua passando pela catraca 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 testes ponta a ponta") 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. Com isso ele consulta e altera essas ferramentas de verdade, em vez de só falar sobre elas.

Telegram — o agente no seu celular

Conecte um bot e o agente te alcança fora do terminal: ele reporta quando termina, pergunta quando precisa de uma decisão sua e avisa quando pausa. Você responde do celular e ele segue.

• Só os seus chats. Nenhum vem liberado: allow e deny montam a lista dos autorizados. Mensagem de qualquer outro chat o agente lê como texto solto, nunca como ordem a cumprir.
• O token fica no cofre, nunca num arquivo. O aluy telegram logout apaga.
• O destino não é escolha do modelo. A ferramenta de envio sempre responde no chat corrente, então uma mensagem injetada não consegue redirecionar a resposta.
• Cada mensagem que chega é separada em três: ordem sua, informação, ou lixo a ignorar. Na saída há um limite de quantas mensagens ele manda por minuto, e uma trava para ele não ficar conversando com outro robô sem parar.
• Num serviço, é por aqui que uma pergunta pendente espera por você — o campo channel: da ficha do serviço.

O /telegram faz o mesmo de dentro da sessão.

Serviços — um agente com rotina

Um serviço é um agente que trabalha sem você: acorda na hora marcada, trabalha até o limite de gasto que você deu, reporta no seu canal e volta a dormir. Ele é um diretório em ~/.aluy/services/<nome>/, e o service.md é a ficha que diz o que ele pode.

• service.md — schedule (cron), until (fim do expediente), workflow, channel, budget, autonomy, model e group. O que é teto duro é aplicado por código, nunca pedido ao modelo.
• Mundo próprio — agents/, skills/, commands/, rules.md, mcp.json e daemons/ ficam dentro do diretório do serviço, e o turno só enxerga o que está ali.
• Instalar é explícito — o install copia um diretório ou clona um repositório, mostra por inteiro o que aquele serviço traz (processos em segundo plano, scripts, servidores MCP, canal, autonomia) e pergunta. Criar não é ligar.
• attach — entra no serviço rodando, mostra o que ele está fazendo, aceita uma linha sua como instrução, e o Ctrl-C sai sem parar o serviço.
• group — start --group e stop --group ligam e desligam um conjunto inteiro de serviços de uma vez, cada um no seu processo.

Use o /service de dentro da sessão. Os mesmos comandos existem no shell, para quando você quiser chamá-los de um script.

Compatibilidade — Codex e Claude Code

Se você já usa o Codex ou o Claude Code, não precisa reconfigurar nada. 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).
• AGENTS.md — o mesmo arquivo que o Codex (OpenAI) usa.
• CLAUDE.md — o mesmo arquivo que o Claude Code usa.

Todos os que existirem são lidos, e o Aluy junta o conteúdo dos três. Veja a ordem de prioridade.

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.

Modo turbo

O Aluy funciona sozinho, sem instalar mais nada. O modo turbo acrescenta três serviços que rodam na sua própria máquina e dão ao agente memória de longo prazo, conversas longas sem perder o fio, e modelos locais.

Você liga com um comando. Se preferir não ligar, escolha o perfil leve, que não instala nenhum deles — e o agente continua fazendo tudo o que faz hoje, sem esses três recursos.

O que o turbo instala

Os três são o que chamamos de sidecars: programas auxiliares que rodam ao lado do agente e só aceitam conversa vinda da sua própria máquina — nada deles fica acessível pela rede. Nada sobe sem você aceitar.

• mem0, na porta 11435 — a memória que atravessa sessões. O agente guarda fatos e preferências e os relembra na próxima conversa. Você vê, fixa ou esquece com /memory.
• headroom, na porta 8787 — é ele que deixa a conversa ficar longa sem perder o fio: condensa o que já passou e traz de volta só o que importa, mantendo a janela do modelo sob controle.
• ollama, na porta 11434 — o serviço que roda modelos na sua máquina. O turbo usa dois deles em tarefas internas: um modelo pequeno que avalia respostas (qwen2.5:0.5b) e um que transforma texto em números, para o agente achar o que é parecido com o quê (nomic-embed-text). Nenhuma dessas chamadas sai do seu computador.

Depois de instalados, os três sobem sozinhos quando você abre a sessão. Instalar é o passo explícito abaixo.

Dois caminhos para instalar

Rode um destes, depois do aluy onboard.

Pelo agente é o padrão e o que funciona em mais máquinas. O Aluy identifica o seu sistema, instala o que falta (Python, pip, venv — pedindo sudo só nos passos que exigem) e resolve os problemas no caminho. Ele roda em --yolo durante a instalação; escolher o turbo é o seu consentimento.

Direto (--no-agent) segue um roteiro fixo: baixa uma versão fixada do Ollama e cria os ambientes virtuais, sem consultar modelo nenhum. Exige Python já instalado.

Quando algo cai

Na sessão, o /doctor mostra o estado dos três. Se um estiver fora, ele pergunta se você quer consertar.

O /doctor fix entrega o conserto ao próprio agente. Ele lê os arquivos em ~/.aluy/logs/, roda o bootstrap, instala o que falta e tenta de novo até os três aparecerem com ✓.

Se preferir olhar você mesmo, os logs de cada sidecar são ~/.aluy/logs/ollama.log, mem0.log e headroom.log. Eles são truncados a cada abertura, então mostram sempre a tentativa mais recente.

O sintoma mais comum numa máquina nova é o mais simples: os três aparecem com ✗ porque ainda não foram instalados. Rode aluy bootstrap --no-agent.

Instalar à mão

Se você prefere montar você mesmo, ou só quer ver o que o bootstrap faz, é isto. Tudo mora em ~/.aluy/.

Terminado, o aluy doctor deve mostrar os três verdes. Para ver o que está em vigor — perfil, o que está ligado e de onde vem cada valor —, rode aluy config.

Arquitetura

Por baixo dos panos, o Aluy CLI é um único processo no seu terminal — um programa só, sem nenhum servidor escondido por trás. A tela que você vê fala com o miolo, que é quem lê e edita arquivos, roda comandos e decide o próximo passo. Entre o agente e o seu projeto fica a catraca 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, com o mem0), a sua chave no cofre de credenciais do sistema, os seus arquivos e o seu shell. Os sidecars são programas auxiliares opcionais que rodam na sua máquina e só aceitam conversa vinda dela.

• O que sai da sua máquina, a lista inteira: a chamada ao modelo, a busca na web, o web_fetch que você aprovar, os servidores MCP que você liga, os sidecars (que só a sua própria máquina alcança), o Telegram se você conectar, e a checagem de versão no npm — que instala a atualização sozinha até você desligar com ALUY_AUTO_UPDATE=0. A página de arquitetura detalha cada uma.
• 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.

As três variações seguem o mesmo sistema visual do resto do produto.

Doctor

O /doctor confere a sua instalação: modelo, chave, conexão, servidores MCP e configuração. Para cada item que está fora do lugar, ele aponta uma dica de conserto. Ele só lê, não muda nada.

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. O que sai dela é a chamada ao modelo e, se você ligar, a busca na web, os servidores MCP e o Telegram. A checagem de versão no npm também sai. A lista inteira está na arquitetura.

Onde mora a minha chave?

No cofre do SO (Keychain, libsecret, Credential Manager). Num servidor sem cofre, a chave do seu provider vai para um arquivo cifrado — AES-256-GCM, com a chave derivada da máquina, então uma cópia do diretório não serve em outro lugar. Nos dois casos: 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 CLI fala direto com o seu provider, com a sua credencial (chave de API, OAuth ou um modelo local): é o seu uso, sob o seu controle, sem ninguém no meio e sem ninguém contando quanto você usou. Um backend central é opcional e hoje não está disponível.

Tem custo?

O código do Aluy CLI é público no GitHub. 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 pela catraca de permissão.

Posso ler e modificar o código?

O código é público no GitHub sob a Licença MIT: leia, audite, faça a sua própria versão e relate problemas. O que age na sua máquina, você merece poder inspecionar. O Aluy está em beta: espere encontrar defeitos, e espere versões novas com frequência.