ChatCLI

Plataforma de IA unificada para terminal, servidor gRPC e Kubernetes.
_{14 provedores · 14 agentes autônomos · pipeline de qualidade em 7 padrões · um único binário.}

English • Documentação completa • Arquitetura • Observabilidade

ChatCLI conecta os maiores modelos de linguagem do mercado a uma interface única e extensível — do chatcli -p no terminal até um operador Kubernetes com pipeline AIOps autônomo, passando por um servidor gRPC production-ready com autenticação, fallback e métricas Prometheus.

Destaques

Instalação

# Homebrew (macOS / Linux)
brew tap diillson/chatcli && brew install chatcli

# Go install
go install github.com/diillson/chatcli@latest

# Binários pre-compilados assinados (cosign)
# https://github.com/diillson/chatcli/releases

git clone https://github.com/diillson/chatcli.git && cd chatcli
go mod tidy && go build -o chatcli

# Com informações de versão injetadas via ldflags
VERSION=$(git describe --tags --always --dirty 2>/dev/null || echo "dev")
go build -ldflags "-X github.com/diillson/chatcli/version.Version=${VERSION}" -o chatcli

Configuração rápida

LLM_PROVIDER=OPENAI    # OPENAI, CLAUDEAI, BEDROCK, GOOGLEAI, XAI, ZAI, MINIMAX, MOONSHOT,
                       # COPILOT, GITHUB_MODELS, OLLAMA, STACKSPOT, OPENROUTER
OPENAI_API_KEY=sk-xxx

Três modos de operação

chatcli
chatcli -p "Explique este repo"
git diff | chatcli -p "Resuma"

chatcli server --port 50051 \
  --token meu-token
chatcli connect \
  --server host:50051 \
  --token meu-token

helm install chatcli-operator \
  oci://ghcr.io/diillson/charts/chatcli-operator \
  --namespace chatcli-system \
  --create-namespace

Scheduler autônomo (Chronos)

O scheduler roda embutido no CLI e, opcionalmente, como daemon. Jobs sobrevivem a reinícios via WAL + snapshot.

# Dispara um comando em 30s
/schedule ping --when +30s --do "/run curl https://api.example.com/health"

# Cron diário com retry
/schedule backup --cron "0 2 * * *" --do "shell: ./backup.sh" --max-retries 3

# Deploy + wait K8s + trigger smoke
/schedule deploy --when +0s --do "shell: terraform apply -auto-approve" \
  --wait "k8s:deployment/prod/api:Available" --timeout 15m \
  --triggers smoke-tests

# Daemon para rodar sozinho com o CLI fechado
chatcli daemon start --detach
chatcli daemon status

# Listar / inspecionar / cancelar
/jobs list
/jobs show <id>
/jobs tree
/jobs cancel <id>

Agents ganham a tool @scheduler e podem se auto-pausar esperando condições — veja Cookbook: automações com Scheduler e doc da feature.

Injete dados do ambiente diretamente no prompt:

apiVersion: platform.chatcli.io/v1alpha1
kind: Instance
metadata:
  name: chatcli-prod
spec:
  provider: ZAI
  model: glm-5
  replicas: 2
  fallback:
    enabled: true
    providers:
      - name: OPENAI
        model: gpt-5.4
      - name: MINIMAX
        model: MiniMax-M2.7

helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
  --namespace chatcli --create-namespace \
  --set llm.provider=OPENAI --set secrets.openaiApiKey=sk-xxx

Provedores suportados

14 provedores com interface unificada. Fallback automático com classificação inteligente de erros, extended thinking cross-provider e cache de prompt onde disponível.

# Fallback chain configurável
CHATCLI_FALLBACK_PROVIDERS=OPENAI,CLAUDEAI,BEDROCK,ZAI,MINIMAX,MOONSHOT,OPENROUTER

/thinking on|off|auto ativa extended thinking / reasoning_effort em qualquer provider que suporte — o mapeamento cross-provider é automático.

Agentes autônomos

Motor ReAct (Reason + Act) com 14 agents builtin: 12 specialists de orquestração executando em paralelo (file, coder, shell, git, search, planner, reviewer, tester, refactor, diagnostics, formatter, deps) + 2 do harness de qualidade (refiner, verifier).

