Modo discreto
Como /narsil discreto silencia a Narsil sem perder os alertas que importam: o que para, o que ainda passa, e por que a linha é traçada em "ela precisa de você".
O que faz
A Narsil fala muito, de propósito: ela fala quando o trabalho começa e termina, alerta quando um turno acaba, dá dicas, propõe próximos passos e resume a sessão. Num dia de reuniões, ou simplesmente num escritório compartilhado, isso é demais.
/narsil discreto (“discreto”) reduz tudo isso de uma vez. Ela para de falar, para de alertar quando um turno termina e para de oferecer dicas e próximos passos por conta própria. Ela ainda alerta você, sem voz, quando precisa de você ou quando algo falhou, e a faixa continua mostrando o que ela está fazendo. /narsil normal traz tudo de volta como estava.
A Narsil tem três formas de dar um passo atrás, e ajuda distingui-las:
| Comando | O que muda |
|---|---|
/narsil silencio |
Só a voz. Todo alerta, dica e passo continua chegando, por escrito. |
/narsil ocultar |
Só a faixa. A voz e os alertas continuam. |
/narsil discreto |
Voz desligada, alertas de fim de turno desligados, extras automáticos desligados; o resto fica. |
Cada um tem o seu oposto: voz, mostrar e normal. São interruptores independentes, então /narsil normal desliga o modo discreto sem religar uma voz silenciada.
Como funciona por dentro
Uma preferência: isQuiet
O modo discreto é um único booleano, isQuiet, no atom prefs de hooks/register.tsx (o seu tipo, Prefs, está em types/index.d.ts). O handler do comando /narsil o escreve por meio de uma pequena tabela:
const change: Record<string, Partial<Prefs>> = {
ocultar: { isHidden: true },
mostrar: { isHidden: false },
silencio: { isMuted: true },
voz: { isMuted: false },
discreto: { isQuiet: true },
normal: { isQuiet: false },
}
O patch é mesclado no atom e o objeto prefs inteiro é salvo com $.store.set('prefs', …), então o modo dura entre sessões até você mudá-lo. Em session.start, as preferências guardadas são mescladas sobre os padrões, o que também cobre valores guardados mais antigos que ainda não têm o campo.
Não há um caminho de código “discreto” próprio. Em vez disso, cada lugar que faz barulho lê isQuiet e decide por si. Isso mantém a regra ao lado daquilo que ela governa, e significa que um novo tipo de barulho precisa aderir explicitamente ao modo discreto.
A linha que ele traça: “precisa de você” passa
Todo alerta passa por announce (o guia 6 o cobre por completo). As suas primeiras linhas são onde o modo discreto vive:
const { isMuted, isFloating, isQuiet } = await read($, prefs)
// Quiet: no voice, and only what needs you (a question, an error) is told.
if (isQuiet && kind === 'done' && !force) return
const spoken = isMuted || isQuiet ? Promise.resolve() : speak($, voice)
Um alerta tem um de três tipos: done, question ou error. No modo discreto:
- um alerta
doneretorna antes de qualquer coisa acontecer: nem janela flutuante, nem notificação do sistema, nem celular, nem voz; - um
questionou umerrorsegue como de costume para a janela flutuante (ou uma notificação do sistema quando a janela está desligada) e para o celular, só que sem a voz.
O motivo dessa linha está no comentário e no README: o que para é o que você pode perder com segurança. Um turno terminado ainda estará terminado quando você olhar. Uma pergunta ou uma permissão bloqueia o trabalho até você responder, e um erro significa que o trabalho parou. Silenciá-los transformaria um modo discreto num modo quebrado.
A flag force deixa dois chamadores passarem mesmo assim. /narsil prueba (“teste”), o alerta de teste, é forçado, para que você possa conferir os seus alertas mesmo no modo discreto. O lembrete de cinco minutos para uma permissão ou pergunta deixada esperando também é forçado, embora, como question, passaria de qualquer forma.
O que cada tipo de alerta faz no modo discreto
Percorrendo os chamadores de announce:
| Momento | Tipo | Modo discreto |
|---|---|---|
| Um turno termina (“He terminado”, “Terminei”) | done |
barrado |
| Um subagente em segundo plano termina bem | done |
barrado |
| Um subagente em segundo plano para ou falha | error |
mostrado, sem voz |
| Um turno falha (“Me he detenido”, “Parei”) | error |
mostrado, sem voz |
| Uma pergunta, um plano ou uma permissão | question |
mostrado, sem voz |
| Um turno termina perguntando na caixa de próximo passo | question |
mostrado, sem voz |
| Ainda esperando depois de 5 minutos | question |
mostrado, sem voz |
/narsil prueba |
done |
mostrado (forçado), sem voz |
Os outros barulhos
Fora de announce, mais quatro lugares leem isQuiet:
- A voz no início do trabalho. Em
turn.start, um prompt que você digitou faz com que ela diga uma frase de início, a menos queisMutedouisQuiet. - Dicas automáticas.
mayTipretorna false quandoisQuiet, antes de contar qualquer coisa. Uma dica que você pede com/narsil consejonão é automática e continua respondendo. - Próximos passos.
offerStepsretorna na hora quandoisQuiet. - O resumo da sessão ociosa.
tickWatchmostra o resumo depois de 30 minutos de calma só quandoisQuieté false./narsil resumencontinua respondendo.
O que o modo discreto não toca
Ler o código também diz o que fica, e vale a pena saber:
- A faixa e o conteúdo da janela flutuante. Estados, manchetes, comentários, a lista de conversas, o relógio do cache e a comemoração de uma subida de nível são desenhados como antes. O modo discreto trata de interrupções, não de informação.
- A sugestão de
/compactdo guia 7. Ela é conferida comisAdviceOn, não comisQuiet, então ainda pode aparecer no modo discreto./narsil consejos offa interrompe. - O aviso sobre comandos perigosos do guia 9: é um comentário na faixa e uma linha de log, não um alerta.
- O estado silencioso enviado ao tópico
-estadodo celular (guia 15). Ele nunca gera uma notificação e, enquanto os alertas no celular estão ligados e você escreve de longe, é enviado depois de cada turno, qualquer que seja o modo.
Quando o modo está ligado, o comando /narsil sozinho acrescenta uma linha ao seu relatório: “Modo discreto activado: sin voz, sin avisos de fin de turno ni consejos o pasos automáticos.” (“Modo discreto ativado: sem voz, sem alertas de fim de turno nem dicas ou passos automáticos.”)
Como foi pedido à IA
O pedido original do modo discreto não foi registrado. Os registros públicos de tarefas do projeto não o cobrem.
Reconstrução a partir do histórico de commits
A partir de git log -S isQuiet -- hooks/register.tsx no narsil-pet:
17ffb30(2026-10-31) “feat: add a quiet mode that only speaks up when Narsil needs you” (acrescentar um modo discreto que só se manifesta quando a Narsil precisa de você). Um único commit acrescenta o modo inteiro: o campoisQuiet, o retorno antecipado emannounce, as verificações nas dicas, nos próximos passos e no resumo ocioso, as palavrasdiscretoenormal, a linha no relatório do comando sozinho, uma seção do README e um teste. O seu assunto é o design numa frase.665bd4e(2026-11-06) “feat: speak when work starts and vary every spoken phrase” (falar quando o trabalho começa e variar cada frase falada). A voz de início do trabalho é nova aqui, e lêisQuietdesde o primeiro dia. Este é o padrão em ação: um novo barulho adere ao modo discreto quando é acrescentado.
O modo chegou no fim da primeira semana, depois que a voz, os alertas, as dicas e os próximos passos já existiam. Essa ordem se encaixa num caminho comum: um mod ganha funcionalidades uma de cada vez, e só quando elas se acumulam ele precisa de um único interruptor para reduzi-las.
Um prompt que você pode usar
O prompt a seguir foi escrito para este guia como sugestão. Não é o prompt da pessoa autora.
O meu mod do Claude Code
my-petfala, alerta no fim de cada turno e mostra dicas. Acrescente um modo discreto:/my-pet quiete/my-pet normaldefinem um booleanoisQuietnas preferências, salvo com$.store.sete carregado emsession.start. Na função que envia todo alerta, que recebe um tipo (done,question,error), retorne antecipadamente paradonequando estiver discreto, a menos que o alerta seja um teste forçado, e nunca fale quando estiver discreto; perguntas e erros continuam aparecendo. Pule também as dicas automáticas quando estiver discreto, mas mantenha as dicas que a pessoa pedir. Deixe a faixa como está. Acrescente testes comclaude-code/testing: no modo discreto, um turno terminado não gera notificação nem voz, e uma chamadaAskUserQuestionainda notifica.
O código mínimo
Escrito para este guia e conferido com os tipos da 2.1.325 ($.store.get, $.store.set, $.command.register, command.run, $.ui.notify, session.start, turn.complete, tool.call). Foi adaptado de hooks/register.tsx do narsil-pet (GPL-3.0-or-later). O atom prefs está declarado em types/index.d.ts como { isQuiet: boolean }. A função vazia speak é onde vai a sua própria voz, como a do guia 6.
import { atom, read, update } from 'claude-code'
import type { EngineInterface, Register } from 'claude-code'
type Kind = 'done' | 'question' | 'error'
const prefs = atom({ plugin: 'my-pet', key: 'prefs' } as const, { isQuiet: false })
async function speak($: EngineInterface, text: string): Promise<void> {
// your own voice goes here (guide 6)
}
async function announce(
$: EngineInterface,
kind: Kind,
title: string,
text: string,
force = false,
) {
const { isQuiet } = await read($, prefs)
// What you can safely miss stays quiet; what blocks the work never does.
if (isQuiet && kind === 'done' && !force) return
const spoken = isQuiet ? Promise.resolve() : speak($, text)
try {
await $.ui.notify(text, { title })
} catch {
// no notification channel on this surface
}
await spoken
}
export const register: Register = (on) => {
on('session.start', async ($, e, next) => {
await $.command.register({ name: 'my-pet', description: 'My pet: quiet | normal | test' })
const saved = await $.store.get('prefs').catch(() => undefined)
if (saved && typeof saved === 'object') await update($, prefs, (p) => ({ ...p, ...saved }))
return next(e)
})
on('command.run', { command: 'my-pet' }, async ($, e) => {
const arg = e.args.trim().toLowerCase()
if (arg === 'test') {
await announce($, 'done', 'Test', 'This is how I will tell you.', true)
return { text: 'My pet: test alert sent.' }
}
if (arg !== 'quiet' && arg !== 'normal') return { text: 'Usage: /my-pet quiet | normal | test' }
const saved = await update($, prefs, (p) => ({ ...p, isQuiet: arg === 'quiet' }))
await $.store.set('prefs', saved).catch(() => undefined)
return {
text: saved.isQuiet
? 'My pet: quiet. I only tell you when I need you.'
: 'My pet: back to normal.',
}
})
on('tool.call', async ($, e, next) => {
if (e.agentId === undefined && e.tool === 'AskUserQuestion')
await announce($, 'question', 'I need you', 'I have a question for you.')
return next(e)
})
on('turn.complete', async ($, e, next) => {
const result = await next(e)
if (e.agentId !== undefined) return result
if (e.reason === 'answer') await announce($, 'done', 'Done', 'I have finished.')
else if (e.reason !== 'aborted')
await announce($, 'error', 'I stopped', 'The turn ended with an error.')
return result
})
}
update retorna o novo valor, então o comando salva exatamente o que escreveu. O try em volta de $.ui.notify segue um comentário no notify da Narsil: onde o host não tem nenhum notify, “the call throws before it returns a promise” (a chamada lança uma exceção antes de retornar uma promise), então um .catch não a capturaria.
Erros comuns e como testar
- Silenciar tudo. Um modo discreto que também barra perguntas e erros deixa o Claude esperando uma permissão que ninguém vê. Decida por tipo de alerta, conforme perdê-lo bloqueie ou não o trabalho.
- Uma flag num só lugar. Se só a função de alerta lê a flag, todo barulho acrescentado depois a ignora. A Narsil lê
isQuietem cada lugar que faz barulho, e acrescenta a verificação quando acrescenta o barulho. - Deixar o modo discreto barrar o teste. Sem
force,/narsil pruebanão faria nada no modo discreto, e a pessoa pensaria que os alertas estão quebrados. - Acoplar interruptores.
normaldeve desfazer sódiscreto. Se também religasse a voz, uma pessoa que tivesse silenciado a Narsil antes voltaria a ouvi-la. - Esquecer de persistir. Uma preferência guardada só num atom some na próxima sessão.
Para testar, tests/narsil.test.tsx tem dois testes para isso. “/narsil discreto keeps her quiet, and /narsil normal brings everything back” (/narsil discreto a mantém calada, e /narsil normal traz tudo de volta) roda num macOS simulado sem a janela flutuante, registra os scripts iniciados para a voz e as notificações, termina um turno e deixa passar onze minutos: nada é falado, nenhuma notificação começa, nenhum modelo é consultado; depois, uma chamada AskUserQuestion gera exatamente uma notificação com o título “Narsil · Te necesito” (“Narsil · Preciso de você”). “in quiet mode the phone gets only what needs you” (no modo discreto, o celular recebe só o que precisa de você) confere a mesma regra no celular: depois de um turno terminado e de uma pergunta, só a pergunta é publicada.
Para ir além
announceemhooks/register.tsxé a única função a ler para saber para onde vai cada alerta; o guia de voz e alertas a percorre.- O comando
/narsilsozinho imprime todas as preferências de uma vez, incluindo esta. O último guia da trilha, sobre comandos, mostra como ele é construído. - O próximo guia envia os mesmos alertas ao seu celular e ao seu relógio, sob a mesma regra do modo discreto.
Para ir além: como o mod real faz
Estes arquivos fazem parte dos mods originais, publicados sob a GPL v3. O código citado nesta página vem deles e mantém essa licença.
Este guia ajudou?
Todos os guias são gratuitos. Se este poupou seu tempo, você pode me pagar um café.
Me pague um café