v0.2.0 - Alpha

Atenção é tudo o que o modelo possui.
Foco é tudo o que o niuma_code faz.

Em 2017, “Attention is All You Need” definiu uma era — toda inteligência de modelos é construída sobre atenção. 8 anos depois, percebemos que os modelos não carecem do mecanismo de atenção — eles carecem de colocar a atenção no lugar certo. Quanto mais longo o contexto, mais o ruído dilui a informação verdadeiramente importante. O niuma_code faz uma coisa: comprime o contexto e adiciona foco — para que cada token chegue onde deveria estar.

🔒
Execução local
Dados não saem da sua máquina — controle total de privacidade
🛡️
Privacidade em primeiro lugar
Chaves de API armazenadas localmente, dados de conversa não são enviados
📦
v0.2.0 Alpha
Em melhoria contínua, liderado pela comunidade
💬
Suporte da comunidade
GitHub Issues — contato direto com os desenvolvedores

Veja em ação

Gravação de tela real do modo de orquestração IDE — teste o foco do niuma_code em 1 minuto

Por que escolher o niuma_code

Não é um substituto do Claude Code — é uma ferramenta complementar que potencializa o foco

⚙️

Modo Harness autônomo

Modo padrão — sem comandos necessários. O LLM explora autonomamente dentro de um loop de ferramentas, agindo enquanto pensa, até concluir a tarefa.

  • Loop de tool-use: O LLM decide autonomamente ler arquivos / editar código / executar comandos
  • Retry automático em erros de API, renderização em streaming + cancelamento com ESC + compressão automática de saídas longas
  • Ideal para tarefas ambíguas e difíceis de decompor — o LLM decide quando está completo
🔁

Orquestração de engenharia Loop

Com /loop <objetivo>, entra em um self-loop orientado a objetivos: planeja com comandos de verificação, executa sequencialmente, verifica cada etapa e se autocorrige em caso de falha.

  • Planejar -> Executar -> Verificar -> Retry em falha (até 3 vezes, com motivo da falha como feedback)
  • Portão ortogonal duplo: MAX_ROUNDS=20 limite de tarefas + MAX_RETRIES=3 autocorreção
  • Cada rodada invoca o harness para executar uma etapa — ideal para tarefas de engenharia decomponíveis e verificáveis
🖥️

Modo TUI tela cheia

Baseado em interface de tela cheia com prompt_toolkit. A entrada é sempre fixada na parte inferior, permitindo adicionar novas mensagens a qualquer momento durante o streaming do LLM — o conteúdo nunca é empurrado para fora.

  • 5 sobreposições modais: configuração de modelo, fila de mensagens, troca de contexto, gerenciamento de conversas, confirmação de permissão
  • Seleção por arrasto do mouse com destaque, navegação por scroll, cópia automática com clique esquerdo, zoom de fonte com Ctrl+scroll
  • Barra de status em tempo real: preview do pensamento, contagem de tokens de entrada/saída, progresso de compressão + cancelamento com ESC
💻

Modo de orquestração IDE

Editor de código em tela cheia. Escreva scripts de orquestração em Python nativo e integre chamadas de LLM em um fluxo de trabalho controlável por script.

  • Injeção de funções llm_call / llm_confirm / llm_judge para orquestração LLM controlável
  • F5 para preview (análise estática AST), F6 para execução (sem supervisão, permissões de ferramentas auto-concedidas)
  • Execução em sandbox seguro + lista negra de importações perigosas (os/subprocess/socket etc.) — única rede de segurança no modo sem supervisão
🔌

Roteamento multi-provedor

Configure múltiplos endpoints de API no settings.json — as requisições são roteadas automaticamente para o provedor correto com base no nome do modelo, com troca livre durante a sessão.

  • Cada provedor declara base_url / api_key / lista de modelos suportados
  • #tag ou /model para trocar de modelo — as requisições se conectam automaticamente ao endpoint correto
  • Cascata de configuração em 3 camadas (nível usuário / nível projeto / projeto local), a última definida tem prioridade
🗂️

Gerenciamento paralelo de contexto

