Manual do Satori

Antes de começar

O Satori não substitui os seus CLIs de IA: ele os roda. Cada conversa é conduzida pelo Claude Code, pelo Codex ou pelo OpenCode instalado na sua máquina, com a conta que você já usa neles. O Satori acrescenta a interface.

Requisitos

O Satori trabalha com três CLIs:

Use o instalador nativo do Claude Code (a linha acima), e não o pacote do npm: o chat do Claude depende dessa instalação. Codex e OpenCode são opcionais; os que estiverem instalados aparecem sozinhos.

O Gemini CLI não é suportado: o free tier dele foi descontinuado e nem autentica.

Instalar

1. Baixe o instalador da versão mais recente: baixar o instalador.
2. Rode o instalador e abra o Satori pelo menu Iniciar.

Não há mais nada para instalar. Novas versões chegam pelo próprio app (veja Atualizações).

Primeira abertura

O Satori procura os CLIs pelo PATH e as contas pelas pastas de perfil do seu usuário. Se faltar algo para o chat funcionar, a primeira tela diz o quê:

• Falta instalar o Claude Code. A tela mostra a linha de instalação, com um botão para copiar. Rode no terminal e clique em Já instalei — verificar. Se o Claude Code já está instalado numa pasta fora do PATH, aponte o executável em Configurações › CLIs & Provedores.
• Falta conectar uma conta. Dê um nome ao perfil (o padrão é pessoal) e clique em Criar e entrar. Abre uma janela de terminal com o Claude Code: digite /login, conclua no navegador e volte ao Satori. Depois, Já fiz login — verificar.

Se o terminal não abrir, a tela mostra o comando de login para você rodar no seu.

Perfis: uma conta por pasta

Um perfil é uma conta separada de um CLI, guardada numa pasta própria. As pastas .claude*, .codex* e .opencode* do seu usuário que já foram usadas aparecem sozinhas em Configurações › Perfis. Ali também dá para:

• criar um perfil novo: escolha o CLI, dê um nome (ex.: trabalho) e clique em Criar e entrar; o login abre em seguida;
• adicionar um perfil em outro lugar, colando o caminho da pasta;
• esconder um perfil da lista, sem apagar nada do disco.

O login de Codex e OpenCode também pode ser feito em Configurações › CLIs & Provedores, pelo botão Entrar… (ou Trocar conta…, quando já há conta). Na mesma aba, Apontar… indica o executável de um CLI que a detecção não achou.

O primeiro chat

1. Ctrl+N (ou o + da lateral) abre um chat novo.
2. Nos chips abaixo do título, escolha com quem falar (um perfil do Claude Code, o Codex ou o OpenCode), a pasta do projeto, o modelo e o modo.
3. Escreva e pressione Enter.

Perfil e pasta congelam depois da primeira mensagem; modelo e modo podem mudar a qualquer momento. Os detalhes estão em A barra da sessão.

A janela

A navegação é a faixa do topo, com os destinos no meio (Chat, Histórico, Orquestração, Git, Canvas e Kanban), a engrenagem de Configurações à direita e os controles de janela na ponta. A lateral é contextual: ela existe no Chat e no Canvas, onde governa o que está na tela, e some no resto.

Quando não há conversa aberta, aparece esta tela: a saudação vem do relógio da máquina e há um cartão por CLI instalado. Clicar num deles escolhe o CLI e a conta do chat que você vai começar.

Barra lateral. Arraste a borda direita para redimensionar (180–460 px). Duplo clique no divisor volta ao padrão. Ctrl+B recolhe para uma faixa só de ícones; o nome aparece ao passar o mouse. Largura e recolhimento continuam como estavam ao reabrir o app.

Chats agrupados por projeto. Cada grupo leva o nome da pasta em que aquele chat trabalha e a quantidade de conversas nele. Clique no cabeçalho para recolher ou abrir; o que você deixou fechado continua fechado na próxima vez.

O chat que está aberto continua visível mesmo com o grupo recolhido. O caminho completo da pasta aparece ao passar o mouse sobre o nome do projeto.

+ no grupo (aparece ao passar o mouse) abre um chat já naquela pasta. Sem ele, o chat novo herda a pasta do chat ativo.

Fixar. O alfinete no item leva o chat para um grupo Fixados no topo, com o nome da pasta como segunda linha, já que ali os chats vêm de projetos diferentes. Clique de novo para desafixar. O que está fixado continua fixado quando você reabre o app.

Filtrar. A lupa ao lado do + abre um campo que filtra por nome do chat ou pela pasta. Enquanto o filtro está ativo todos os grupos ficam abertos. Esc fecha e limpa; fechar pela lupa também limpa.

Ponto colorido ao lado de cada chat:

A marca vermelha some quando você manda a próxima mensagem naquele chat.

Selo de estado, à direita do nome, quando há algo que você precisa saber sem abrir o chat:

Aparece um só de cada vez, nessa ordem de prioridade: o que depende de você vem antes do que depende de esperar.

Chat

Escreva e pressione Enter (Shift+Enter quebra a linha). A resposta aparece conforme chega.

A resposta inteira vira um cartão por turno, com uma tira no topo dizendo qual CLI respondeu, com que modelo e, quando o turno fecha, quanto tempo ele levou. Logo abaixo do título ficam os chips da sessão: conta, pasta, modelo e modo.

Imagens e comandos

Imagens (PNG, JPEG, WebP ou GIF) entram na mensagem de três jeitos: colando com Ctrl+V, arrastando para o campo ou pelo botão de anexar. A miniatura aparece na hora, acima do campo.

/ no início do campo abre o menu de comandos e skills do CLI (no Claude Code e no OpenCode), para escolher em vez de lembrar o nome.