/coder "Refatore o módulo auth para usar JWT"
chatcli -p "Crie testes para o pacote utils" --agent-auto-exec

Workers são coordenados pelo dispatcher com semáforo configurável (CHATCLI_AGENT_MAX_WORKERS), política de retry e sincronização por FileLockManager.

Harness/Quality Pipeline

Sete padrões de prompting e execução compostos por uma pipeline pluggable com state machine, hot reload e isolamento por hook.

Arquitetura do Pipeline

• State machine (Active → Draining → Closed) com transições via CAS atômico.
• Copy-on-Write via atomic.Pointer[snapshot] — AddPre/AddPost/SwapConfig atômicos, zero lock no hot path.
• Isolamento por hook: panic recovery, timeout enforcement (default 30s), circuit breaker (5 falhas → open por 30s).
• Priority-based ordering via interface opcional Prioritized (backward compat — hooks sem prioridade ficam em 100).
• Short-circuit sentinels: ErrSkipExecution (cache-hit antes do agent.Execute) e ErrSkipRemainingHooks (ensemble patterns).
• Graceful shutdown com DrainAndClose(timeout) respeitando in-flight.

Reflexion durável (WAL + DLQ)

Triggers de reflexion (erro, alucinação detectada pelo CoVe, baixa qualidade) passam por uma fila de lessons com garantia enterprise — lições sobrevivem a crash do processo:

• WAL com CRC32 duplo, atomic rename, dir fsync — detecta torn writes automaticamente.
• Worker pool (default 2) com per-job timeout, exponential backoff + jitter, MaxAttempts configurável.
• DLQ persistente (mesmo formato WAL) com subcomandos /reflect failed, /reflect retry <id>, /reflect purge <id>.
• Drain-on-boot: lições pendentes de uma sessão anterior são reprocessadas automaticamente.
• Idempotência via sha256(task | trigger | attempt) — re-trigger da mesma situação é no-op.
• Stale discard (default 7d) — lições velhas descartadas no replay.

/reflect list              # fila atual + DLQ
/reflect failed            # DLQ com último erro por entrada
/reflect retry <job-id>    # reenfileira uma lição que falhou
/reflect purge <job-id>    # remove definitivamente da DLQ
/reflect drain             # força replay do WAL

Convergência semântica (Self-Refine)

O Self-Refine usa cascade char → Jaccard → embedding para detectar quando parar iterando. Resolve "same meaning, different words" que o heurístico char-level não pegava:

• Cache LRU com TTL (default 256 entries / 5min) evita chamar embedder duas vezes pelo mesmo texto.
• Circuit breaker por scorer — provider fora do ar degrada pra Jaccard sem travar refine.
• Quality regression detection: se pass N piora (>15% sim loss vs melhor) → reverte pro melhor draft visto + marca refine_rolled_back pra Reflexion aprender.
• Modo strict: recusa declarar convergência sem embedding quando a stakes for alta.

# Master switch
CHATCLI_QUALITY_ENABLED=true

# Self-Refine (#5) + convergência semântica
CHATCLI_QUALITY_REFINE_ENABLED=false            # opt-in
CHATCLI_QUALITY_REFINE_MAX_PASSES=1
CHATCLI_QUALITY_REFINE_CONVERGENCE_ENABLED=true
CHATCLI_QUALITY_REFINE_CONVERGENCE_EMBEDDING=false
CHATCLI_QUALITY_REFINE_CONVERGENCE_STRICT=false

# Chain-of-Verification (#6)
CHATCLI_QUALITY_VERIFY_ENABLED=false
CHATCLI_QUALITY_VERIFY_NUM_QUESTIONS=3
CHATCLI_QUALITY_VERIFY_REWRITE=true

# Reflexion (#3) + fila durável
CHATCLI_QUALITY_REFLEXION_ENABLED=true
CHATCLI_QUALITY_REFLEXION_QUEUE_ENABLED=true    # WAL + worker pool + DLQ
CHATCLI_QUALITY_REFLEXION_QUEUE_WORKERS=2
CHATCLI_QUALITY_REFLEXION_QUEUE_MAX_ATTEMPTS=5
CHATCLI_QUALITY_REFLEXION_QUEUE_STALE_AFTER=168h

# Plan-and-Solve / ReWOO (#2)
CHATCLI_QUALITY_PLAN_FIRST_MODE=auto             # off|auto|always