Expande única conversa em N contextos paralelos, cada um gerenciando independentemente histórico, contagem de tokens e estado de compressão — zero contaminação cruzada.

  • Evicção LRU, limite padrão de 5 (configurável via max_contexts) — evicção = arquivado e restaurável
  • Alternância via sobreposição visual /context; geração de resumo assíncrono ao sair
  • /messages para seleção múltipla por unidade — exclusão / reordenação / integração de resumo LLM
🕸️

Grafo de conhecimento de código

Analisa a estrutura do código com base no tree-sitter, construindo definições de símbolos, cadeias de chamadas e grafos de dependências — identifica a posição exata antes que o LLM leia as linhas.

  • 4 ferramentas de consulta somente leitura: busca de símbolos, dependências de arquivo, referências, cadeias de chamadas
  • Retorna arquivo:número de linha e assinatura — substitui a abordagem de procurar agulha no palheiro do grep
  • Decisão de rebuild sob demanda em 3 critérios — evita parsing completo na inicialização
🤖

Pesquisa paralela com sub-agentes

Sub-agentes somente leitura executam ferramentas em paralelo, pesquisam em contextos isolados e retornam apenas resumos — o contexto principal permanece limpo.

  • Múltiplos sub-agentes executam ferramentas somente leitura em paralelo, sem bloqueio
  • Pesquisa em contexto isolado, apenas resumos — não polui a conversa principal
  • Pertence ao paradigma padrão do harness, invocado sob demanda e não em modo independente
🧠

Memória percepção-orientada

Memória persistente com memory-palace — eventos durante a execução são capturados em tempo real como memórias, acumulando experiência entre sessões.

  • 10 tipos de eventos perceptivos (visual/corporal/língua/nariz/resultados etc.), escritos em tempo real e não após a conversa
  • Trios de fatos + resumo de conversa, recuperação em 4 camadas + decaimento bayesiano
  • Injeção automática no prompt do sistema na próxima sessão, posição estável de recall
🎯

Rastreamento de recompensa por resultado

Rastreia todo o ciclo de vida do objetivo da tarefa, calcula pontuação de recompensa com base na qualidade de conclusão e grava como evento perceptivo na memória.

  • OutcomeTracker calcula pontuação de recompensa de 0.0 a 1.0 em todo o ciclo de vida da tarefa
  • A pontuação de recompensa serve como sinal de avaliação de reutilização da memória
  • Como um dos 10 eventos perceptivos, integrado com eventos de read/write/tool-call

Como aproveitar ambos os modos de forma eficaz

Quando as etapas não estão claras, descreva e itere (harness). Quando tiver uma lista de verificação, use /loop

🧭

Pontos-chave do harness

O harness não tem loop de replanejamento — quanto mais clara a entrada, mais precisa a exploração autônoma.

Caso de uso: Tem uma ideia geral mas não consegue articular as etapas claramente e quer avançar iterativamente. Exemplo: "Encontre e corrija o erro na página de login"
  • Especifique restrições com antecedência: objetivo + arquivos/funções que não devem ser tocados + critérios de aceitação — não altere requisitos durante a execução
  • Ideal para fronteiras ambíguas mas objetivo claro; quanto mais claras as etapas, mais rápido a convergência
  • Use os pontos de controle: ESC para parar a qualquer momento, saídas longas são comprimidas automaticamente, erros de API são retryados automaticamente
  • "Concluído" e "verdadeiramente concluído" são coisas diferentes — execute testes/compilação você mesmo após mudanças importantes
🎯

Pontos-chave do loop

A autocorreção depende inteiramente da "verificação" — apenas objetivos verificáveis tornam as 3 tentativas significativas.

Caso de uso: Pode decompor a tarefa em etapas e cada etapa tem um método de verificação de correto/errado. Exemplo: "/loop Adicione paginação à API de usuários e execute após as alterações"
  • O objetivo deve ser decomponível em etapas com comandos de verificação — "refine mais" não é verificável
  • Descreva o método de verificação diretamente no objetivo (py_compile / testes) para máxima precisão de planejamento
  • 3 falhas de correção geralmente significam informações de verificação insuficientes — em vez de se esforçar mais, decompost mais
  • Não pare nas 3 falhas — são registradas e o loop continua; verifique o marcador [!!] no resumo