Ferramentas e subagents

As ferramentas que o agente usa em sequência ficam agrupadas num bloco fechado, para a conversa não virar uma parede de linhas:

▸ 3 ações  Write ×3            ← clique para abrir

Aberto, cada ferramenta é uma linha:

▾ 4 ações  Read ×3, Bash
    ◜ Bash    npm test              ← rodando
    ✓ Read    calculadora.js        ← concluída, clique abre a saída
    ✕ Read    naoexiste.txt         ← falhou, a saída já vem aberta
    – Edit    arquivo.js            ← ficou sem resultado até o fim do turno

Clique na linha para ver o que a ferramenta devolveu.

Falha abre o grupo sozinha e deixa o cabeçalho vermelho: um bloco fechado não pode esconder erro.

Texto do agente ou cartão de arquivo no meio encerram o grupo: as ferramentas seguintes começam um bloco novo, na ordem em que aconteceram.

Subagent tem cartão próprio. Quando o agente abre um Task, tudo que o subagent fizer (o que ele escreve e as ferramentas que usa) fica dentro daquela linha, com a contagem de ações no canto (6 ações). O cartão fica solto no fluxo, com moldura, e nasce fechado; um erro lá dentro o abre sozinho.

▸ 3 ações  Read ×2, Grep

┌ ▸ Task   revisar o diff          6 ações ┐

agente: encontrei três problemas…

O tempo de cada turno

Enquanto o turno roda, uma barra trabalhando… fica no pé da conversa, com o tempo correndo ao lado:

⟳ trabalhando…  1m 12s

Quando o turno acaba, a barra para de girar e fica na conversa como registro de quanto aquele turno levou:

✓ 2m 59s · 11:23

Uma linha por turno, então dá para olhar para trás e ver onde o tempo foi. O relógio zera a cada mensagem sua, inclusive quando você enfileira várias.

Renomear e editar

Renomear o chat. Duplo clique no título, no alto da conversa. Enter salva, Esc desiste, clicar fora salva. Nome vazio mantém o anterior.

O título automático é a primeira frase que você escreveu. Depois de renomear à mão, o Satori não sobrescreve mais aquele nome, e ele continua ao reabrir o app.

Editar a última mensagem. Terminado o turno, o lápis no seu último balão permite corrigir a mensagem e reenviar: a resposta que ela produziu é descartada e o agente responde de novo. Enter salva, Esc cancela. O lápis só aparece quando o CLI daquele chat permite voltar àquele ponto; num chat retomado do Histórico, por exemplo, ele aparece depois da primeira troca nova.

Quando o agente pergunta

Quando ele precisa de uma decisão sua, sobe um painel acima do campo de mensagem com as opções, e a conversa continua visível atrás.

Nenhuma opção vem pré-escolhida. A descrição de cada uma sai em uma linha; o texto inteiro aparece ao passar o mouse. Clicar de novo na opção marcada desmarca. Quando o agente aceita mais de uma escolha, o aviso "pode escolher mais de uma" aparece sob a pergunta e cada opção ganha uma caixinha.

Nenhuma das opções serve? Toda pergunta tem Outro…, que abre um campo para você escrever a resposta com suas palavras.

A pergunta não expira. O turno fica parado até você responder. Pular (ou Esc) segue sem responder, e o agente fica sabendo que não houve resposta. (O pedido de permissão é o contrário: tem prazo, e sem resposta a ação é negada.)

Comandos em segundo plano

O agente pode deixar algo rodando depois de responder: um servidor, um build, um teste longo. Cada chat tem um processo próprio do CLI, que vive enquanto o chat estiver aberto, igual ao terminal. Fechar o chat encerra esse processo.

No chat do Claude Code, o que ficou rodando aparece numa faixa no fim da conversa, com um botão parar por item. A faixa some sozinha quando a lista esvazia. No Codex e no OpenCode o processo vive do mesmo jeito, mas sem essa lista.

Fechar o Satori encerra tudo isso. Havendo chat em andamento ou comando em segundo plano, o Satori avisa o que vai junto e pede confirmação; sem nada rodando, ele fecha direto.

Hooks do seu perfil

Se você tem hooks no settings.json do Claude Code, eles valem no chat do Satori do mesmo jeito que valem no terminal. O Satori só fala deles quando um hook recusa uma ação ou falha:

um hook do perfil recusou PreToolUse:Write — não escreva no .env

Num chat de Codex ou OpenCode o alcance é menor, e o chat avisa na largada o que não vale, antes de você confiar num guard que não vai rodar.

A barra da sessão

Os chips abaixo do título do chat decidem para onde a mensagem vai. A statusline fica junto do campo de texto:

[.claude-work ▾] [🗀 pasta] [modelo ▾] [Manual ▾]   ● modelo  ⑂ branch  ctx ▰▰▱ 38%  5h ▰▰ 27%  7d ▰ 25%

Perfil

Com quem o chat fala: um perfil do Claude Code, o Codex ou o OpenCode (veja Com quem o chat fala). Congela depois da primeira mensagem, porque a conversa fica gravada naquele perfil. Para outro, abra um chat novo.

Pasta do projeto

Onde o agente trabalha. Clique para escolher pelo seletor do Windows. Mostra só o nome da pasta; o caminho completo fica ao passar o mouse. Congela depois da primeira mensagem.

Modelo

A lista vem do próprio CLI, então mostra os modelos que a sua conta pode usar. Pode trocar a qualquer momento: vale a partir da próxima mensagem, e o chat registra o aviso. Padrão deixa o perfil decidir; a statusline mostra qual foi de fato.