# HyDE (#4)
CHATCLI_QUALITY_HYDE_ENABLED=false
CHATCLI_QUALITY_HYDE_USE_VECTORS=false

# Reasoning backbone (#7)
CHATCLI_QUALITY_REASONING_MODE=auto              # off|on|auto
CHATCLI_QUALITY_REASONING_BUDGET=8000

Todos expostos no /config quality com estado em tempo real (hooks registrados, queue depth, DLQ size).

Observabilidade

Prometheus end-to-end em namespace chatcli. 50+ métricas cobrindo LLM, agentes, pipeline, queue e fila de lições.

chatcli server --port 50051 --metrics-port 9090
curl http://localhost:9090/metrics | grep chatcli_
curl http://localhost:9090/healthz

Métricas principais

Collectors padrão do Go runtime e process_* também registrados automaticamente.

Enterprise Security

Segurança não é um feature flag. É a fundação de cada camada do ChatCLI.

/auth login openai-codex       # OAuth PKCE + callback local
/auth login anthropic          # OAuth PKCE + code manual
/auth login github-copilot     # Device Flow (RFC 8628)
/auth status                   # Status de todos os providers

Credenciais armazenadas com AES-256-GCM em ~/.chatcli/auth-profiles.json.

Referência de comandos

Funcionalidades

Cada feature foi projetada para compor com as demais. Plugins descobrem skills. Hooks acionam tools. Contextos alimentam agentes.

Arquitetura

chatcli/
  cli/
    agent/
      quality/              Pipeline 7 patterns (state machine + COW snapshots)
        convergence/        Semantic convergence (char → jaccard → embedding)
        lessonq/            Reflexion durable queue (WAL + worker pool + DLQ)
      workers/              14 agentes + dispatcher + FileLockManager
    hooks/                  Lifecycle events (shell/webhook)
    mcp/                    MCP client (stdio + SSE)
    plugins/                Plugin manager + signature verification
    scheduler/              Chronos — scheduler durável (WAL + cron + DAG + daemon)
      condition/            10 evaluators (shell, http, k8s, docker, tcp, llm, ...)
      action/               8 executors (slash, shell, agent, webhook, ...)
      builtins/             Registro agregado de evaluators + executors
    workspace/memory/       Facts, topics, patterns, vector index (HyDE)
    tui/                    Bubble Tea adapters
  llm/
    openai/  openai_responses/  openai_assistant/
    claudeai/  bedrock/
    googleai/  xai/  zai/  minimax/
    copilot/  github_models/  stackspotai/  openrouter/  ollama/
    fallback/  catalog/  registry/  token/  toolshim/  embedding/
  metrics/                  Prometheus registry + /metrics + /healthz
  server/                   gRPC + TLS + JWT + MCP + Plugin discovery
  operator/                 Kubernetes Operator (17 CRDs, AIOps pipeline)
  k8s/                      Watcher (collectors, store, summarizer)
  models/                   ToolDefinition, ToolCall, LLMResponse, Message
  auth/                     OAuth PKCE, Device Flow, AES-256-GCM store
  config/                   ConfigManager com migração versionada
  i18n/                     embed.FS + golang.org/x/text (PT / EN)

Princípio de design: cada pacote define suas interfaces e se auto-registra no sistema. O llm/ registry permite adicionar um novo provider implementando uma única interface. O pipeline de qualidade é pluggable via AddPre/AddPost com swap atômico. O operator coordena CRDs independentes via controller pattern.

CI/CD & Releases

• CI (.github/workflows/1-ci.yml): golangci-lint, gofmt, go vet, go test -race -coverprofile, coverage HTML como artifact.
• Security scan (security-scan.yml): Trivy image scanning contínuo.
• Release automation (release-please + publish-release.yml): multi-platform builds, assinaturas cosign, SBOM CycloneDX, publish em ArtifactHub.
• Makefile: make build, make test, make lint, make install com injeção de Version, CommitHash, BuildDate via ldflags.

Contribuição

1. Fork o repositório
2. Crie uma branch a partir da main: git checkout -b feature/minha-feature
3. Commit e push
4. Abra um Pull Request

Veja docs/ para guias detalhados de arquitetura, quality pipeline e operator.

Licença

Apache License 2.0

Documentação • Releases • Helm Charts • Go Reference • Issues