Kode-cli/docs/develop/overview.md

# Kode System Overview

## Introduction

Kode is an AI-powered terminal assistant that brings the power of Claude and other language models directly to your command line. It's designed as a sophisticated development tool that understands your codebase, executes commands, and handles complex workflows through natural language interaction.

## Core Design Philosophy

### 1. **Tool-First Architecture**
Everything in Kode is abstracted as a "Tool" - a self-contained unit of functionality with standardized interfaces for:
- Input validation through Zod schemas
- Permission checking and security
- Async execution with progress reporting
- Result formatting for both AI and human consumption

This design allows unlimited extensibility while maintaining consistency and security.

### 2. **Terminal-Native Experience**
Unlike web-based AI assistants, Kode is built specifically for terminal workflows:
- React components render directly to terminal using Ink
- Keyboard shortcuts and vim-like bindings for power users
- Streaming responses with real-time progress indicators
- Syntax highlighting and diff visualization in terminal

### 3. **Context-Aware Intelligence**
The AI automatically understands your project through:
- Git status and recent commits
- Directory structure analysis
- AGENTS.md and CLAUDE.md project documentation
- Custom command definitions in .claude/commands/ and .kode/commands/
- Previous conversation history and forked conversations

### 4. **Security Through Permissions**
Two-tier security model balancing safety and usability:
- **Permissive Mode** (default): Streamlined workflow with minimal interruptions
- **Safe Mode** (--safe flag): Granular permission requests for every operation

### 5. **Provider Agnostic**
Support for multiple AI providers through unified interface:
- Anthropic Claude (primary)
- OpenAI and compatible APIs
- Custom endpoints and local models
- Automatic model switching based on context size

### 6. **Extensibility via MCP**
Model Context Protocol (MCP) integration enables:
- Third-party tool integration
- Custom server connections (stdio/SSE)
- Import from Claude Desktop configuration
- Project-scoped server management

## Technology Stack

### Core Technologies
- **Language**: TypeScript with relaxed strict mode for pragmatic development
- **Runtime**: Node.js 18+ with Bun for development, TSX for production
- **UI Framework**: React + Ink for terminal rendering
- **CLI Framework**: Commander.js for argument parsing
- **Validation**: Zod for runtime type checking

### AI Integration
- **Anthropic SDK**: Native integration with Claude models
- **OpenAI SDK**: Support for GPT models and compatible APIs
- **Streaming**: Server-sent events for real-time responses
- **Context Management**: Smart token counting and compaction

### Development Tools
- **Build System**: Custom Bun-based build scripts
- **Testing**: Bun test runner with mocking support
- **Formatting**: Prettier with consistent code style
- **Error Tracking**: Sentry integration for production monitoring
- **Analytics**: Statsig for feature flags and usage metrics

## System Architecture Layers

### 1. Presentation Layer
React components rendered to terminal, providing:
- Interactive prompts and selections
- Syntax-highlighted code display
- Progress indicators and spinners
- Message formatting with markdown support

### 2. Command & Control Layer
Orchestrates user interactions through:
- Slash command system for quick actions
- Natural language processing for AI conversations
- Tool selection and execution pipeline
- Context injection and management

### 3. Tool Execution Layer
Standardized tool interface enabling:
- File operations (read, write, edit)
- Shell command execution
- Code searching and analysis
- Task management and planning
- External tool integration via MCP

### 4. Service Integration Layer
Connects to external services:
- AI model providers (Anthropic, OpenAI)
- MCP servers for extended functionality
- Git for version control integration
- File system for project analysis

### 5. Infrastructure Layer
Foundational services including:
- Configuration management (global/project)
- Permission system and security
- Logging and error handling
- Session and history management
- Cost tracking and analytics

## Key Design Patterns

### Async Generators for Streaming
Tools use async generators to yield progress updates, enabling real-time feedback during long operations while maintaining cancellation support.

### Component-Based UI Architecture
Every UI element is a React component, from simple text displays to complex interactive dialogs, ensuring consistency and reusability.

### Configuration Cascading
Settings flow from global → project → runtime with validation at each level, allowing flexible customization without complexity.

### Error Boundaries
Comprehensive error handling ensures graceful degradation, with user-friendly messages and automatic error reporting.

### Context Injection
Relevant project context is automatically injected into AI conversations, improving response quality without manual specification.

## Development Principles

### 1. **User Experience First**
Every feature is designed for terminal workflow efficiency, with keyboard-first interaction and minimal context switching.

### 2. **Progressive Disclosure**
Complex features are hidden behind simple interfaces, with advanced options available when needed.

### 3. **Fail Gracefully**
Errors are handled gracefully with helpful messages, fallback options, and recovery suggestions.

### 4. **Performance Conscious**
Caching, lazy loading, and streaming ensure responsive interaction even with large codebases.

### 5. **Security by Default**
Permission checks are mandatory for potentially dangerous operations, with clear user consent flows.

## System Capabilities

### Core Capabilities
- **Code Understanding**: Analyzes project structure and relationships
- **File Manipulation**: Read, write, and edit files with validation
- **Command Execution**: Run shell commands with output capture
- **Search & Analysis**: Find code patterns and dependencies
- **Task Management**: Plan and track development tasks

### AI-Enhanced Features
- **Natural Language Commands**: Describe what you want in plain English
- **Context-Aware Suggestions**: AI understands your project's specifics
- **Multi-Step Workflows**: Complex tasks broken down automatically
- **Code Generation**: Create new code following project patterns
- **Refactoring Support**: Safely modify existing code

### Integration Features
- **MCP Servers**: Connect to external tools and services
- **Custom Commands**: Define reusable markdown-based commands
- **Git Integration**: Understand and work with version control
- **Multiple AI Models**: Switch between models based on task

## Future Extensibility

The architecture is designed for future expansion:
- New tools can be added by implementing the Tool interface
- Additional AI providers can be integrated through ModelManager
- Custom commands enable user-defined workflows
- MCP support allows third-party extensions
- Plugin system could be added with minimal changes

This modular, extensible design ensures Kode can evolve with user needs while maintaining stability and security.