Modelos com janela de contexto maior (como as variantes "1M" do Claude) são opções próprias na lista. A barra ctx mostra o tamanho da janela que o CLI reportou para o modelo em uso.

Modo

No Claude Code, o modo define como o agente se comporta diante de operações que alteram coisas:

Com o menu aberto, as teclas 1–4 escolhem direto. O padrão é Manual.

"Ignorar permissões" desliga o pedido de permissão por completo. Nenhum modal aparece e o agente executa tudo sem perguntar. O chip fica vermelho enquanto estiver ativo e a escolha registra um aviso na conversa.

No Codex e no OpenCode o mesmo chip vira a política do chat (veja Com quem o chat fala).

Statusline

Cores seguem faixas: verde abaixo de 50%, amarelo até 65%, laranja até 80%, vermelho acima disso.

5h e 7d vêm do Claude Code do terminal. Esses números são os que a statusline do Claude Code grava quando você o usa no terminal. Se passar horas só no Satori, o valor para de andar; acima de 30 minutos aparece um ⏱, e ao passar o mouse você vê de quando ele é.

Com quem o chat fala

O primeiro chip escolhe o CLI: um dos perfis do Claude Code, o Codex ou o OpenCode. Só dá para trocar antes da primeira mensagem.

A grande diferença é a aprovação:

Com Codex e OpenCode você escolhe uma vez, na largada, o quanto o agente pode fazer, e ele faz sem perguntar. No OpenCode não existe "somente leitura": o padrão já escreve na pasta do chat. O chat anuncia a política ao começar e a cada troca.

O que continua igual nos três: a resposta aparecendo conforme chega, as ações agrupadas, o cartão de diff com o antes e o depois lidos do disco, a fila de mensagens e o histórico.

O que cada CLI oferece nas outras telas:

Quando um recurso não existe naquele CLI, o controle some da tela em vez de ficar cinza.

Permissões

No modo Manual do Claude Code, operações que alteram algo abrem um modal com a ferramenta e os parâmetros exatos.

O diff é o que a escrita PROPÕE, não o que já aconteceu: o pedido chega antes de o arquivo ser tocado, então o que está na tela é exatamente o que o Permitir vai deixar acontecer.

• Permitir: executa
• Permitir sempre: executa e não pergunta de novo por operações do mesmo tipo
• Negar: o agente recebe o motivo e segue sem aquela operação
• Esc: nega
• Sem resposta em 120 s: nega

Um pedido que expira nunca vira permissão concedida.

Permitir sempre só aparece quando o Claude Code diz o que cobriria aquele pedido, e o modal escreve na tela exatamente o que vai acontecer:

No primeiro caso o chip de modo muda junto, à vista. Para voltar, é só escolher Manual ali.

A liberação fica guardada por perfil e por projeto: vale nos próximos chats daquela conta naquela pasta, e em nenhum outro lugar. Um chat que nasce com uma liberação guardada avisa isso na conversa. Para ver e revogar o que já foi liberado, use Configurações › Permissões. O Satori guarda isso no estado dele, e não no settings.json do seu perfil.

Se um chat em segundo plano pedir permissão, ele vira o chat ativo e o modal diz qual é, para o pedido não expirar sem você ver.

Arquivos alterados

Cada arquivo que o agente toca vira um cartão na conversa:

▾ calculadora.js   [Edit]                    +12  −3

Clique para abrir o diff, com numeração dos dois lados: a coluna esquerda é o arquivo antes, a direita depois.

O diff é lido do disco, não do que o agente disse ter feito. O Satori lê o arquivo antes e depois de cada ferramenta de escrita e compara. Se o agente disser que alterou algo e o arquivo não mudar, o cartão não aparece.

Casos especiais:

• novo: arquivo criado, só linhas adicionadas
• mudança grande demais: acima de 1500 linhas alteradas, mostra as contagens sem despejar tudo na janela
• sem conteúdo de texto: binário ou arquivo apagado

Arquivo criado por Bash (por exemplo echo > arquivo.txt) não gera cartão: o Satori acompanha as ferramentas de arquivo, não o shell.

Fila de mensagens

O campo nunca trava. Mandar mensagem durante um turno enfileira em vez de recusar.

Mensagens na fila aparecem na conversa com contorno tracejado e · na fila, e viram balão normal quando chega a vez delas. A ordem é preservada. Uma mensagem ainda na fila pode ser editada no lugar, sem perder a posição.

O botão muda de acordo:

• campo com texto → Enviar
• campo vazio durante um turno → Parar

Parar descarta a fila. As pendentes ficam riscadas e um aviso diz quantas foram. Sem isso, você mandaria parar e a próxima da fila começaria em seguida.

Isso é fila, não interrupção: a mensagem nova não interfere no que o agente já está fazendo; ela roda depois.

Vários chats ao mesmo tempo

Ctrl+N ou o + na lateral cria um chat. Cada um tem histórico, perfil, pasta e modo próprios.

Dá para mandar um chat trabalhar, ir para outro e voltar: o ponto colorido mostra quem está ocupado. Um chat que falha em segundo plano fica com o ponto vermelho sem você precisar entrar nele.

Chats de pastas diferentes ficam em grupos separados na lista, cada um com o nome do projeto.

Fechar um chat (×) interrompe o que estiver rodando nele.

A bancada volta ao abrir o app. Os chats que estavam abertos são restaurados, com as últimas mensagens e o nome que você deu a cada um. Um chat que nunca recebeu resposta não é salvo, porque não haveria conversa para trazer de volta. Dá para desligar a restauração em Configurações › Geral.

Worktrees: um chat por branch

Dois chats na mesma pasta disputam os mesmos arquivos: o agente de um edita o que o outro está lendo, e o git status mistura os dois trabalhos. Uma worktree resolve isso: é um segundo checkout do mesmo repositório, com branch própria, numa pasta separada.

