🗺️ Mapa dos comandos por grupo
Toda mensagem que começa com / é comando. O orquestrador responde na hora, sem roteador, sem modelo, sem custo, e o texto nunca vira memória. O que não começa com / é conversa: passa pelo roteador em llama3.2 e vira resposta direta no Ollama ou job de agente. Os comandos se organizam em sete grupos, e é assim que o /ajuda os mostra.
Legenda: o caminho da esquerda para a direita é sempre o mesmo. O grupo só diz o que você está operando. Controle da conversa é a Trilha 4; os outros seis são deste módulo e do próximo.
| Grupo | Comandos (sintaxe exata) | O que devolve |
|---|---|---|
| Fila | /status [id] · /cancelar <id> · /prioridade <id> <n> | rodando/pendente por lane; detalhe de um job com resultado ou erro |
| Custo | /usage | hoje, semana, mês; por tier e por agente (30 dias); orçamento |
| Saúde | /health · /ollama status|preflight <m>|descarregar <m> | Ollama, RAM/swap, RSS, fila, heartbeat, canais |
| Memória | /memoria lista|buscar <t>|salvar <t>|esquecer <id>|propostas|aprovar <id>|descartar <id> · /consolidar · /fontes | cérebro, vault e conectores (módulo 3.2) |
| Tarefas | /tarefa add [quando] <texto> · /tarefa lista · /tarefa feita <id> · /daily | suas tarefas, lembretes, resumo do dia |
| Cron | /cron lista|on <nome>|off <nome> | tarefas agendadas, ativo/inativo, próxima execução |
| Controle | /parar · /retomar · /fila · /personality · /context · /novo · /compress | interruptores, modo de fila, persona, custo do prompt, sessão |
| Utilidade | /chatid · /versao · /ajuda · /ajuda <comando> | id do chat e canal; versão e instância; lista e detalhe |
✦ Dica prática
Na dúvida de sintaxe, não pergunte em prosa (isso vira rota de conversa e gasta o roteador). Mande /ajuda. Para os comandos de controle (/parar, /retomar, /fila, /personality, /context) existe detalhe: /ajuda parar, /ajuda fila. Para os demais, /ajuda <x> responde que não há detalhe e lista os que têm.
📋 Fila na prática
Tudo que demora vira job numa fila em SQLite, separada em cinco lanes com concorrência própria. Jobs nunca são apagados: são o histórico. Quando um pedido "não responde", quase sempre ele está enfileirado atrás de outro na lane agente, que roda um por vez porque cada claude -p consome cerca de 500 MB de RAM.
| Lane | Concorrência | O que roda nela |
|---|---|---|
chat | 2 | resposta direta que chegou durante outra em curso |
agente | 1 | claude -p (lead e especialistas) |
ollama | 1 | consolidação, ingestão, embeddings |
cron | 1 | tarefas agendadas |
io | 4 | rede/arquivo, junção de especialistas, probe do doctor |
Legenda: a coluna do meio é o que explica a espera. Duas respostas diretas em paralelo cabem; dois agentes, não.
Legenda: a primeira parte é o retrato por lane; a segunda, os 5 jobs mais recentes com #id lane/tarefa status. O #id é o que você usa em /status, /cancelar e /prioridade.
✓ O que FAZER
- ✓
/statusantes de mandar o mesmo pedido de novo: ele pode já estar na fila. - ✓
/status <id>para ler o resultado (até 1.500 caracteres) ou o erro (até 300) de um job. - ✓
/prioridade <id> <n>para furar fila em algo que ainda estáqueued. - ✓
/cancelar <id>no que ficou obsoleto; o cancelamento é sem corrida.
✗ O que NÃO fazer
- ✗Reiniciar o serviço porque "travou": o drain gracioso espera até 110 s e o job volta na fila do mesmo jeito.
- ✗Tentar
/prioridadeem job que já estárunningoudone: sóqueuedmuda de prioridade. - ✗Esperar que
/cancelarmate o processo na hora: umclaude -pem execução morre na batida seguinte do worker, até 30 s. - ✗Procurar o job no dashboard para agir: quem opera a fila são os comandos de barra (
/status,/cancelar,/prioridade).
⌘ Copiar e rodar: ler a fila e um job
Objetivo: ver o que está rodando e abrir o detalhe de um job específico, no chat do Telegram com o bot.
/status
/status <id-do-job>
/prioridade <id-do-job> 10
/cancelar <id-do-job>
Como verificar: a resposta do primeiro comando lista as cinco lanes e os recentes; o segundo devolve status, tentativas x/y, duração e o resultado se estiver done. Se o id não existir, o bot responde "Job #N não existe.". Troque <id-do-job> por um número da lista de recentes.
⏰ Tarefas, lembretes e /daily
Tarefas aqui são suas, não do bot: ficam na tabela tarefas_usuario, por chat. /tarefa add [quando] <texto> cria; se o começo do texto for uma data que o bot reconhece, ela vira lembrete e o resto vira o texto da tarefa. Sem data reconhecida, a frase inteira é a tarefa e não há lembrete.
Formato de quando | Exemplos aceitos | Como o bot interpreta |
|---|---|---|
| Relativo | em 30 min · em 2h · em 3 dias | agora + intervalo (min, m, h, hora(s), d, dia(s)) |
| Dia + hora | hoje 18:30 · amanhã 9h · sex 10h · seg 8:15 | hoje, amanhã ou o próximo dia da semana (dom, seg, ter, qua, qui, sex, sáb), na hora dada |
| Data + hora | 15/09 14:30 · 15/09 14h | dia/mês deste ano; se já passou, ano que vem |
| Nenhum | /tarefa add pagar o domínio | tarefa sem lembrete; aparece só em /tarefa lista e no /daily |
Legenda: a data precisa vir no início, logo depois de add. "pagar o domínio amanhã 9h" não vira lembrete; "amanhã 9h pagar o domínio" vira. O fuso é o do processo (a máquina).
Você anota
/tarefa add amanhã 9h ligar pro contador. O bot confirma com o id da tarefa e a data do lembrete em pt-BR.
O cron lembretes cobra
Roda a cada minuto (* * * * *) na lane cron, em sessão isolada. Quando a hora chega, a mensagem vem no Telegram. Se você mandar /cron off lembretes, nenhum lembrete dispara.
Você fecha
/tarefa feita <id> marca concluída (só pendente do seu chat). Ela sai da lista e entra na contagem "feitas nas últimas 24 h" do /daily.
Às 8h, o resumo
O cron daily-8h (0 8 * * *, sessão principal, só se houver ALLOWED_CHAT_ID) manda o mesmo que /daily: até 8 tarefas pendentes, feitas em 24 h, custo do dia, jobs pendentes, resumo do Ollama e os primeiros 500 caracteres do MEMORY.md.
⌘ Copiar e rodar: uma tarefa com lembrete
Objetivo: criar uma tarefa que o bot cobra daqui a poucos minutos, conferir a lista e fechar.
/tarefa add em 2 min <texto-da-sua-tarefa>
/tarefa lista
/tarefa feita <id-que-o-bot-devolveu>
/daily
Como verificar: a primeira resposta é "Tarefa #N criada · lembrete <data>". Em até 2 minutos (mais o tick do cron) chega a mensagem de lembrete. Depois de feita, ela some de /tarefa lista e "feitas nas últimas 24 h" sobe 1 no /daily. Se o lembrete não vier, /cron lista tem que mostrar lembretes com o círculo verde.
✦ Dica prática
Tarefa e memória são coisas diferentes. "Lembra que eu prefiro reunião de manhã" é memória (cérebro, módulo 3.2). "Me lembra amanhã 9h de ligar" é tarefa. Uma frase enviada como conversa pode virar memória semântica por causa do "lembra", mas não cria lembrete: lembrete só com /tarefa add.
🔁 Cron: o que roda sozinho
Cron no v3 não é um processo à parte: cada ocorrência vira um job na fila com idem_key = nome@ocorrência. Se o serviço reiniciar no meio, a mesma ocorrência não dispara duas vezes. Cada cron declara a sessão: isolada (contexto limpo) ou principal (continua a conversa do chat, como o daily-8h). Os padrão são criados no boot, uma vez por nome; o que você desligar fica desligado.
| Nome | Quando | Faz | Estado inicial |
|---|---|---|---|
lembretes | a cada minuto | dispara os lembretes vencidos de /tarefa | ligado |
indexar-memoria | a cada 15 min | gera vetor bge-m3 das memórias sem vetor | ligado |
ingestao-observados | a cada 30 min | extrai fatos dos chats observados do Telegram | ligado |
gmail-ingestao | a cada 2 h | lê as últimas 3 h de e-mail em todas as contas | desligado até autenticar |
agenda-ingestao | 7h05 | próximos 14 dias de todas as agendas | desligado até autenticar |
decaimento | 3h30 | reduz salience por dia sem uso; apaga o que ficou abaixo de 0.05 sem acesso há 30 dias | ligado |
consolidacao-noturna | 4h | duplicatas, contradições, insights (módulo 3.2) | ligado |
backup-noturno | 4h15 | VACUUM INTO + age ou gzip, retenção 14, em store/backups/ | ligado |
daily-8h | 8h | manda o /daily no chat permitido (sessão principal) | ligado se há ALLOWED_CHAT_ID |
Legenda: a ordem da madrugada importa: 3h30 decai, 4h consolida, 4h15 copia. O backup é sempre do estado já consolidado.
✓ O que FAZER
- ✓
/cron listade vez em quando: cada linha traz ativo (🟢/⚪), nome, expressão, tarefa e a próxima execução. - ✓
/cron on gmail-ingestaoe/cron on agenda-ingestaosó depois doauthde cada conta Google. - ✓Se um cron falha 3 vezes em 1 h, o heartbeat alerta no Telegram: leia o
/status <id>do job antes de mexer.
✗ O que NÃO fazer
- ✗Desligar
indexar-memoriapara "economizar": sem vetor, a busca por significado para de achar o que a palavra-chave não pega. - ✗Ligar os crons do Google sem token: cada tick falharia, e o alerta de 3 falhas ia disparar.
- ✗Esperar que
/cron oncrie um cron novo: ele só liga um que existe. Cron novo é código, não comando.
✦ Dica prática
O heartbeat (a cada 30 min) é o vigia do cron e da fila: recupera lease vencido, cancela zumbi (job rodando há mais de 2× o timeout de 20 min) e alerta 3 falhas da mesma tarefa em 1 h. Se /health mostrar heartbeat "nunca" ou com mais de 90 min, o GET /health deixa de responder ok e é hora de olhar o journalctl (Trilha 2).
🧩 Agentes, skills e sessão
Dois comandos mostram o que está instalado e dois controlam o quanto o bot "carrega" da conversa anterior. /agentes lista cada agente de agents/<id>/ com o modelo e a marca "só leitura" quando for especialista; /skills lista as skills de skills/, e as de skills/_rascunhos/ aparecem com 📝 na frente. Skills entram no prompt só pela metadata (nome e descrição), não pelo corpo: é assim que o prompt não incha.
/novo | /compress | |
|---|---|---|
Sessão --resume do CLI (agente) | apaga | apaga |
Histórico do chat no conversation_log | apaga (o bot diz quantos turnos) | mantém |
Memórias (memories) e vault | mantém | mantém |
| Próximo turno | começa do zero, só com identidade, USER.md e memória | sessão nova de agente, mas a resposta direta ainda vê o histórico |
| Quando usar | mudar totalmente de assunto; sessão contaminada | o agente ficou lento ou "preso" no contexto antigo; quer poupar tokens |
Legenda: nenhum dos dois toca a memória de longo prazo. O que se perde é conversa, não fato.
▦ Novo aqui? Sessão retomada
Quando um agente roda, o claude -p abre uma sessão e o v3 guarda o id dela por chat. No pedido seguinte, o agente é retomado com --resume e "lembra" do que fez. Sessão com mais de 6 h não é retomada: o cache do provedor já expirou e não compensa. Trocar de personalidade (/personality) também apaga as sessões, senão o agente voltaria com a voz antiga.
⌘ Copiar e rodar: inventário e reset
Objetivo: ver quais agentes e skills o seu v3 tem, e limpar a sessão sem perder o histórico.
/agentes
/skills
/compress
Como verificar: /agentes devolve uma linha por agente no formato id (modelo, só leitura) seguido da descrição; no repo de hoje são comms, content, ops e research. /skills lista uma por linha, com 📝 nos rascunhos. /compress responde "Sessões limpas: N (histórico mantido; próximo turno começa sessão nova)".
🚀 Pedir trabalho a um agente
Você não escolhe a rota: o roteador escolhe. Pedido que precisa de ferramenta (arquivo, shell, repo, web, skill, calendário) vai para a rota agente. O bot responde na hora com um briefing curto: o nome do agente, o número do job, quantos estão na frente e o lembrete de que /status N acompanha. Depois o worker roda claude -p --output-format json com o prompt em camadas (identidade, agente, memória, skills, mensagem), e a resposta volta pelo bus ao mesmo chat, com o custo real registrado.
Legenda: o caminho de cima é o comum. O ramo ciano acontece quando o roteador marca consultar: até 2 especialistas só leitura (ex.: research) rodam antes e o lead escreve a resposta final. Só o lead escreve.
✓ Pedido que sai certo
- ✓Diz o que quer, onde (pasta, repo, arquivo) e como saber que está pronto.
- ✓Uma tarefa por mensagem. Duas tarefas viram dois jobs em sequência de qualquer jeito, e a segunda perde o contexto da primeira.
- ✓Nomeia a ferramenta quando importa ("usa a skill X", "no repo Y"): o roteador acerta o agente com mais facilidade.
- ✓Depois do briefing, espera.
/status Nquando quiser saber; o resultado chega sozinho.
✗ Pedido que vira job ruim
- ✗"Dá uma olhada nisso" sem dizer o quê nem onde: o agente gasta tokens descobrindo o que você quis.
- ✗Mandar a mesma coisa de novo porque demorou: no modo
collectas duas juntam; nos outros modos vira segundo job. - ✗Pedir mídia paga (HeyGen, render) esperando que rode: a identidade proíbe sem confirmação explícita no momento.
- ✗Esperar resposta de agente com
/parar agentesligado: o bot avisa que o agente está parado e responde só pelo modelo local.
⌘ Copiar e rodar: um pedido de agente de ponta a ponta
Objetivo: disparar um job de agente com um pedido bem formado, acompanhar pela fila e ler o resultado e o custo.
Lê o README.md do repo ~/projetos/<nome-do-seu-repo> e me devolve, em 5 linhas, o que o projeto faz e como se roda. Não altera nada.
/status <numero-do-job-que-veio-no-briefing>
/usage
Como verificar: a primeira resposta é o briefing com 🧠, o nome do agente e job #N. Enquanto roda, /status N mostra status: running; ao terminar, o resumo chega no chat e /status N passa a done com o texto. No /usage, o agente aparece em "Por agente (30 d)" com custo em US$. Se a saída do CLI não puder ser interpretada, o erro do job aponta o arquivo bruto em store/saidas/job-N.txt.
✦ Dica prática
Toda resposta que sai passa pela guarda de exfiltração: token, chave de API, JWT e os valores das variáveis sensíveis do .env viram [REDIGIDO]. Se um agente "devolveu" uma chave e você vê [REDIGIDO], está funcionando. Não peça para o bot imprimir segredos; ele não vai, e é assim que deve ser.
✅ Resumo do módulo
/ajuda e /ajuda <comando>agente roda 1 por vez; /status, /status <id>, /cancelar, /prioridade só em queued/tarefa add [quando] <texto>, data no início; cron lembretes cobra; /daily às 8h/cron lista|on|off; Google desligado até autenticar/novo apaga o histórico; memória fica/usagePróximo módulo:
3.2 - Cérebro e conectores: o que o bot guarda, como buscar e corrigir, e como ligar Gmail, agendas e grupos do Telegram à memória.