3 passos para começar

Download, configuração e inicialização — pronto em segundos

01 Download
⬇ Baixar niuma.exe
Windows · Sem instalação · Execução imediata
02 Configuração
# ~/.niuma/settings.json
{
  "factories": [{
    "api_key": "your-key"
  }]
}
03 Inicialização
$ niuma.exe
niuma_code v0.2.0 launched

Lista de parâmetros do settings.json

Caminho do arquivo de configuração: ~/.niuma/settings.json

factoriesConfiguração de API multi-provedor. Cada provedor declara base_url / api_key / lista de modelos suportados; as requisições são roteadas automaticamente pelo nome do modelo
💡 Exemplo de configuração
{
  "factories": [
    {
      "base_url": "https://api.anthropic.com",  // Anthropic official endpoint
      "api_key": "sk-ant-xxx",                   // Required; all three fields must be present
      "options": ["claude-sonnet-4-6", "claude-opus-4-8"]  // Supported models for this provider
    },
    {
      "base_url": "https://your-proxy.example.com",  // Anthropic-compatible proxy endpoint
      "api_key": "sk-proxy-xxx",
      "options": ["claude-sonnet-4-6"]  // Supported models for this endpoint
    }
  ]
}
Parâmetro Tipo Padrão Descrição
base_url string --- URL do endpoint da API (obrigatório)
api_key string --- Chave de API (obrigatório)
options string[] [] Nomes dos modelos suportados por este provedor
llmModelo, nível de esforço, orçamento de pensamento e gerenciamento de contexto
💡 Exemplo de configuração
{
  "llm": {
    "default_model": "claude-sonnet-4-6",   // Default value for /model switch
    "default_effort": "high",               // Determines which thinking_budget is used
    "max_contexts": 5,                      // Max parallel contexts; LRU eviction beyond limit
    "resume_latest_context": true,          // Resume last active context on startup
    "options": [                            // Model -> effort mapping
      {"claude-sonnet-4-6": ["low", "medium", "high"]},
      {"claude-opus-4-8": ["low", "medium", "high", "max"]}
    ],
    "thinking_budget_low": "0",             // 0 = disable extended thinking
    "thinking_budget_medium": "0",
    "thinking_budget_high": "10000",        // Thinking budget for high effort
    "thinking_budget_max": "20000"           // Thinking budget for max effort (deepest reasoning)
  }
}
Parâmetro Tipo Padrão Descrição
default_model string "claude-sonnet-4-6" Modelo padrão (fixo durante a sessão, trocável via /model)
default_effort string "high" Nível de esforço padrão — controla a profundidade do orçamento de pensamento
max_contexts integer 5 Número máximo de contextos paralelos ativos; evicção LRU quando excedido
resume_latest_context boolean true Restaurar o último contexto ativo ao iniciar; false = iniciar do zero
options object[] [] Mapeamento modelo->esforço, usado para validação na troca via /model
thinking_budget_low string/int "0" Orçamento de tokens de pensamento no esforço low (0 = desabilitado)
thinking_budget_medium string/int "0" Orçamento de tokens de pensamento no esforço medium
thinking_budget_high string/int "10000" Orçamento de tokens de pensamento no esforço high
thinking_budget_max string/int "20000" Orçamento de tokens de pensamento no esforço max (raciocínio mais profundo)
envVariáveis de ambiente gravadas no os.environ. Controlam persona, depuração, rede e comportamento de permissões
💡 Exemplo de configuração
{
  "env": {
    "PERSONA_NAME": "niuma",              // AI persona name, injected into system prompt
    "MODEL_BACKGROUND": "claude-haiku-4-5", // Background task model (memory extraction, compression, etc.)
    "LANG": "zh",                        // UI language (zh/en); also controls LLM response language
    "TEMPERATURE_ZERO": "true",            // Note: all values are strings
    "API_TIMEOUT": "30",                   // Streaming stall timeout (seconds)
    "API_ROUND_MAX": "120",                // Per-turn wall-clock hard limit (seconds)
    "API_STALL_MAX_RETRIES": "10",        // Max auto-retries on stream stall
    "PERMISSION_MODE": "auto",             // auto=whitelist+confirm / manual=whitelist only / skip=allow all
    "ALLOWED_TOOLS": ""                    // Whitelisted tools (comma-separated); empty = built-in defaults
  }
}
Parâmetro Tipo Padrão Descrição
PERSONA_NAME string "niuma" Nome da persona injetado no prompt do sistema
MODEL_BACKGROUND string "claude-haiku-4-5" Modelo para tarefas em segundo plano (extração de memória, compressão, etc.)
LANG string "en" Idioma da interface (zh/en); também controla o idioma de resposta do LLM
TEMPERATURE_ZERO string(bool) "true" Fixar temperature=0 para saída determinística; false = padrão do modelo
API_TIMEOUT string/int "30" Timeout de estagnação do streaming (segundos) — reconectar se não houver eventos
API_ROUND_MAX string/int "120" Limite rígido de relógio por turno (segundos) — forçar o fim de streams antigos
API_STALL_MAX_RETRIES string/int "10" Número máximo de retries automáticos em caso de estagnação do stream
PERMISSION_MODE string "auto" Modo de permissão: auto (lista de permissões+confirmação) / manual (apenas lista de permissões) / skip (permitir tudo)
ALLOWED_TOOLS string "" Lista de permissões de ferramentas separadas por vírgula; vazio = padrões integrados
compactCompressão de contexto: comprime conversas longas automaticamente para manter informações importantes
💡 Exemplo de configuração
{
  "compact": {
    // -- Inline compression (blocks main loop until done) --
    "inline_trigger": 0.8,      // Triggers at 80% of MAX_TOKENS
    "inline_keep_ratio": 0.4,   // Keep latest 40% of messages after compression

    // -- Post-reply async compression (non-blocking, runs in background) --
    "idle_trigger": 0.5,        // Triggers at 50% of MAX_TOKENS
    "idle_keep_ratio": 0.4,     // Keep latest 40% of messages after compression

    // -- LLM summary output limit --
    "max_summary_tokens": 4096  // Max tokens for generated summary
  }
}
Parâmetro Tipo Padrão Descrição
inline_trigger float 0.8 Taxa de gatilho da compressão inline — bloqueia o loop principal ao atingir
inline_keep_ratio float 0.4 Proporção de mensagens recentes a manter após compressão inline
idle_trigger float 0.5 Taxa de gatilho da compressão idle — executada de forma assíncrona após a resposta
idle_keep_ratio float 0.4 Proporção de mensagens recentes a manter após compressão idle
max_summary_tokens integer 4096 Número máximo de tokens de saída do resumo gerado pelo LLM
memory_palaceConfigurações LLM do Memory Palace; independente do bloco llm, parseado separadamente
💡 Exemplo de configuração
// Basic mode: rule-based extraction only (no LLM, zero cost)
{
  "memory_palace": {
    "enable_v9": false,        // Disable V9; falls back to legacy V8 mode
    "llm_enabled": false        // Disable LLM enhancement
  }
}