Abra pelo ⑂ do cabeçalho do painel de Git, ou pelo ⋯ do grupo de um projeto na lista de chats. O diálogo faz três coisas:

Criar. Digite o nome da branch e clique em Criar e abrir chat. A branch nasce do estado atual do repositório, a pasta é criada em <projeto>/.worktrees/<branch> e o chat já abre lá, em grupo próprio na lateral, com o nome da branch. Nome que já existe como branch não é recriado: o chat abre no trabalho que já estava nela.

Abrir. A lista mostra as worktrees do repositório. Abrir chat cria um chat novo em qualquer uma delas, inclusive nas que você criou pelo terminal, que aparecem marcadas como externa.

Remover. Dois cliques (o primeiro só arma o botão) apagam a pasta. A branch continua no repositório: nada do que você commitou se perde.

O botão de remover não aparece quando a remoção não faria sentido:

Se houver alteração não commitada, quem recusa é o próprio git, e a mensagem dele aparece no diálogo. Commite, faça stash ou remova pelo terminal.

Fechar o chat não apaga nada. A pasta é sua e fica onde está. Quando terminar (mergeou, virou PR, desistiu), volte no ⑂ e remova.

A pasta .worktrees/ fica escondida do git status do projeto por uma regra local do seu clone (.git/info/exclude): o .gitignore do repositório não é tocado, e nada disso vai parar num commit seu.

Git

O repositório é escolhido no primeiro chip do topo, e fica guardado: ele não muda quando você troca de chat.

A lista do chip traz Escolher pasta…, Seguir o chat ativo e um item por projeto que você tem aberto em algum chat. O chip fica tracejado quando está seguindo o chat.

À esquerda, duas listas: No índice (o que vai entrar no próximo commit) e Alterados (o que mudou e ainda não entrou). Cada linha tem a letra do git (M mudou, A novo, D apagado) e um botão pôr ou tirar. Os atalhos pôr tudo e tirar tudo ficam no cabeçalho de cada lista.

Clique num arquivo e o diff aparece à direita, em blocos. Cada bloco tem o próprio botão: dá para pôr no índice só um pedaço do arquivo e deixar o resto de fora, como um git add -p sem a linha de comando.

Gerar mensagem manda o que está no índice para um CLI escrever a mensagem do commit. Escolher o CLI na lista é o que dispara, porque isso consome uso da conta. A mensagem cai no campo e você edita antes de commitar; o que já estiver escrito ali vira instrução a mais para o CLI.

Quem commita é o git, não o agente. A IA escreve a frase e para por aí: o que entra no commit é exatamente o que está no índice, e você viu o que é.

Commit só fica ativo com algo no índice e uma mensagem escrita. Depois dele, o botão da direita publica: Publicar branch quando ainda não há upstream, Enviar N quando há commits para subir.

O painel tem duas abas. Alterações é o que está descrito acima. Histórico é a árvore de commits: as raias mostram de onde veio cada um, com as branches e tags marcadas na linha. Clique num commit e o que ele mudou aparece ao lado. A lista traz 200 por vez, com carregar mais no fim.

A divisória entre as duas colunas é arrastável, nas duas abas. Duplo clique nela volta ao tamanho padrão, e a largura escolhida fica guardada.

Canvas: os chats numa mesa

O Canvas mostra os seus chats como cartões numa mesa. São os mesmos da barra lateral, com o mesmo estado, o mesmo ponto colorido e os mesmos selos. O que muda é que aqui eles têm posição, e a posição é sua.

Serve para quando há mais conversa do que cabe na cabeça: dez chats de três projetos numa lista são dez linhas parecidas; na mesa você os arruma por assunto, escreve uma nota ao lado e vê de uma olhada quem está trabalhando.

Navegar

O minimapa, no canto inferior esquerdo, mostra o mundo inteiro e onde a sua vista está. Some com menos de dois chats.

Filtrar (o campo do cabeçalho) esmaece quem não casa em vez de esconder, para nenhum cartão parecer ter mudado de lugar. Enter leva a vista até o que sobrou.

Abaixo de 60% de zoom o cartão fica compacto: somem o modelo, a prévia e o rodapé, e o título ganha uma linha.

O cartão

De cima para baixo: o ponto de estado com o CLI e o modelo, o título do chat, a última fala, onde ele roda e em qual conta, e o relógio do turno.

Clicar no cartão não abre a conversa, porque no canvas o gesto frequente é arrumar. Quem abre é o Abrir sessão ↗ do rodapé, ou Abrir conversa, no menu, quando o zoom baixo esconde o rodapé.

Chat parado esperando você ganha uma faixa de alerta com o nome da ferramenta e quanto falta para o pedido expirar. Ela não some no zoom baixo.

O ⋯ no alto do cartão (ou o botão direito nele) abre as ações daquele chat: abrir, responder, novo chat daqui, renomear, definir o passo, pôr num workspace, fixar, worktrees e fechar. São as mesmas da lista da lateral.

Organizar

Arraste o cartão para movê-lo. Solto perto de uma linha da grade ele encaixa; mais longe, fica exatamente onde você soltou. Com as setas, Shift anda uma célula da grade em vez do passo fino.

Arrumar, no cabeçalho, põe uma coluna por projeto. Duplo clique no vazio cria um chat ali mesmo, herdando pasta, perfil e modelo do chat aberto.

Arrastar um chat da barra lateral para dentro do canvas o põe onde você soltou.

Soltando pastas do Explorer no canvas, cada pasta vira um chat nela. Arquivos viram um chat na pasta-mãe com os caminhos já escritos no campo de envio: o que pedir sobre eles continua sendo você quem diz. Soltos em cima de um cartão, vão para aquele chat em vez de criar outro.

