ChatCLI

Unified AI platform for terminal, gRPC server, and Kubernetes.
_{15 providers · 14 autonomous agents · 7-pattern quality pipeline · one binary.}

Português • Full documentation • Architecture • Observability

ChatCLI connects the industry's leading LLMs to a single, extensible interface — from chatcli -p in your terminal to a Kubernetes operator with an autonomous AIOps pipeline, passing through a production-ready gRPC server with authentication, failover, and Prometheus metrics.

Highlights

Installation

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

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

# Pre-built, cosign-signed binaries
# https://github.com/diillson/chatcli/releases

Once installed, ChatCLI keeps itself current: /update upgrades through the same channel you installed with (Homebrew, go install, or verified binary self-replace for release downloads), and CHATCLI_AUTO_UPDATE=auto stages updates silently in the background — the next start opens on the new version. Docker images and source builds are never touched; they get instructions instead. See /config update for the current policy and detected channel.

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

# With version metadata injected 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

Quick Setup

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

Three Modes of Operation

chatcli
chatcli -p "Explain this repo"
git diff | chatcli -p "Summarize"

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

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

Autonomous scheduler (Chronos)

The scheduler runs embedded in the CLI and optionally as a daemon. Jobs survive restarts via WAL + snapshot.

# Fire a command in 30s
/schedule ping --when +30s --do "/run curl https://api.example.com/health"

# Daily cron with retry
/schedule backup --cron "0 2 * * *" --do "shell: ./backup.sh" --max-retries 3

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

# Daemon to keep running with the CLI closed
chatcli daemon start --detach
chatcli daemon status

# List / inspect / cancel
/jobs list
/jobs show <id>
/jobs tree
/jobs cancel <id>

Agents get the @scheduler tool and can pause themselves waiting on conditions — see Cookbook: scheduler automation and the feature doc.

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

Supported Providers

15 providers with a unified interface. Automatic failover with intelligent error classification, cross-provider extended thinking, and prompt caching where available.

# Configurable fallback chain
CHATCLI_FALLBACK_PROVIDERS=OPENAI,CLAUDEAI,BEDROCK,ZAI,MINIMAX,MOONSHOT,OPENROUTER

/thinking on|off|auto enables extended thinking / reasoning_effort on any provider that supports it — the cross-provider mapping is automatic.

Autonomous Agents

ReAct engine (Reason + Act) with 14 built-in agents: 12 orchestration specialists running in parallel (file, coder, shell, git, search, planner, reviewer, tester, refactor, diagnostics, formatter, deps) + 2 quality-harness agents (refiner, verifier).

/coder "Refactor the auth module to use JWT"
chatcli -p "Create tests for the utils package" --agent-auto-exec

Workers are coordinated by the dispatcher with a configurable semaphore (CHATCLI_AGENT_MAX_WORKERS), retry policy, and FileLockManager synchronization.

Harness/Quality Pipeline

Seven prompting/execution patterns composed via a pluggable pipeline with state machine, hot reload, and per-hook isolation.

Pipeline Architecture

• State machine (Active → Draining → Closed) with atomic CAS transitions.
• Copy-on-Write via atomic.Pointer[snapshot] — AddPre/AddPost/SwapConfig are atomic, zero locks on the hot path.
• Per-hook isolation: panic recovery, timeout enforcement (default 30s), circuit breaker (5 failures → open for 30s).
• Priority-based ordering via optional Prioritized interface (backward-compatible — unmarked hooks default to 100).
• Short-circuit sentinels: ErrSkipExecution (cache-hit before agent.Execute) and ErrSkipRemainingHooks (ensemble patterns).
• Graceful shutdown via DrainAndClose(timeout) honoring in-flight calls.

Durable Reflexion (WAL + DLQ)

Reflexion triggers (error, hallucination flagged by CoVe, low quality) flow through a lesson queue with enterprise guarantees — lessons survive process crashes:

• WAL with double CRC32, atomic rename, dir fsync — torn writes detected automatically.
• Worker pool (default 2) with per-job timeout, exponential backoff with jitter, configurable MaxAttempts.
• Persistent DLQ (same WAL format) with /reflect failed, /reflect retry <id>, /reflect purge <id>.
• Drain-on-boot: pending lessons from a previous session are reprocessed automatically.
• Idempotency via sha256(task | trigger | attempt) — re-triggering the same situation is a no-op.
• Stale discard (default 7d) — old lessons dropped at replay time.

/reflect list              # current queue + DLQ
/reflect failed            # DLQ with last error per entry
/reflect retry <job-id>    # re-queue a failed lesson
/reflect purge <job-id>    # permanently remove a DLQ entry
/reflect drain             # force WAL replay

Semantic Convergence (Self-Refine)

Self-Refine uses a char → Jaccard → embedding cascade to detect when to stop iterating. Catches "same meaning, different words" that the char-level heuristic missed:

• LRU cache with TTL (default 256 entries / 5min) avoids re-embedding identical text.
• Per-scorer circuit breaker — provider outage degrades to Jaccard without blocking refine.
• Quality regression detection: when pass N gets worse (>15% sim loss vs best) → revert to best draft + set refine_rolled_back metadata so Reflexion can learn.
• Strict mode: refuses to declare convergence without embedding when stakes are high.

# Master switch
CHATCLI_QUALITY_ENABLED=true

# Self-Refine (#5) + semantic convergence
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) + durable queue
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

Observability

End-to-end Prometheus integration in the chatcli namespace. 50+ metrics covering LLM, agents, pipeline, queue, and lesson queue.

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

Key metrics

Standard Go runtime and process_* collectors are registered automatically.

Enterprise Security

Security is not a feature flag. It is the foundation of every layer of ChatCLI.

/auth login openai-codex       # OAuth PKCE + local callback
/auth login anthropic          # OAuth PKCE + manual code
/auth login github-copilot     # Device Flow (RFC 8628)
/auth status                   # All provider status

Command Reference

Core Features

Every feature is designed to compose with the others. Plugins discover skills. Hooks drive tools. Contexts feed agents.

Architecture

chatcli/
  cli/
    agent/
      quality/              7-pattern pipeline (state machine + COW snapshots)
        convergence/        Semantic convergence (char → jaccard → embedding)
        lessonq/            Reflexion durable queue (WAL + worker pool + DLQ)
      workers/              14 agents + dispatcher + FileLockManager
    hooks/                  Lifecycle events (shell/webhook)
    mcp/                    MCP client (stdio, SSE, HTTP + OAuth)
    plugins/                Plugin manager + signature verification
    scheduler/              Chronos — durable scheduler (WAL + cron + DAG + daemon)
      condition/            10 evaluators (shell, http, k8s, docker, tcp, llm, ...)
      action/               8 executors (slash, shell, agent, webhook, ...)
      builtins/             Aggregated registry for 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 with versioned migration
  i18n/                     embed.FS + golang.org/x/text (PT / EN)

Design principle: each package declares its own interfaces and self-registers. The llm/ registry lets you add a new provider by implementing a single interface. The quality pipeline is pluggable via AddPre/AddPost with atomic swap. The operator coordinates independent CRDs via the controller pattern.

CI/CD & Releases

• CI (.github/workflows/1-ci.yml): golangci-lint, gofmt, go vet, go test -race -coverprofile, coverage HTML as artifact.
• Security scan (security-scan.yml): continuous Trivy image scanning.
• Release automation (release-please + publish-release.yml): multi-platform builds, cosign signatures, CycloneDX SBOM, ArtifactHub publishing.
• Makefile: make build, make test, make lint, make install with Version, CommitHash, BuildDate injected via ldflags.

Contributing

1. Fork the repository
2. Create a branch from main: git checkout -b feature/my-feature
3. Commit and push
4. Open a Pull Request

See docs/ for detailed architecture, quality pipeline, and operator guides.

License

Apache License 2.0

Documentation • Releases • Helm Charts • Go Reference • Issues