@codemieai/code 0.0.2 → 0.0.4

package/README.md

@@ -1,26 +1,79 @@
-# CodeMie Code
-
-> AI coding assistant and CLI wrapper for managing multiple AI coding agents
-
-CodeMie Code is a unified npm package that provides both a built-in AI coding assistant and a CLI wrapper for managing multiple AI coding agents (Claude Code, Aider, Codex, etc.).
-
-## ✨ Features
+# AI/Run CodeMie CLI
+
+> Professional CLI wrapper for managing multiple AI coding agents
+
+## Table of Contents
+
+- [Synopsis](#synopsis)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+  - [From npm (Recommended)](#from-npm-recommended)
+  - [From Source (Development)](#from-source-development)
+  - [Verify Installation](#verify-installation)
+- [Usage](#usage)
+  - [Built-in Agent (CodeMie Native)](#built-in-agent-codemie-native)
+  - [External Agents](#external-agents)
+- [Commands](#commands)
+  - [Core Commands](#core-commands)
+  - [Agent Shortcuts](#agent-shortcuts)
+  - [Configuration Commands](#configuration-commands)
+- [Configuration](#configuration)
+  - [Setup Wizard (Recommended)](#setup-wizard-recommended)
+  - [Supported Providers](#supported-providers)
+  - [Manual Configuration](#manual-configuration)
+  - [Model Compatibility](#model-compatibility)
+- [Authentication & SSO Management](#authentication--sso-management)
+  - [AI/Run CodeMie SSO Setup](#airun-codemie-sso-setup)
+  - [Token Management](#token-management)
+  - [Enterprise SSO Features](#enterprise-sso-features)
+- [Examples](#examples)
+  - [Common Workflows](#common-workflows)
+  - [Configuration Examples](#configuration-examples)
+  - [Advanced Usage](#advanced-usage)
+- [Agents](#agents)
+  - [CodeMie Native (Built-in)](#codemie-native-built-in)
+  - [Claude Code](#claude-code)
+  - [Codex](#codex)
+- [Troubleshooting](#troubleshooting)
+  - [Command Not Found](#command-not-found)
+  - [Configuration Issues](#configuration-issues)
+  - [Connection Problems](#connection-problems)
+  - [Agent Installation Failures](#agent-installation-failures)
+  - [Model Compatibility Errors](#model-compatibility-errors)
+- [Development](#development)
+  - [Project Structure](#project-structure)
+  - [Building](#building)
+  - [Testing](#testing)
+- [License](#license)
+- [Links](#links)
+
+## Synopsis
+
+```bash
+codemie [COMMAND] [OPTIONS]
+codemie-code [MESSAGE|--task TASK] [OPTIONS]
+codemie-claude [-p MESSAGE] [OPTIONS]
+codemie-codex [MESSAGE|--task TASK] [OPTIONS]
+```
+
+AI/Run CodeMie CLI is a professional, unified CLI tool for installing, configuring, and running multiple AI coding agents from a single interface. It includes a built-in LangGraph-based agent (CodeMie Native) and supports external agents like Claude Code and Codex.
+
+## Quick Start
+
+```bash
+# 1. Install
+npm install -g @codemieai/code
 
-- 🤖 **Built-in AI Assistant** - Ready-to-use coding assistant powered by any AI provider
-- 🔧 **CLI Wrapper** - Manage and run multiple AI coding agents from one interface
-- 🛠️ **Complete Toolset** - 15 tools including filesystem operations, git commands, and code execution
-- 🔌 **MCP Support** - Model Context Protocol integration for extensible tool support
-- 🔒 **Security First** - Path validation, symlink protection, and command sanitization
-- 📝 **Diff-based Editing** - Smart file editing with indentation preservation
-- 🌐 **Provider Agnostic** - Works with any AI provider (OpenAI, Anthropic, Azure, etc.)
-- 🎯 **Project-aware** - Operates within allowed directories with ignore patterns
-- 🚀 **Zero Configuration** - Works with environment variables only
+# 2. Setup (interactive wizard)
+codemie setup
 
----
+# 3. Start coding with built-in agent
+codemie-code "Review my code for bugs"
+```
 
-## 📦 Installation
+## Installation
 
-### From npm (when published)
+### From npm (Recommended)
 
 ```bash
 npm install -g @codemieai/code
@@ -29,889 +82,474 @@ npm install -g @codemieai/code
 ### From Source (Development)
 
 ```bash
-# Clone the repository
 git clone https://github.com/codemie-ai/codemie-code.git
 cd codemie-code
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Link globally for testing
-npm link
+npm install && npm run build && npm link
 ```
 
 ### Verify Installation
 
 ```bash
-# Check if commands are available
 codemie --help
-codemie-code --help
-
-# Run health check
 codemie doctor
 ```
 
----
-
-## 🚀 Quick Start
+## Usage
 
-### 1. Set Up Environment Variables
+### Built-in Agent (CodeMie Native)
 
-CodeMie Code requires AI provider credentials:
+Ready to use immediately - no installation required:
 
 ```bash
-export CODEMIE_BASE_URL="https://your-ai-proxy.com"
-export CODEMIE_AUTH_TOKEN="your-auth-token"
-export CODEMIE_MODEL="claude-4-5-sonnet"
-```
-
-**Add to your shell profile** for persistence:
-
-```bash
-# Add to ~/.bashrc or ~/.zshrc
-echo 'export CODEMIE_BASE_URL="https://your-ai-proxy.com"' >> ~/.bashrc
-echo 'export CODEMIE_AUTH_TOKEN="your-auth-token"' >> ~/.bashrc
-echo 'export CODEMIE_MODEL="claude-4-5-sonnet"' >> ~/.bashrc
-
-# Reload shell
-source ~/.bashrc
-```
-
-### 2. Test Connection
-
-```bash
-codemie-code test
-```
-
-**Expected output:**
-```
-✓ Configuration loaded
-✓ Testing connection...
-✓ Connection successful
-✓ Model: claude-4-5-sonnet
-```
-
-### 3. Start the Assistant
-
-```bash
-# In current directory
+# Interactive conversation
 codemie-code
 
-# In specific directory
-codemie-code /path/to/your/project
-
-# Execute one-off task
-codemie-code exec "Add error handling to api.ts"
-```
+# Execute single task
+codemie-code --task "fix bugs in src/utils"
 
-### 4. Interact with the Assistant
+# Start with initial message
+codemie-code "Help me refactor this component"
 
+# Debug mode
+codemie-code --debug
 ```
-╔═══════════════════════════════════════╗
-║       CodeMie Code Assistant          ║
-╚═══════════════════════════════════════╝
-
-Working directory: /your/project
-Model: claude-4-5-sonnet
-
-Type "exit" to quit, "clear" to clear history
-
-You: List all TypeScript files in this project
-You: Show git status and recent commits
-You: Create a new file called utils.ts with helper functions
-```
-
----
 
-## 📚 Configuration
+### External Agents
 
-### Required Environment Variables
-
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `CODEMIE_BASE_URL` | AI provider base URL | `https://your-ai-proxy.com` |
-| `CODEMIE_AUTH_TOKEN` | Authentication token | `your-token-here` |
-| `CODEMIE_MODEL` | Model to use | `claude-4-5-sonnet` |
-
-### Optional Configuration
-
-#### Runtime Configuration
+Install and run external agents:
 
 ```bash
-# Enable debug logging
-export CODEMIE_DEBUG="true"
+# Install agents
+codemie install claude
+codemie install codex
 
-# Timeout for AI requests (seconds)
-export CODEMIE_TIMEOUT="300"
+# Run via shortcuts (recommended)
+codemie-claude -p "Review my API code"
+codemie-codex --task "Generate unit tests"
 
-# Load specific MCP servers
-export CODEMIE_MCP_SERVERS="time,context7"
+# Or run through main CLI
+codemie run claude --task "Fix security issues"
 ```
 
-#### MCP Configuration
+## Commands
 
-Configure MCP (Model Context Protocol) servers in `~/.codemie/config.json`:
-
-```json
-{
-  "mcpServers": {
-    "context7": {
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
-    },
-    "time": {
-      "command": "uvx",
-      "args": ["mcp-server-time"]
-    }
-  }
-}
-```
-
-Or use environment variable to specify which servers to load:
+### Core Commands
 
 ```bash
-# Load specific MCP servers
-export CODEMIE_MCP_SERVERS="context7,time"
-codemie-code
-
-# Or with CLI flag
-codemie-code --mcp-servers context7,time
+codemie setup                    # Interactive configuration wizard
+codemie auth <command>           # Manage SSO authentication
+codemie list                     # List all available agents
+codemie install <agent>          # Install an agent
+codemie uninstall <agent>        # Uninstall an agent
+codemie run <agent> [args...]    # Run an agent
+codemie doctor                   # Health check and diagnostics
+codemie config <action>          # Manage configuration
+codemie version                  # Show version information
 ```
 
-When no `--mcp-servers` flag is provided, all servers configured in `~/.codemie/config.json` are loaded automatically.
+### Agent Shortcuts
 
-### Configuration Methods
-
-#### Method 1: Shell Environment (Recommended)
+Direct access to agents with automatic configuration:
 
 ```bash
-# Add to ~/.bashrc or ~/.zshrc
-export CODEMIE_BASE_URL="https://your-ai-proxy.com"
-export CODEMIE_AUTH_TOKEN="your-token"
-export CODEMIE_MODEL="claude-4-5-sonnet"
-
-# Reload shell
-source ~/.bashrc  # or ~/.zshrc
-```
+# Built-in agent
+codemie-code [message]           # Interactive or with initial message
+codemie-code --task "task"       # Single task execution
+codemie-code health              # Health check
 
-#### Method 2: Project .env File
+# External agents
+codemie-claude                   # Claude Code agent (interactive)
+codemie-claude -p "message"      # Claude Code agent (print mode)
+codemie-codex [message]          # Codex agent
 
-```bash
-# Create .env in your project
-cat > .env << EOF
-CODEMIE_BASE_URL=https://your-ai-proxy.com
-CODEMIE_AUTH_TOKEN=your-token
-CODEMIE_MODEL=claude-4-5-sonnet
-EOF
-
-# Load and run
-set -a; source .env; set +a
-codemie-code
+# Configuration overrides
+codemie-claude --model claude-4-5-sonnet --api-key your-key
+codemie-codex --model gpt-4o --provider openai
 ```
 
-#### Method 3: Inline
+### Configuration Commands
 
 ```bash
-CODEMIE_BASE_URL="https://your-ai-proxy.com" \
-CODEMIE_AUTH_TOKEN="your-token" \
-CODEMIE_MODEL="claude-4-5-sonnet" \
-codemie-code
+codemie config list              # Show all configuration
+codemie config get <key>         # Get specific value
+codemie config set <key> <value> # Set configuration value
+codemie config reset             # Reset to defaults
 ```
 
-### Advanced: Provider-Specific Configuration
+## Configuration
 
-For advanced scenarios, you can use provider-specific environment variables. These act as fallbacks if generic `CODEMIE_*` variables are not set:
+### Setup Wizard (Recommended)
 
-**For Anthropic Claude:**
-```bash
-export ANTHROPIC_BASE_URL="https://api.anthropic.com"
-export ANTHROPIC_AUTH_TOKEN="your-anthropic-token"
-export ANTHROPIC_MODEL="claude-4-5-sonnet"
-```
+Run the interactive setup wizard:
 
-**For OpenAI GPT:**
 ```bash
-export OPENAI_BASE_URL="https://api.openai.com/v1"
-export OPENAI_API_KEY="your-openai-key"
-export OPENAI_MODEL="gpt-4"
+codemie setup
 ```
 
-**Configuration Priority:**
-1. `CODEMIE_*` (generic - checked first)
-2. `ANTHROPIC_*` or `OPENAI_*` (provider-specific - fallback)
+The wizard will:
+- Guide you through provider selection
+- Test your credentials via health endpoints
+- Fetch available models in real-time
+- Save configuration to `~/.codemie/config.json`
 
----
+### Supported Providers
 
-## 🎯 Usage
+- **ai-run-sso** - AI/Run CodeMie SSO (unified enterprise gateway)
+- **openai** - OpenAI API
+- **azure** - Azure OpenAI
+- **bedrock** - AWS Bedrock
+- **litellm** - LiteLLM Proxy
 
-### CodeMie Code Assistant
+### Manual Configuration
 
-The built-in AI assistant with filesystem, git, and command execution tools.
+#### Environment Variables (Highest Priority)
 
 ```bash
-# Interactive mode (default)
-codemie-code
-codemie-code /path/to/project
-
-# Execute one-off task
-codemie-code exec "Add error handling to api.ts"
+# Generic (works with any provider)
+export CODEMIE_BASE_URL="https://your-proxy.com"
+export CODEMIE_API_KEY="your-api-key"
+export CODEMIE_MODEL="your-model"
+export CODEMIE_PROVIDER="litellm"
 
-# Execute with custom directory
-codemie-code exec "Run tests" -d /path/to/project
-
-# Test connection
-codemie-code test
-
-# With MCP servers
-codemie-code --mcp-servers time,context7
-
-# With specific model
-CODEMIE_MODEL="claude-opus" codemie-code
+# Provider-specific
+export OPENAI_API_KEY="your-openai-key"
+export OPENAI_BASE_URL="https://api.openai.com/v1"
 ```
 
-#### Interactive Commands
-
-Once inside the assistant:
+#### Configuration File
 
-- **exit** - Exit the assistant
-- **clear** - Clear conversation history
-- Any coding question or task
+Location: `~/.codemie/config.json`
 
-#### Example Prompts
-
-```
-You: Show me the project structure
-You: Read the package.json file
-You: List all TypeScript files
-You: Show git status and recent commits
-You: Create a new file called utils.ts with helper functions
-You: Search for files containing "authentication"
-You: Edit README.md to add a new section
-You: Run npm test and show me the results
+```json
+{
+  "provider": "litellm",
+  "model": "claude-4-5-sonnet",
+  "baseUrl": "https://litellm.codemie.example.com",
+  "apiKey": "your-api-key",
+  "timeout": 300
+}
 ```
 
-### MCP Server Management
+### Model Compatibility
 
-Extend capabilities with Model Context Protocol servers.
+AI/Run CodeMie CLI automatically validates model compatibility:
 
-```bash
-# List available servers
-codemie-code mcp list
+- **Codex**: OpenAI models only (gpt-4, gpt-4o, gpt-5, etc.)
+- **Claude**: Both Claude and GPT models
+- **CodeMie Native**: All supported models
 
-# List with detailed configuration
-codemie-code mcp list -v
+When incompatible models are detected, AI/Run CodeMie CLI will:
+1. Fetch available models from your provider's API
+2. Filter to compatible models
+3. Offer to switch automatically
 
-# Add new server
-codemie-code mcp add <name> <command-or-url> [options]
+## Authentication & SSO Management
 
-# Test server configuration
-codemie-code mcp test <server-name>
+### AI/Run CodeMie SSO Setup
 
-# Remove server
-codemie-code mcp remove <server-name>
+For enterprise environments with AI/Run CodeMie SSO (Single Sign-On):
 
-# Preview which servers will load
-codemie-code mcp servers
-codemie-code mcp servers --servers time,context7
-```
+#### Initial Setup via Wizard
 
-#### Popular MCP Servers
+The setup wizard automatically detects and configures AI/Run CodeMie SSO:
 
-**Time Server** - Query times in any timezone:
 ```bash
-codemie-code mcp add time uvx -a "mcp-server-time"
-codemie-code --mcp-servers time
-
-# Then ask: "What time is it in Hong Kong?"
+codemie setup
 ```
 
-**Context7** - Access up-to-date library documentation:
-```bash
-codemie-code mcp add context7 npx -a "-y" "@upstash/context7-mcp"
-codemie-code --mcp-servers context7
-
-# Then ask: "Show me LangChain documentation for chains"
-```
+**The wizard will:**
+1. Detect if you have access to AI/Run CodeMie SSO
+2. Guide you through the authentication flow
+3. Test the connection with health checks
+4. Fetch and display available models
+5. Save secure credentials to `~/.codemie/config.json`
 
-### CLI Wrapper (codemie)
+#### Manual SSO Authentication
 
-Manage multiple AI coding agents from one interface.
-
-#### List Available Agents
+If you need to authenticate separately or refresh your credentials:
 
 ```bash
-codemie list                    # List all agents
-codemie list --installed        # List only installed agents
-```
-
-#### Install Agents
+# Authenticate with AI/Run CodeMie SSO
+codemie auth login --url https://your-airun-codemie-instance.com
 
-```bash
-codemie install claude-code     # Install Anthropic Claude Code
-codemie install aider           # Install Aider
-codemie install codex           # Install OpenAI Codex
-```
+# Check authentication status
+codemie auth status
 
-#### Run Agents
+# Refresh expired tokens
+codemie auth refresh
 
-```bash
-# Run built-in CodeMie Code
-codemie run codemie-code
+# Logout and clear credentials
+codemie auth logout
+```
 
-# Run other agents
-codemie run claude-code
-codemie run aider
-codemie run codex
+### Token Management
 
-# With custom model
-codemie run codemie-code --model claude-opus
+SSO tokens are automatically managed but you can control them manually:
 
-# Pass additional arguments
-codemie run aider --no-auto-commits
-```
+#### Token Refresh
 
-#### Uninstall Agents
+AI/Run CodeMie CLI automatically refreshes tokens when they expire. For manual refresh:
 
 ```bash
-codemie uninstall claude-code
-codemie uninstall aider
+# Refresh SSO credentials (extends session)
+codemie auth refresh
 ```
 
-#### Health Check
+**When to refresh manually:**
+- Before long-running tasks
+- After extended periods of inactivity
+- When you receive authentication errors
+- Before important demonstrations
 
-```bash
-codemie doctor
-```
+#### Authentication Status
 
-Checks:
-- ✅ Node.js version (>= 24.0.0)
-- ✅ npm installation
-- ✅ git availability
-- ✅ Environment variables configuration
-- ✅ Installed agents
-
-#### Version Information
+Check your current authentication state:
 
 ```bash
-codemie version
-codemie-code --version
+codemie auth status
 ```
 
----
-
-## 🛠️ Available Tools
-
-CodeMie Code assistant comes with 15 built-in tools, plus extensible MCP tools:
-
-### Filesystem Tools (10 tools)
-
-| Tool | Description |
-|------|-------------|
-| `read_file` | Read contents of a file |
-| `read_multiple_files` | Read multiple files at once |
-| `write_file` | Write/create a file with content |
-| `edit_file` | Edit file with diff-based updates |
-| `create_directory` | Create directories recursively |
-| `list_directory` | List files and directories |
-| `project_tree` | Generate visual project structure tree |
-| `move_file` | Move or rename files |
-| `search_files` | Search files by name or content |
-| `list_allowed_directories` | Show accessible directories |
+**Status information includes:**
+- Connection status to AI/Run CodeMie SSO
+- Token validity and expiration
+- Available models for your account
+- Provider configuration details
 
-### Git Tools (4 tools)
+#### Token Troubleshooting
 
-| Tool | Description |
-|------|-------------|
-| `git_status` | Get repository status |
-| `git_diff` | Show git diff for changes |
-| `git_log` | Show commit history |
-| `git_command` | Execute any git command |
+Common authentication issues and solutions:
 
-### Command Execution (1 tool)
-
-| Tool | Description |
-|------|-------------|
-| `execute_command` | Execute shell commands (with security checks) |
-
-### MCP Tools (Extensible)
-
-MCP (Model Context Protocol) enables dynamic tool loading from external servers:
-
-| Server | Tools | Description |
-|--------|-------|-------------|
-| `context7` | `resolve-library-id`, `get-library-docs` | Access up-to-date library documentation |
-| `time` | `get-current-time` | Query times in any timezone |
-| Custom | Varies | Add your own MCP servers |
-
-Configure MCP servers in `~/.codemie/config.json` to extend available tools.
-
-### Tool Features
-
-- **Path Validation**: All operations restricted to allowed directories
-- **Symlink Protection**: Prevents escaping allowed directories
-- **Ignore Patterns**: Automatically excludes node_modules, .git, etc.
-- **Indentation Preservation**: Smart editing maintains code formatting
-- **Unified Diffs**: Shows clear before/after changes
-- **Command Sanitization**: Blocks dangerous commands (rm -rf /, sudo, etc.)
-
----
-
-## 🔒 Security Features
-
-CodeMie Code implements multiple security layers:
-
-### Filesystem Security
-
-✅ **Path Validation**
-- All paths validated against allowed directories
-- No directory traversal attacks (../)
-- Absolute path resolution
-
-✅ **Symlink Protection**
-- Symlinks resolved and validated
-- Target paths must be within allowed directories
-
-✅ **Ignore Patterns**
-- Automatically excludes sensitive directories
-- Default: `node_modules`, `.git`, `__pycache__`, `.venv`, `dist`, `build`
+```bash
+# Token expired
+codemie auth refresh
 
-### Command Security
+# Connection issues
+codemie doctor                    # Full system diagnostics
+codemie auth status              # Check auth-specific issues
 
-The `execute_command` tool blocks dangerous patterns:
+# Complete re-authentication
+codemie auth logout
+codemie auth login --url https://your-airun-codemie-instance.com
 
-```typescript
-🚫 rm -rf /              // Recursive delete on root
-🚫 mkfs                  // Filesystem formatting
-🚫 dd if=                // Disk operations
-🚫 wget ... | sh         // Download and execute
-🚫 curl ... | sh         // Download and execute
-🚫 sudo                  // Privilege escalation
-🚫 chmod 777             // Unsafe permissions
-🚫 > /etc/               // Writing to system config
-🚫 > /dev/               // Writing to devices
-🚫 :(){ :|:& };:         // Fork bomb
+# Reset all configuration
+codemie config reset
+codemie setup                    # Run wizard again
 ```
 
-### Security Best Practices
+### Enterprise SSO Features
 
-1. **Set Allowed Directories**: Only the working directory is accessible
-2. **Review Changes**: Always review diffs before applying
-3. **Use Version Control**: Work in git repositories
-4. **Test in Isolation**: Test in separate environments first
+AI/Run CodeMie SSO provides enterprise-grade features:
 
----
+- **Secure Token Storage**: Credentials stored in system keychain
+- **Automatic Refresh**: Seamless token renewal without interruption
+- **Multi-Model Access**: Access to Claude, GPT, and other models through unified gateway
+- **Audit Logging**: Enterprise audit trails for security compliance
+- **Role-Based Access**: Model access based on organizational permissions
 
-## 🎨 Usage Examples
+## Examples
 
-### Example 1: Code Review
+### Common Workflows
 
 ```bash
-codemie-code
+# Code review workflow
+codemie-code "Review this PR for security issues and performance"
 
-You: Read src/utils/helper.ts and review the code
-Assistant: [Reads file, provides detailed review with suggestions]
+# Bug fixing
+codemie-claude -p "Fix the authentication bug in src/auth.ts"
 
-You: Create a test file for this module
-Assistant: [Creates tests/utils/helper.test.ts with test cases]
-```
+# Test generation
+codemie-codex --task "Generate comprehensive tests for the API endpoints"
 
-### Example 2: Refactoring
+# Documentation
+codemie-code "Document the functions in utils/helpers.js"
 
-```bash
-You: Show me all files in src/components
-Assistant: [Lists component files]
-
-You: Read Button.tsx and refactor it to use hooks
-Assistant: [Shows diff with proposed changes]
-
-You: Apply those changes
-Assistant: [Applies edits and shows confirmation]
+# Refactoring
+codemie-claude -p "Refactor this component to use React hooks"
 ```
 
-### Example 3: Git Workflow
+### Configuration Examples
 
 ```bash
-You: Show me the current git status
-Assistant: [Shows modified, staged, and untracked files]
+# Setup with different providers
+codemie config set provider openai
+codemie config set model gpt-4o
+codemie config set apiKey sk-your-key
 
-You: Show diff for src/app.ts
-Assistant: [Displays git diff]
+# Temporary model override
+codemie-claude --model claude-4-5-sonnet -p "Explain this algorithm"
 
-You: Show the last 5 commits
-Assistant: [Shows commit history]
+# Debug mode for troubleshooting
+codemie-code --debug --task "analyze performance issues"
 ```
 
-### Example 4: Project Setup
+### Advanced Usage
 
 ```bash
-You: Create a new directory called "api"
-Assistant: [Creates directory]
+# Run specific agent versions
+codemie run claude --version latest
 
-You: Create index.ts in api/ with a basic Express setup
-Assistant: [Creates file with boilerplate code]
+# Pass custom arguments
+codemie-codex --temperature 0.1 --max-tokens 2000 "Generate clean code"
 
-You: Create a README.md in api/ documenting the API
-Assistant: [Creates documentation]
+# Health checks
+codemie doctor                   # Full system check
+codemie-code health             # Built-in agent check
+codemie-claude health           # Claude agent check
 ```
 
-### Example 5: Search and Replace
+## Agents
 
-```bash
-You: Search for all files containing "TODO"
-Assistant: [Lists files with TODO comments]
+### CodeMie Native (Built-in)
 
-You: Read components/Header.tsx
-Assistant: [Shows file content]
-
-You: Replace the TODO with an implementation
-Assistant: [Shows diff and applies changes]
-```
+LangGraph-based coding assistant with no installation required.
 
----
+**Features:**
+- Modern terminal UI with streaming responses
+- File operations, git integration, command execution
+- Clipboard support with automatic image detection
+- Interactive conversations with context memory
+- Task-focused execution mode
+- Debug mode with comprehensive logging
 
-## 🐛 Troubleshooting
+**Usage:**
+```bash
+codemie-code                    # Interactive mode
+codemie-code --task "task"      # Single task
+codemie-code --debug            # Debug mode
+```
 
-### Common Issues
+### Claude Code
 
-#### "Base URL not configured"
+Anthropic's official CLI with advanced code understanding.
 
-**Solution:**
-```bash
-export CODEMIE_BASE_URL="https://your-ai-proxy.com"
-export CODEMIE_AUTH_TOKEN="your-token"
-export CODEMIE_MODEL="claude-4-5-sonnet"
-```
+**Installation:** `codemie install claude`
 
-#### "Connection test failed"
+**Features:**
+- Advanced code understanding and generation
+- Multi-file editing capabilities
+- Project-aware context
+- Interactive conversations
 
-**Possible causes:**
-1. Invalid CODEMIE_AUTH_TOKEN
-2. CODEMIE_BASE_URL not accessible
-3. Network/VPN issues
+### Codex
 
-**Solution:**
-```bash
-# Verify URL is accessible
-curl -I $CODEMIE_BASE_URL
+OpenAI's code generation assistant optimized for completion tasks.
 
-# Check environment variables
-echo $CODEMIE_BASE_URL
-echo $CODEMIE_AUTH_TOKEN
-echo $CODEMIE_MODEL
+**Installation:** `codemie install codex`
 
-# Run doctor
-codemie doctor
+**Features:**
+- Code completion and generation
+- Function generation and bug fixing
+- Code explanation and documentation
+- **Requires OpenAI-compatible models only**
 
-# Try test again
-codemie-code test
-```
+## Troubleshooting
 
-#### "Command not found: codemie"
+### Command Not Found
 
-**Solution:**
 ```bash
-# Re-install globally
-npm install -g @codemieai/code
-
-# Or re-link the package (from source)
-cd /path/to/codemie-code
+# Re-link the package
 npm link
-
-# Verify
 which codemie
-which codemie-code
-```
 
-#### "Path outside allowed directories"
+# Check installation
+npm list -g @codemieai/code
+```
 
-**Solution:**
-CodeMie Code only operates within the working directory for security.
+### Configuration Issues
 
 ```bash
-# Start in the correct directory
-cd /path/to/your/project
-codemie-code
+# Run setup wizard
+codemie setup
+
+# Check current config
+codemie config list
 
-# Or specify the directory
-codemie-code /path/to/your/project
+# Reset if needed
+codemie config reset
 ```
 
-#### Environment Variables Not Loaded
+### Connection Problems
 
 ```bash
-# Verify variables are set
-env | grep CODEMIE_
+# Run diagnostics
+codemie doctor
 
-# If empty, reload shell profile
-source ~/.bashrc  # or ~/.zshrc
+# Test specific agent
+codemie-code health
+codemie-claude health
 
-# Or export again
-export CODEMIE_BASE_URL="..."
-export CODEMIE_AUTH_TOKEN="..."
-export CODEMIE_MODEL="..."
+# Debug mode for detailed logs
+codemie-code --debug
 ```
 
-### Debug Mode
-
-Enable debug logging to diagnose issues:
+### Agent Installation Failures
 
 ```bash
-export CODEMIE_DEBUG="true"
-codemie-code
-```
+# Check internet connection
+curl -I https://api.github.com
 
-Debug mode shows:
-- Tool initialization details
-- AI request/response info
-- File operation details
-- Error stack traces
+# Clear npm cache
+npm cache clean --force
 
-### Clean Installation
+# Retry installation
+codemie install claude
+```
 
-If you encounter persistent issues:
+### Model Compatibility Errors
 
-```bash
-# Clean build
-rm -rf dist/ node_modules/
-npm install
-npm run build
-
-# Re-link
-npm link
-```
+When you see "Model not compatible" errors:
 
----
+1. Check your configured model: `codemie config get model`
+2. Run the agent to see compatible options
+3. Set a compatible model: `codemie config set model gpt-4o`
+4. Or override temporarily: `codemie-codex --model gpt-4o`
 
-## 📊 Architecture
+## Development
 
-### Package Structure
+### Project Structure
 
 ```
 codemie-code/
-├── bin/
-│   ├── codemie-code.js      # AI assistant entry point
-│   └── codemie.js           # CLI wrapper entry point
-│
+├── bin/                    # Executable entry points
+│   ├── codemie.js         # Main CLI
+│   ├── codemie-code.js    # Built-in agent
+│   ├── codemie-claude.js  # Claude shortcut
+│   └── codemie-codex.js   # Codex shortcut
 ├── src/
-│   ├── code/                # CodeMie Code Assistant
-│   │   ├── index.ts         # Main assistant class
-│   │   ├── agent.ts         # LangChain ReAct agent
-│   │   ├── agent-events.ts  # Event system for streaming
-│   │   ├── config.ts        # Configuration loader
-│   │   ├── prompts.ts       # System prompts
-│   │   └── tools/           # Tool implementations
-│   │       ├── filesystem.ts   # 10 filesystem tools
-│   │       ├── git.ts          # 4 git tools
-│   │       ├── command.ts      # Command execution
-│   │       ├── mcp.ts          # MCP integration
-│   │       └── diff-utils.ts   # Diff utilities
-│   │
-│   ├── cli/                 # CLI Wrapper
-│   │   └── commands/        # CLI commands
-│   │       ├── list.ts
-│   │       ├── install.ts
-│   │       ├── run.ts
-│   │       ├── doctor.ts
-│   │       ├── uninstall.ts
-│   │       ├── version.ts
-│   │       └── mcp.ts
-│   │
-│   ├── agents/              # Agent System
-│   │   ├── registry.ts      # Agent registry
-│   │   └── adapters/        # Agent adapters
-│   │       ├── codemie-code.ts
-│   │       ├── claude-code.ts
-│   │       ├── codex.ts
-│   │       └── aider.ts
-│   │
-│   ├── env/                 # Environment Management
-│   │   └── manager.ts
-│   │
-│   ├── ui/                  # UI Layer
-│   │   └── terminal-ui.ts   # Interactive terminal
-│   │
-│   └── utils/               # Utilities
-│       ├── env-mapper.ts    # Environment variable mapping
-│       ├── exec.ts          # Process execution
-│       ├── logger.ts        # Logging
-│       ├── errors.ts        # Error classes
-│       └── tips.ts          # Loading tips
-│
-├── tests/                   # Test files
-│   └── integration/         # Integration tests
-│
-├── dist/                    # Build output (TypeScript compilation)
-├── mcp/                     # MCP server configurations
-│   └── servers.json
-├── package.json             # Dependencies and scripts
-├── tsconfig.json            # TypeScript configuration
-├── eslint.config.mjs        # ESLint configuration
-└── README.md                # Package documentation
+│   ├── agents/            # Agent registry and adapters
+│   ├── cli/               # CLI command implementations
+│   ├── env/               # Environment and config management
+│   ├── workflows/         # Workflow management
+│   ├── tools/             # VCS tools management
+│   └── utils/             # Shared utilities
+└── tests/                 # Test files
 ```
 
-### Technology Stack
-
-- **Language**: TypeScript (ES2022, NodeNext modules)
-- **Runtime**: Node.js >= 24.0.0 (LTS Krypton)
-- **Package Manager**: npm
-- **LLM Framework**: LangChain 1.x (`@langchain/core`, `@langchain/langgraph`, `@langchain/openai`)
-- **LLM Provider**: Any OpenAI-compatible API
-- **CLI Framework**: Commander.js
-- **Schema Validation**: Zod
-- **Diff Generation**: diff package
-- **UI**: Chalk, Inquirer, Ora
-- **Testing**: Jest with ts-jest
-- **Linting**: ESLint with TypeScript support
-
----
-
-## 🔄 Roadmap
-
-### Current Status (v1.0.0)
-
-✅ **Implemented**:
-- Built-in AI coding assistant
-- CLI wrapper for multiple agents
-- 10 filesystem tools with security
-- 4 git operation tools
-- 1 command execution tool
-- MCP (Model Context Protocol) integration
-- Diff-based file editing
-- Agent management (install/uninstall/run)
-- Health check and diagnostics
-- Interactive terminal UI with cancellation support
-- One-off task execution with `exec` command
-
-### Planned Features (v1.1.0+)
-
-- 🎨 Custom themes and output formats
-- 📦 Enhanced plugin system for custom tools
-- 🌐 Multi-language support
-- 📊 Usage analytics and insights
-- 🔌 VS Code extension integration
-- 🤖 More agent adapters (Cursor, Copilot, etc.)
-- 🔍 Advanced MCP server discovery and management
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
-
-### Development Setup
+### Building
 
 ```bash
-# Clone repository
-git clone https://github.com/codemie-ai/codemie-code.git
-cd codemie-code
-
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Watch mode (for development)
-npm run dev
-
-# Test locally
-npm link
-codemie doctor
+npm run build              # Compile TypeScript
+npm run dev                # Watch mode
+npm run lint               # Check code style
+npm run test               # Run tests
+npm run ci                 # Full CI pipeline
 ```
 
-### Running Tests
+### Testing
 
 ```bash
-# Run all tests
-npm test
-
-# Run with coverage
-npm run test:coverage
-
-# Run specific test
-npm test -- path/to/test
-
-# Manual integration tests
-node tests/test-streaming.js
-node tests/test-agent-direct.js
-```
-
----
-
-## 📄 License
-
-MIT License - see LICENSE file for details
-
----
-
-## 🙏 Acknowledgments
-
-- Built with [LangChain](https://js.langchain.com/)
-- Inspired by [Aider](https://github.com/paul-gauthier/aider) and [Claude Code](https://claude.com/code)
-- CLI framework by [Commander.js](https://github.com/tj/commander.js)
-- MCP specification by [Anthropic](https://github.com/modelcontextprotocol/specification)
-
----
-
-## 📞 Support
-
-For issues, questions, or contributions:
-- 🐛 Report bugs via [GitHub Issues](https://github.com/codemie-ai/codemie-code/issues)
-- 💬 Ask questions in [Discussions](https://github.com/codemie-ai/codemie-code/discussions)
-- 📖 Read the full [User Guide](docs/USER_GUIDE.md)
-
----
-
-## Quick Reference
-
-### Essential Commands
-
-```bash
-# Setup
-export CODEMIE_BASE_URL="https://your-ai-proxy.com"
-export CODEMIE_AUTH_TOKEN="your-token"
-export CODEMIE_MODEL="claude-4-5-sonnet"
-
-# Verify
+npm run build && npm link
+codemie --help
 codemie doctor
-codemie-code test
-
-# Start coding
-codemie-code
-codemie-code /path/to/project
-codemie-code exec "task description"
-
-# MCP
-codemie-code mcp list
-codemie-code --mcp-servers time,context7
-
-# CLI Wrapper
-codemie list
-codemie install claude-code
-codemie run claude-code
+codemie-code health
 ```
 
-### Common Tasks
+## License
 
-| What you want | Command |
-|---------------|---------|
-| Start interactive coding | `codemie-code` |
-| Execute single task | `codemie-code exec "task"` |
-| Test connection | `codemie-code test` |
-| Check system health | `codemie doctor` |
-| List MCP servers | `codemie-code mcp list` |
-| Install agent | `codemie install <agent>` |
-| Show versions | `codemie version` |
+Apache-2.0
 
----
+## Links
 
-**Made with ❤️ by the CodeMie Team**
+- [GitHub Repository](https://github.com/codemie-ai/codemie-code)
+- [Issue Tracker](https://github.com/codemie-ai/codemie-code/issues)
+- [NPM Package](https://www.npmjs.com/package/@codemieai/code)