Regiões de projeto. Dois ou mais chats da mesma pasta ganham uma moldura tracejada com o nome do projeto e a contagem. Trocar a pasta de um chat o tira do grupo sozinho, e um chat sozinho não vira moldura.

Clique no rótulo da moldura e o projeto recolhe numa pílula com o nome, a contagem e o estado. Clique na pílula para abrir de novo, e arraste a pílula para levar o grupo todo de uma vez. O que você recolheu continua recolhido quando reabre o app.

Notas. Botão direito no vazio › Nota nova aqui. Quatro cores (o ponto da alça cicla), tamanho ajustável pela quina de baixo, e arrasta pela alça: arrastar em cima do texto seleciona o texto. Nota vazia não é gravada; é assim que se apaga uma.

Exportar (o ícone de download no cabeçalho) salva um PNG do mundo inteiro, em dobro do tamanho. Projeto recolhido sai aberto na imagem.

Trabalhar sem sair do canvas

Marcar vários: Shift+arrasto no fundo laça, Ctrl+clique (ou Shift+clique) marca um a um, Ctrl+A pega todos, Esc limpa.

Arrastar um cartão marcado move a seleção inteira, sem desfazer o arranjo entre eles. Arrastar um cartão de fora da seleção a desfaz.

Com cartões marcados:

Fechar em lote pergunta, e ainda dá para voltar. Depois de confirmar, uma faixa oferece Desfazer por alguns segundos e reabre os chats de onde pararam. Só voltam os que já tiveram alguma resposta, e a faixa diz quantos são quando o número difere.

Workspaces nomeados

Uma moldura sólida em volta de chats que você juntou à mão: dois repositórios diferentes que são a mesma frente de trabalho, e que a pasta nunca teria como agrupar. A tracejada vem da pasta; a sólida, de uma escolha sua.

No menu do cartão, Pôr num workspace… (ou Workspace dos N… com vários marcados): escreva o nome e clique em Agrupar. O campo sugere os que já existem, e maiúsculas não contam: "Auth" e "auth" são o mesmo workspace.

O workspace vence a pasta: um chat aparece num grupo só, o que você escolheu. Campo em branco, ou o Tirar ao lado, devolve o chat ao grupo do projeto. Um chat sozinho num workspace não vira moldura; nesse caso o nome aparece no próprio cartão.

Quem nasce dentro de um workspace o herda: Novo chat daqui e o duplo clique dentro da moldura entram na mesma frente. No vazio fora dela, o chat nasce sem workspace.

Workflow: uma cadeia de chats

O canvas também liga chats para que um rode depois do outro, com a resposta do primeiro entrando no pedido do segundo.

Ligar. Passe o mouse num cartão e as duas portas aparecem: um anel vazado à esquerda (entrada) e uma bolinha cheia à direita (saída). Arraste da saída até qualquer ponto de outro cartão. A linha sólida com seta é a ordem de execução.

Ligação impossível é recusada na hora, com o motivo escrito na tela: um chat não se liga a si mesmo, dois já ligados não se ligam de novo nem no sentido contrário, e nada pode fechar um ciclo.

Apagar uma ligação: clique nela e use o ✕ que aparece no meio, ou a tecla Delete.

O passo é o pedido que cada chat recebe quando a cadeia chega nele. Menu do cartão › Definir passo…. Dentro do texto, {{saida}} é o lugar onde a resposta do chat anterior entra; o botão inserir {{saida}} escreve o token onde está o cursor. Ctrl+Enter salva, Esc desiste, Enter quebra linha.

Duas regras que poupam digitação:

• passo em branco encaminha a resposta do anterior como ela veio;
• sem {{saida}}, o passo roda só o que você escreveu, e o que veio antes é ignorado. O ⚡ na faixa do cartão acende quando o passo usa a saída do anterior.

Rodar é sempre um gesto seu: o botão Rodar workflow no cabeçalho, ou a tecla R (só R, sem Ctrl: Ctrl+R recarrega a interface). Havendo cartões marcados, roda só o pedaço ligado dentro da seleção; sem seleção, roda tudo que estiver ligado na tela. O botão só aparece quando existe alguma ligação.

Enquanto roda, uma faixa no alto diz o passo, o total e de quem é a vez, e os cartões se marcam: o que já rodou, o da vez e os que esperam. Não há porcentagem, porque nenhum CLI sabe dizer quanto falta de um turno.

Os chats rodam um por vez, na ordem das setas, nunca em paralelo. O que passa adiante é tudo que o agente falou naquele turno.

Quando algo interrompe:

E quatro recusas, todas antes de gastar um turno: o workflow já está rodando; há um ciclo; a cadeia passa de 12 chats; ou um dos chats está no meio de um turno.

O que o canvas não faz

Não existe encadeamento automático. Nada aqui dispara sozinho: a cadeia só anda depois de você clicar em Rodar workflow ou apertar R, e só até onde você mandou.

Não é orquestração. Na Orquestração os CLIs respondem o mesmo pedido em colunas, para você comparar. Aqui cada chat continua sendo a sua conversa, com a sua pasta, a sua conta e a sua fila; o que passa de um para o outro é a resposta, não o pedido.

A conversa não acontece dentro do cartão. Ele mostra a última fala e o que o chat está fazendo; para ler ou trabalhar de verdade, abra a sessão.

E nada aqui muda a conversa. Mover, agrupar, recolher e anotar são arranjo de tela: os chats continuam onde estavam, na lista da lateral. A única ação com perda real é fechar, e é a única que pergunta antes.

Equipe: papéis que vestem um chat