// Full mode: LLM-enhanced extraction (all three fields required; otherwise falls back to rule-based)
{
  "memory_palace": {
    "enable_v9": true,
    "llm_enabled": true,       // Once enabled, the following three fields are required
    "base_url": "https://api.anthropic.com",
    "api_key": "sk-ant-xxx",
    "model": "claude-haiku-4-5"    // Recommend a lightweight model to save tokens
  }
}
Parâmetro Tipo Padrão Descrição
enable_v9 boolean true Habilitar memória percepção-orientada V9; false = modo legado V8
llm_enabled boolean false Habilitar extração de memória aprimorada por LLM; false = apenas regras
base_url string "" Endpoint da API LLM para memória (os 3 campos são obrigatórios; caso contrário, retorna para regras)
api_key string "" Chave de API LLM para memória
model string "" Modelo LLM para memória (recomenda-se um modelo leve como haiku)
memory_qualityLimiares de qualidade da memória; controlam filtração de escrita e precisão de recall
💡 Exemplo de configuração
{
  "memory_quality": {
    "min_store_importance": 0.4,  // Write gate: discard facts with importance below this threshold
    "min_recall_score": 0.35,     // Recall gate: skip memories scoring below this threshold
    "dedup_threshold": 0.3        // Dedup threshold: Jaccard similarity above this = duplicate
  }
}
Parâmetro Tipo Padrão Descrição
min_store_importance float 0.4 Portão de escrita: descartar fatos com importância abaixo deste limiar na extração
min_recall_score float 0.35 Portão de recall: memórias com pontuação abaixo deste limiar não são injetadas no prompt
dedup_threshold float 0.3 Limiar de deduplicação: similaridade Jaccard acima deste valor = duplicata, manter a mais recente

