Skip to main content
ChatCLI is a modular Go project organized into packages with well-defined responsibilities. This page documents the internal architecture for contributors and advanced users.

​
Package Overview

chatcli/
|-- main.go                    # Entrypoint
|-- cli/                       # User interface and modes
|   |-- cli.go                 # Main ChatCLI struct + Start()
|   |-- agent_mode.go          # Agent mode (~3200 lines)
|   |-- rewind.go              # Conversation checkpoints and restore
|   |-- compact_command.go     # Guided history compaction
|   |-- history_compactor.go   # 3-level compaction pipeline
|   |-- history_trimmer.go     # Near-lossless trimming (level 1)
|   |-- command_handler.go     # Slash command routing
|   |-- agent/                 # Multi-agent system
|   |   |-- workers/           # 12 specialist agents
|   |   |-- ui_renderer.go     # UI rendering
|   |   +-- dispatcher.go      # Async dispatcher
|   |-- bus/                   # Internal message bus
|   |-- workspace/             # Bootstrap files + memory (connected)
|   |   |-- bootstrap.go       # BootstrapLoader with mtime cache
|   |   |-- memory.go          # MemoryStore (MEMORY.md + daily notes)
|   |   +-- context_builder.go # Combines bootstrap + memory into prompt
|   |-- skills/                # Skills system
|   +-- mcp/                   # MCP manager
|-- config/                    # Configuration and migration
|-- i18n/                      # Internationalization
|-- llm/                       # LLM communication
|   |-- registry/              # Provider auto-registration
|   |-- fallback/              # Fallback chain
|   |-- client/                # LLMClient + ToolAwareClient interface
|   |-- openai/                # OpenAI provider
|   |-- claudeai/              # Anthropic provider
|   |-- googleai/              # Google provider
|   |-- xai/                   # xAI provider
|   |-- ollama/                # Ollama provider
|   +-- copilot/               # GitHub Copilot provider
|-- models/                    # Structs: ToolDefinition, ToolCall, LLMResponse
|-- server/                    # gRPC server
|-- client/remote/             # gRPC client
|-- k8s/                       # Kubernetes Watcher
|-- operator/                  # K8s Operator (AIOps)
|   |-- api/v1alpha1/          # 7 CRD types
|   +-- controllers/           # Reconcilers and engines
|-- proto/                     # Protobuf definitions
|-- utils/                     # Utility functions
+-- version/                   # Version information

​
Main Components

​
CLI and Modes

The ChatCLI struct in cli/cli.go is the central point. The Start() method initiates interactive mode using go-prompt v0.2.6.
ModeFileDescription
Interactivecli/cli.goInteractive prompt with auto-completion
Agentcli/agent_mode.goTask planning and execution
Codercli/cli.go + cli/agent_mode.goEngineering loop with tool calls
One-shotcli/cli.go (flag -p)Single execution without TUI
Mode switching uses a panic/recover mechanism to exit the go-prompt loop. ChatCLI uses a unified history (cli.history) shared across all modes. When switching modes, the full context is preserved. The /compact and /rewind commands operate directly on this single history.

​
Provider Registry

Each LLM provider auto-registers via init() in the llm/registry package. This eliminates switch/case blocks and makes adding new providers easy — just create the package and implement the LLMClient interface.

​
Message Bus

The cli/bus package implements a typed message bus with:
  • Pub/sub with channel and type filters
  • Request-reply with correlation IDs
  • Atomic throughput metrics

​
Multi-Agent

The orchestration system in cli/agent/workers manages 12 specialist agents running in parallel goroutines with a configurable semaphore. Each worker has:
  • Isolated mini ReAct loop (observe -> reason -> act)
  • Own skills (accelerator and descriptive scripts)
  • File locks (mutex per-filepath)
  • Configurable timeout and max turns

​
Technologies

CategoryLibrary
TUIgo-prompt v0.2.6
MarkdownGlamour (Charmbracelet)
ColorsLipgloss (Charmbracelet)
LoggerZap (Uber)
Log rotationLumberjack
Env filesGodotenv
i18ngolang.org/x/text
gRPCgoogle.golang.org/grpc
Kubernetesk8s.io/client-go
Operatorcontroller-runtime (Kubebuilder)
Protobufgoogle.golang.org/protobuf

​
Design Patterns

  • Auto-registration via init() — Providers register themselves automatically
  • Interface-driven — LLMClient and ToolAwareClient for polymorphism
  • Fallback chain — Intelligent error classification + exponential cooldown
  • Stateful parser — XML parsing with escaped attributes (more robust than regex)
  • embed.FS — i18n files embedded in the binary (always uses /, never filepath.Join)
  • Panic/recover — Mode switching in go-prompt without restarting the process
  • Unified history — A single message array shared across chat, agent, and coder modes
  • Checkpoint/rewind — Deep copy of history before each LLM call, with selective restore
  • 3-level compaction — Near-lossless trimming, structured summarization, emergency truncation
  • Workspace context injection — Bootstrap + memory automatically injected into every system prompt
  • Unified system prompt with caching — Attached contexts (/context attach) now flow through the system prompt via SystemParts with CacheControl hints in the Message model, enabling provider-level prompt caching (Anthropic cache_control: ephemeral, OpenAI automatic caching, Google context caching). Previously, attached contexts were injected as user messages, which prevented caching across turns