Um papel é nome + instrução + CLI + modelo + modo. Vestir um chat com ele faz a instrução chegar ao modelo e valer pela conversa inteira, sem virar fala sua e sem aparecer na conversa. Serve para o que você repete: "revise procurando injeção de SQL", "escreva as notas da versão para quem usa".

Criar e editar é na lateral do Canvas (+ Novo papel); Configurações › Equipe só liga e desliga a exibição na lista.

A instrução é lida na abertura da sessão. Vestir um chat que já conversou vale no próximo chat, não no próximo envio; o cartão diz se ela já está valendo. O modelo e o modo valem na hora.

Papel de outro CLI cria um chat novo no lugar do antigo. Uma conversa em andamento não se transfere entre CLIs: o chat novo herda posição, tamanho, pasta, workspace, o passo e as ligações do workflow, e o antigo fica intacto e fora da cadeia.

No workflow, um nó vestido dispensa passo: o papel já diz o que aquele chat faz com o trabalho do anterior.

Desligar em Configurações não apaga nem desveste: só esconde da lista da lateral. Um chat já vestido continua com o papel.

Kanban: o quadro do projeto

O Kanban da faixa do topo é um quadro de tarefas por projeto. O chip ao lado de Projeto escolhe qual, e a escolha é lembrada; com a borda tracejada, ele está seguindo a pasta do chat ativo.

Um quadro novo nasce com A fazer / Fazendo / Revisão / Feito, e as colunas são suas:

O card tem título, descrição, cor, etiquetas (separadas por vírgula), prazo e checklist. + Adicionar card cria; clicar no card edita; arrastar o leva para outra coluna ou outra posição. A busca e o chip Etiquetas filtram o que aparece.

Do card para o trabalho, pelas ações que aparecem ao passar o mouse:

• Virar chat abre um chat na pasta do projeto com o título, a descrição e o checklist em aberto já escritos no campo de envio. Nada é enviado: você revisa e manda.
• Virar nó cria o mesmo chat no Canvas, com o card como passo do workflow.

O card vinculado ganha uma faixa com o CLI e o que o chat está fazendo agora (executando · 00:48, esperando você, falhou, pronto), e ↗ leva à conversa. No caminho de volta, o chat mostra o chip ▦ <coluna> na barra da sessão (clicar leva ao card no quadro), e o nó do canvas ganha a linha card com a coluna e o título.

O card não muda de coluna sozinho. Mover é com você — ou com o agente, quando você pede (abaixo).

Apagar um card que virou chat pergunta antes. Confirmado, o chat continua aberto; ele só deixa de estar ligado ao card.

Pedir ao agente: o quadro e o canvas pelo chat

Todo chat do Satori — Claude, Codex ou OpenCode — já vem com as ferramentas do Satori para o quadro e o canvas. É só pedir em palavras:

• "crie um card em A fazer para revisar o login, com checklist ler, testar e documentar"
• "mova o meu card para Revisão e marque o item testar" — meu card é o card de onde o chat nasceu (pelo Virar chat ou Virar nó)
• "monte no canvas três nós: um que levanta os requisitos, um que implementa e um que revisa, ligados nessa ordem"

Toda mudança pede a sua permissão no mesmo modal de sempre, com Permitir sempre valendo para este perfil e este projeto. Ler não pede nada.

O nó que o agente cria aparece no canvas e na lateral sem tirar você da tela em que está e sem mexer no que você está digitando. Ele nasce na mesma pasta, conta e workspace do chat que pediu, e não recebe mensagem nenhuma — ele só fica salvo quando rodar o primeiro turno.

Isto só existe com o Satori aberto. As ferramentas moram dentro do app; o mesmo CLI aberto num terminal não as tem.

Histórico

Todas as conversas do perfil, agrupadas por projeto e ordenadas da mais recente para a mais antiga. A pasta em que você está trabalhando já vem aberta. O chip da esquerda escolhe a fonte: Claude Code, Codex ou OpenCode.

O Satori não guarda conversa nenhuma: ele lê o que cada CLI já grava. Na prática, as conversas que você teve no terminal aparecem aqui também.

Retomar não é só mostrar as mensagens antigas na tela: o agente recebe o histórico de verdade. Você pode perguntar "o que fizemos aqui?" e ele responde sem reler os arquivos.

Skills

Uma skill é uma pasta com SKILL.md que o agente abre sob demanda, dentro da conversa que já está rolando. É diferente de um agent, que é um subagente com contexto próprio (veja Agents).

Os três CLIs têm skills, e o chip da esquerda escolhe de qual você está olhando. Algumas pastas são lidas por mais de um CLI: ~/.agents/skills/ pelo Codex e pelo OpenCode, e ~/.claude/skills/ pelo Claude Code e pelo OpenCode. A mesma skill em dois painéis é o mesmo arquivo em disco, e a pasta escrita na linha é o que diz isso.

Desligar funciona de um jeito diferente em cada CLI:

Nos dois primeiros é reversível e visível no disco: dá para desfazer à mão, sem o Satori. No OpenCode a skill continua aparecendo na lista mesmo negada, com o estado ao lado.

Skills de plugin e as que vêm com o CLI aparecem marcadas e sem interruptor: elas são reinstaladas a cada atualização, então desligar por aqui não duraria.

Pasta sem SKILL.md legível aparece marcada sem SKILL.md em vez de sumir da lista.

A alteração vale para a próxima sessão do CLI. Uma sessão já aberta no terminal continua com o que carregou ao iniciar.

Agents

Lista os subagents do perfil do Claude Code e do Codex com nome, descrição, modelo e quantas ferramentas cada um pode usar (passe o mouse na etiqueta para ver quais).