Comandos disponíveis

Execute ações rápidas com comandos de barra

Comando Descrição
/ide Iniciar editor de código em tela cheia
/context Gerenciamento multi-contexto (novo/renomear/trocar/excluir)
/help Exibir informações de ajuda
/copy Copiar a última resposta para a área de transferência
/resume Retomar tarefas incompletas
/clear Limpar contexto da conversa
/restart Reiniciar o niuma
/model Verificar/trocar de modelo
/quit Encerrar o programa

Comandos rápidos #tag

Use #tag para injetar rapidamente instruções predefinidas — defina uma vez, reutilize muitas vezes

💡

O que é #tag

Tags personalizadas são atalhos definidos pelo usuário que se expandem em texto predefinido ao digitar #tagname.

  • Ao digitar #ja, expande automaticamente para "responder em japonês"
  • Suporta qualquer tag personalizada, sem distinção entre maiúsculas e minúsculas
  • As tags podem ser colocadas em qualquer lugar da entrada, removidas automaticamente após o parsing
  • O texto expandido é adicionado à entrada para que o LLM possa entendê-lo
Exemplo: #ja complexidade do bubble sort -> [responder em português] complexidade do bubble sort
⚙️

Dois tipos de tags

Tags de sistema controlam o modo de operação, tags personalizadas injetam instruções predefinidas. Elas se complementam.

  • #plan_mode — Forçar apenas análise, sem execução (maior prioridade)
  • #skip_mode — Pular todas as permissões, executar ferramentas diretamente
  • #custom — Qualquer atalho definido pelo usuário
  • Se plan_mode e skip_mode forem digitados ao mesmo tempo, plan_mode tem prioridade
📋

Gerenciamento com /tag

Use o comando /tag para adicionar, alterar, excluir e listar tags personalizadas.

  • /tag — Abrir painel de gerenciamento de tags (TUI) ou listar tags (CLI)
  • /tag add <name> <text> — Adicionar nova tag
  • /tag mod <name> <text> — Alterar tag existente
  • /tag rm <name> — Excluir tag
  • /tag ls — Listar todas as tags
🎯

Casos de uso comuns

Encapsule instruções frequentes como tags para aumentar a eficiência da conversa.

  • #ja — Forçar resposta em japonês
  • #fix — Instrução padrão de correção de bugs
  • #review — Requisitos padrão de revisão de código
  • #explain — Explicação detalhada da lógica do código
Uso combinado: #plan_mode #ja Analise o gargalo de desempenho desta função
💾

Armazenamento e configuração

As tags são salvas em um arquivo JSON, no mesmo local que o settings.json.

  • Local: ~/.niuma/custom_tags.json
  • Formato simples chave-valor, chaves convertidas automaticamente para minúsculas
  • Gravação atômica, compatível com Windows
Exemplo de arquivo:
{
  "ja": "responder em portugues",
  "fix": "corrigir bug"
}
🔄

Pipeline de parsing

A entrada passa por um roteamento em 3 direções, garantindo que LLM, recall de memória e armazenamento perceptivo recebam as informações necessárias.

  • raw_input — Entrada original, para salvamento de trace
  • llm_input — Entrada após expansão de tags, para compreensão do LLM
  • filter_input — Entrada sem tags, para recall de memória
  • A memória não é contaminada por tags, o recall permanece preciso