How shareai-lab/kode works
Project Type and Purpose
• This is a full-featured CLI application (“Kode”) with a layered, plugin-style architecture.
• Purpose: Provide an AI-driven terminal assistant that understands codebases, runs shell commands, edits files, and orchestrates AI sub-agents across multiple AI model providers.
High-Level Component Breakdown
a. Entrypoints
• CLI layer (src/entrypoints/cli.tsx, mcp.ts)
• Docker wrapper (Dockerfile, DEPLOYMENT_GUIDE.md)
b. Command Processor
• Command registry (src/commands.ts)
• Individual commands/modules (src/commands/\*.tsx/.ts)
c. Context & State Manager
• Conversation/context manager (src/context.ts, src/utils/messageContextManager.ts)
• Session state, history (src/history.ts, src/utils/sessionState.ts)
d. Model Management Layer
• ModelManager & profiles (services/adapters + src/services/modelAdapterFactory.ts)
• Multi-model pointers & switching logic (Configuration in src/constants and CLI /model)
e. Tooling & Sub-Agents
• Tool definitions (src/tools/\*Tool)
• Agent orchestration (AGENTS.md, src/utils/agentLoader.ts, src/services/responseStateManager.ts)
f. Services & Adapters
• AI service adapters (OpenAI, Claude, custom…) under src/services/adapters
• OAuth, MCP server, notifier, cost-tracking, VCR (src/services/*)
g. UI / Rendering Layer
• React components for terminal UI (src/components/**)
• Hooks & context providers for interactive views (src/hooks, src/context/PermissionContext.tsx)
h. Persistence & Configuration
• File-based configs (~/.kode.json), agent storage, expert chat storage (src/utils/*Storage)
• Permission logs, cost history
i. Utils & Shared Libraries
• Fuzzy matchers, diffing, logging, file I/O, shell execution (src/utils/**)
• Common types (src/types)
Relationships & Data Flow
1. User launches CLI (cli.tsx) → passes raw args to Command Processor.
2. Command Processor selects Command Module → fetches/updates Context via Context Manager.
3. Command Module invokes Tools or direct model requests:
• Calls ModelManager to select appropriate adapter.
• Sends prompt or sub-agent orchestration request.
4. Service Adapters handle external API calls → returns AI responses.
5. ResponseStateManager & UI Components render output to terminal.
6. If file edits or shell commands are issued, Tools call into Shell Execution / File I/O Utils.
7. Persistence layer logs operations, updates state, cost tracking, and permission records.
Architectural Patterns & Principles
• Layered Architecture: Clear separation between CLI, command logic, services, tools, and persistence.
• Plugin/Modular Pattern: Each command and tool is a self-contained module registered at startup.
• Adapter Pattern: AI providers are abstracted behind a common interface.
• Event-Driven / Message-Based Flow: Context and state updates propagate through hooks and context providers.
• Configuration-Driven: Model profiles and pointers are entirely configurable and hot-swappable.
Essential Details to Capture
• Multi-model collaboration: show multiple adapters connected to ModelManager.
• Permission system: highlight permission requests flowing through PermissionContext → user approval → Tools.
• Cost tracking: illustrate /cost command querying CostTracker service.
• Docker integration: separate container boundary with mounted volumes and working directory.