Ver abre o conteúdo do arquivo, que às vezes é grande demais para a lista.

O interruptor liga e desliga igual ao das skills, e pelo mesmo motivo: não existe "agent desabilitado" nos CLIs. Desligar move o arquivo para <perfil>/agents-desativados/, e ligar traz de volta. No Codex, os dois arquivos de cada agent (.md e .toml) se movem juntos.

Agents que vêm de plugins não aparecem aqui, porque não ficam na pasta agents/ do perfil. Por isso a contagem desta tela pode ser menor que a que você vê no CLI.

MCP

Lista os MCP servers do perfil (Claude Code ou Codex): nome, transporte, comando e os nomes das variáveis de ambiente que ele usa. Os valores não são exibidos, porque costumam ser segredo.

Testar conexões (no Claude Code) roda a verificação de saúde do CLI e marca cada servidor como conectado ou falhou. Demora alguns segundos.

Adicionar um servidor

+ Servidor abre o formulário:

No Codex o formulário é menor, porque ele aceita menos: não há transporte sse nem headers.

O Satori adiciona pelo subcomando do próprio CLI (claude mcp add --scope user ou codex mcp add) e nunca escreve direto no arquivo de configuração, que o CLI reescreve enquanto roda. Se o CLI recusar, o erro aparece dentro do formulário e nada é adicionado; a janela só fecha quando deu certo.

Remover

O botão Remover de cada linha pede confirmação: o primeiro clique troca o rótulo para Confirmar, e só o segundo remove. Sem confirmar em 4 segundos ele volta ao normal.

A remoção vale só para os servidores do perfil (escopo user), que são exatamente os que esta tela lista. Um servidor herdado de um projeto ou vindo do Claude.ai não é removível por aqui.

O seletor de perfil das telas

Skills, Agents, MCP e Histórico têm um chip de perfil no canto superior esquerdo, compartilhado entre as quatro: trocar em uma vale para todas. Ele começa no perfil do chat ativo e não mexe no chat.

Configurações

A engrenagem da faixa abre um modal com nove abas. A conversa continua visível atrás, e o Esc devolve você para a tela em que estava. A busca do topo procura em todas as abas de uma vez.

A escala funciona como o zoom do navegador: amplia texto e controles juntos. A densidade muda só o espaço entre as mensagens, sem diminuir a letra.

Um chat novo herda do chat aberto por padrão (conta, CLI, modo e pasta). Desligue Copiar do chat aberto para que todo chat nasça igual, com os padrões definidos na mesma aba.

Orquestração

Manda o mesmo pedido para vários CLIs ao mesmo tempo e mostra as respostas lado a lado. Serve para auditoria cruzada: pedir ao Codex que revise o que o Claude fez, e vice-versa.

1. Escreva o pedido (ex.: "audite o diff atual e aponte problemas")
2. Marque os CLIs (todos vêm marcados)
3. Disparar

Cada CLI vira uma coluna com indicador de andamento enquanto roda, ✓ ou ✕ no fim, e o tempo que levou. Cada um é um processo independente, com sua própria conta e contexto: a segunda opinião não compartilha o viés da primeira.

CLIs suportados: Claude Code, Codex e OpenCode; os que estiverem instalados aparecem na lista. Um CLI que falha (conta sem acesso, por exemplo) mostra o erro na coluna dele em vez de sumir.

A pasta da corrida

O chip de pasta, ao lado das pílulas dos CLIs, diz onde as corridas rodam. Há duas opções: Escolher pasta…, que fixa uma e vale até você trocar, e Seguir o chat ativo, em que o chip fica com a borda tracejada porque a pasta muda junto com a conversa.

Os CLIs rodam sem trava na orquestração. Eles leem e escrevem arquivos na pasta da corrida, rodam comandos e acessam a web sem pedir permissão, porque não há como responder a um pedido de permissão numa corrida. Confira a pasta antes de disparar um pedido que mexe em arquivo.

Tempo limite

⏱ é diferente de ✕. Cada CLI tem um teto de tempo, e quem estoura é interrompido: a coluna fica amarela, diz sem terminar ao lado do tempo, e o corpo começa explicando em quantos minutos parou, com o que ele tinha produzido até ali logo abaixo. Não é falha do CLI; é tempo que não coube.

O teto padrão é 15 minutos e fica em Configurações › Geral. Zero desliga o relógio: aí quem decide quando parar é o botão parar de cada coluna.

Consolidar e continuar

Consolidar manda as respostas de todos para um CLI julgar, e devolve onde eles concordam, onde divergem e o veredito. Você escolhe o júri na própria lista do botão: escolher é o que dispara, porque isso gasta um turno da conta escolhida. O veredito fica guardado junto da corrida (reabri-la traz o julgamento de volta, sem pagar de novo) e o Exportar o leva no fim do arquivo.

abrir chat leva a resposta de uma coluna para um chat daquele mesmo CLI, na pasta da corrida, com o pedido e a resposta já na tela. O veredito tem o mesmo botão, e ali ele abre o chat com o CLI que julgou.

O pedido e a resposta (ou o veredito) entram no seu primeiro envio naquele chat, junto com o que você escrever, então o CLI responde já sabendo do assunto. O chat é novo: o que ele sabe da corrida é o que foi junto ali.

Textos muito grandes são cortados, e o corte aparece escrito no pedido. Codex e OpenCode recebem a mensagem como argumento de linha de comando, e o Windows tem um limite para ela.

Segredos

Segredos conhecidos são removidos do que o Satori guarda e exporta: se uma resposta trouxer algo como ANTHROPIC_API_KEY=…, Authorization: Bearer … ou uma chave no formato sk-…/ghp_…, ela aparece como [redigido] na coluna, no arquivo exportado e no que vai para o júri do Consolidar.

Isso protege o que SAI do Satori, não a conversa. O agente leu o arquivo, e o texto está no histórico do próprio CLI. Um segredo que chegou ao agente continua exposto: troque a chave.

Corridas e exportação

As corridas ficam guardadas. O chip Corridas, ao lado de Verificar CLIs, lista as últimas vinte: escolha uma e as colunas voltam como estavam, com a conta e o tempo de cada CLI daquela vez, e o pedido acima delas.

Exportar salva a comparação inteira num .md: o pedido e o que cada CLI respondeu, na ordem das colunas. Vale para a corrida que acabou de rodar e para uma reaberta. O salvar de cada coluna salva só uma resposta. O botão só aparece com a corrida terminada.

Verificar CLIs

O botão Verificar CLIs mostra, para cada um, a versão instalada e o estado da conta:

Não consome nada: nenhum turno, nenhum token. O Codex responde por codex login status, o OpenCode por opencode auth list, e o Claude Code pelo arquivo de credencial do perfil.

Por isso o perfil importa: a conta do Claude Code é por perfil, e o seletor no alto da tela decide qual está sendo verificado. Trocar de perfil e verificar de novo pode dar respostas diferentes, porque são contas diferentes.

Nenhum token sai do lugar, nem para a tela, nem para o log.

Avisos do sistema

Turno longo termina, permissão fica esperando, orquestração acaba: se a janela do Satori não estiver em foco, o Windows mostra uma notificação.

Com a janela em foco não há aviso, de propósito: quem já está olhando a tela não precisa de notificação.

Atualizações

Ao abrir, o Satori consulta se existe versão nova. Se houver, aparece uma janela com a versão atual, a nova e o que mudou, e duas opções. Nada é baixado antes de você mandar.

• Atualizar e reiniciar: o app baixa o instalador, instala e volta sozinho. O andamento aparece na própria janela; leva algum tempo, e a janela parada não é travamento.
• Agora não: fecha e não muda nada. A pergunta volta na próxima abertura.

Para procurar uma versão nova sem reabrir o app, use Configurações › Sobre › Procurar atualização.

Sem internet, ou com o GitHub fora do ar, o app abre normalmente e não diz nada.

O pacote é assinado, e o app recusa qualquer atualização cuja assinatura não confira. Um instalador trocado no meio do caminho não roda.

Todas as versões publicadas ficam em github.com/Satori-Harness/satori-releases/releases.

Atalhos

No Canvas:

Quando algo dá errado

"Falta instalar o Claude Code" com ele instalado

A detecção procura o claude no PATH. Se ele foi instalado numa pasta fora dele, aponte o executável em Configurações › CLIs & Provedores › Apontar…. O mesmo vale para o Codex e o OpenCode.

Um CLI aparece sem conta

Use Verificar CLIs na Orquestração ou Verificar contas em Configurações › CLIs & Provedores. Bolinha vermelha é falta de login: entre pelo botão Entrar… da mesma aba (ou, no Claude Code, pelo perfil em Configurações › Perfis).

O agente diz que não tem acesso às ferramentas

Às vezes o agente não acha um arquivo e conclui que não tem as ferramentas de disco, o que é falso. Verifique as linhas de ferramenta: elas mostram o que ele realmente chamou e o que recebeu. Repetir o pedido citando a pasta costuma resolver.

"limite de uso da conta atingido"

É o limite de uso da conta daquele perfil. Troque de perfil ou espere a janela de 5 h virar.

"a pasta de trabalho desta conversa não existe mais"

Você retomou uma conversa do Histórico cuja pasta foi apagada ou movida desde então. Abra um chat novo na pasta certa; a conversa antiga continua legível e exportável no Histórico.

Um erro do OpenCode com número em vez de explicação

Falhas do provedor do OpenCode (por exemplo 503 … Endpoint is unavailable) aparecem com o texto que ele mesmo reportou. Um 503 é indisponibilidade temporária do lado deles: tentar de novo costuma resolver. Se aparecer só código 1, sem texto, o CLI não disse nada; rode o mesmo pedido pelo terminal para ver a saída completa.

Um cartão de arquivo não apareceu

Três causas comuns: o arquivo já estava no estado pedido e nada mudou; a alteração foi feita por Bash em vez de Write/Edit; ou o arquivo é binário.

Um hook do meu perfil bloqueou alguma coisa

É para bloquear mesmo: os guards do seu settings.json valem aqui dentro. A conversa mostra qual comando decidiu e por quê; o texto completo aparece ao passar o mouse sobre o balão.

Se um hook falhar (erro de digitação no caminho, script que não existe), o Satori avisa e segue em vez de travar.

Hooks de SessionStart também rodam, e quem dispara depende do provedor:

• no chat do Claude é o próprio Claude Code, como no terminal: ele lê o seu settings.json, roda os hooks ao abrir a sessão e põe o que eles imprimem no contexto. É assim que hooks de memória e de modo de trabalho continuam valendo aqui. A conversa só fala de hook que recusou ou falhou;
• no chat do Codex e do OpenCode é o Satori, no primeiro turno, antes de o agente ver sua pergunta. Os efeitos valem (o hook que grava memória grava igual), mas o que ele imprime não entra na conversa. No primeiro envio o chat diz quantos hooks do perfil valem ali e quais ficam de fora.

Uma exceção: hooks de FileChanged não rodam no Satori.

A janela abre e nada responde

O app registra o motivo em:

%LOCALAPPDATA%\dev.satori\logs\satori.log

A última linha costuma dizer exatamente o que faltou. Ctrl+R recarrega a interface sem fechar o app.