@codemieai/code 0.0.2 → 0.0.3

package/CLAUDE.md

@@ -17,24 +17,28 @@ npm install                 # Install dependencies
 npm link                    # Link globally for local testing
 
 # Building
-npm run build              # Compile TypeScript and copy assets (to dist/)
+npm run build              # Compile TypeScript
 npm run dev                # Watch mode for development
 
-# Testing
-npm test                   # Run all tests (Node.js native test runner)
-npm run test:watch         # Run tests in watch mode
-
-# Run individual test files
-node --test tests/agent-direct.test.mjs
-node --test tests/streaming.test.mjs
-
 # Code Quality
-npm run lint               # Check code style with ESLint
+npm run lint               # Check code style with ESLint (max 10 warnings)
 npm run lint:fix           # Fix linting issues automatically
+npm run ci                 # Run full CI pipeline (license-check + lint + build)
 
 # Development Workflow
 npm run build && npm link  # Build and link for testing
 codemie doctor             # Verify installation and configuration
+codemie-code health        # Test built-in agent health
+
+# Testing the Built-in Agent
+codemie-code --task "test"  # Single task execution
+codemie-code --debug       # Interactive with debug logging
+
+# Direct Agent Shortcuts (bypass registry)
+codemie-claude             # Direct Claude Code access
+codemie-codex              # Direct Codex access
+codemie-claude health      # Claude health check
+codemie-codex health       # Codex health check
 
 # Release & Publishing
 git tag -a v0.0.1 -m "Release version 0.0.1"  # Create release tag
@@ -55,801 +59,167 @@ git push origin v0.0.1                         # Push tag to trigger publish
 ### DRY (Don't Repeat Yourself)
 - Never duplicate code, logic, or configuration
 - Extract common patterns into reusable functions/utilities
-- Reuse existing utilities from `src/utils/` before creating new ones
+- Reuse existing utilities from \`src/utils/\` before creating new ones
 - If you find yourself copying code, refactor it into a shared function
 - One source of truth for each piece of knowledge
 
 **Remember:** Simple, clean code is better than clever, complex code.
 
-## Specialized Agents
-
-This project uses specialized subagents for complex, multi-step workflows. These agents have dedicated system prompts stored in `.claude/agents/` that can be updated independently.
-
-### Release Manager Agent
-
-**Location:** `.claude/agents/release-manager.md`
-
-**Purpose:** Automate the complete release process from change analysis to npm publication.
-
-**Trigger Phrases:**
-- "Release version X.X.X"
-- "Create a new release"
-- "Release a patch/minor/major version"
-- "Use release manager to..."
-- "Prepare a release"
-
-**What it does:**
-1. Runs pre-flight checks (clean working directory, correct branch)
-2. Analyzes git history since last release tag
-3. Categorizes commits using conventional commits
-4. Generates structured release notes (Keep a Changelog format)
-5. Updates package.json and package-lock.json version
-6. Creates git commit for version bump
-7. Creates and pushes annotated git tag
-8. Creates GitHub release with generated notes
-9. Triggers npm publish workflow via GitHub Actions
-10. Reports completion status and provides verification links
-
-**Example Usage:**
-```
-You: "Release version 0.0.2"
-
-Claude:
-1. Checks git status and current branch
-2. Analyzes 12 commits since v0.0.1
-3. Generates release notes with categorized changes
-4. Shows preview and asks for confirmation
-5. Updates package.json to 0.0.2
-6. Creates commit "chore: bump version to 0.0.2"
-7. Creates tag v0.0.2 and pushes
-8. Creates GitHub Release
-9. Reports: "✅ Released v0.0.2, npm publish workflow triggered"
-```
-
-**Customization:**
-Edit `.claude/agents/release-manager.md` to modify:
-- Release notes format
-- Commit categorization rules
-- Version bump strategies
-- Error handling behavior
-- Pre-flight check requirements
-
-### Creating Additional Agents
-
-To create your own specialized agent:
-
-1. **Create the agent file**: `.claude/agents/{role}-{function}.md`
-   - Example: `code-reviewer.md`, `test-generator.md`, `security-auditor.md`
-
-2. **Define the system prompt**: Include role, capabilities, workflow, error handling, and examples
-
-3. **Document trigger phrases**: Add them to this CLAUDE.md section
-
-4. **Update agents README**: Add documentation to `.claude/agents/README.md`
-
-**Naming convention:** `{role}-{function}.md`
-- ✅ `release-manager.md`, `code-reviewer.md`, `test-generator.md`
-- ❌ `release.md`, `agent1.md`, `helper.md`
-
-**See:** `.claude/agents/README.md` for detailed agent creation guide and best practices.
-
-## Critical Policies
-
-### Testing & Documentation Policy
-
-**IMPORTANT - Do NOT write tests, documentation, or summaries unless explicitly requested:**
-- Do NOT write tests unless user explicitly says: "Write tests", "Create unit tests", etc.
-- Do NOT run tests unless user explicitly says: "Run the tests", "Execute test suite", etc.
-- Do NOT generate documentation unless user explicitly says: "Write documentation", "Create docs", etc.
-- Do NOT write summaries unless user explicitly says: "Summarize", "Write a summary", etc.
-- Do NOT run compilation checks unless explicitly requested
-- Do NOT proactively create README files or documentation files
-
-### Node Modules Policy
-
-**IMPORTANT:**
-- NEVER modify files inside `node_modules/`
-- All source code lives in `src/`
-- All tests live in `tests/`
-- Build output goes to `dist/`
-
-### Utilities Policy
-
-**Before implementing new utility functions:**
-1. Check if similar functionality exists in `src/utils/` directory
-2. Always reuse existing utilities (logger, exec, errors, tips, etc.)
-3. If implementing new shared utilities, get user approval first
-
-### Git Workflow Policy
-
-**CRITICAL - Read the complete Git Workflow Policy:**
-
-📖 **See:** `.codemie/guides/git-workflow.md` for comprehensive git workflow guidelines
-
-**Key Requirements:**
-- ❌ **NEVER commit directly to `main` branch**
-- ✅ **ALWAYS create a feature branch** for any changes
-- ✅ **ALL changes go through Pull Request review**
-- ✅ Use conventional commit format: `type: description`
-- ✅ Follow branch naming: `feature/`, `fix/`, `docs/`, `refactor/`, `chore/`
-
-**Quick Reference:**
-```bash
-# Standard workflow
-git checkout main && git pull origin main
-git checkout -b feature/your-feature-name
-# Make changes...
-git add .
-git commit -m "feat: add something" -m "Co-authored-by: CodeMie AI <codemie.ai@gmail.com>"
-git push -u origin feature/your-feature-name
-# Create PR via GitHub UI or: gh pr create
-```
-
-**Important:** Always add CodeMie AI co-author to commits for proper attribution
-
-For detailed information on:
-- Branch naming conventions
-- Commit message guidelines
-- PR creation and review process
-- Merge conflict resolution
-- Emergency hotfixes
-- Git commands reference
-
-👉 **Read:** `.codemie/guides/git-workflow.md`
-
-### Release & Publishing Policy
-
-**IMPORTANT - How to publish to npm registry:**
-
-The project uses GitHub Actions to automatically publish to npm when a release is created. The workflow is defined in `.github/workflows/publish.yml`.
-
-**Step-by-step release process:**
-
-1. **Ensure you're on the main branch** (after merging your feature branch):
-   ```bash
-   git checkout main
-   git pull origin main
-   ```
-
-2. **Create an annotated git tag** with the version number:
-   ```bash
-   # Match the version in package.json (e.g., 0.0.1)
-   git tag -a v0.0.1 -m "Release version 0.0.1"
-   ```
-
-3. **Push the tag to GitHub**:
-   ```bash
-   git push origin v0.0.1
-   ```
-
-4. **Create a GitHub Release** (two options):
-
-   **Option A - GitHub UI (recommended):**
-   - Go to GitHub repository → Releases → "Draft a new release"
-   - Select the tag you just pushed (`v0.0.1`)
-   - Add release title (e.g., `v0.0.1` or `Release 0.0.1`)
-   - Add release notes describing changes
-   - Click "Publish release"
-
-   **Option B - Manual workflow trigger:**
-   - Go to Actions → "Publish to NPM" workflow
-   - Click "Run workflow"
-   - Select the `main` branch
-   - Click "Run workflow"
-
-5. **The workflow will automatically**:
-   - Checkout code
-   - Install dependencies
-   - Run CI checks (`npm run ci` - includes lint, build, and tests)
-   - Publish to npm with `npm publish --access public`
-   - Authenticate using the `NPM_TOKEN` secret
-
-**Prerequisites:**
-- `NPM_TOKEN` must be configured in GitHub repository secrets
-- Version in `package.json` must match the tag version (without the `v` prefix)
-- All CI checks must pass (linting, build, tests)
-
-**Version bumping:**
-```bash
-# Update version in package.json
-npm version patch    # 0.0.1 → 0.0.2
-npm version minor    # 0.0.1 → 0.1.0
-npm version major    # 0.0.1 → 1.0.0
-
-# This creates a commit and tag automatically
-# Then push both:
-git push origin main --tags
-```
-
-**Verifying the publish:**
-```bash
-# Check on npm registry
-npm view @codemieai/code
-
-# Install and test locally
-npm install -g @codemieai/code@latest
-codemie doctor
-```
-
-## Reference Implementations
-
-Study these excellent examples before implementing new code:
-- **AI Assistant** (`src/code/`) - Complete ReAct agent implementation with streaming
-- **Tool System** (`src/code/tools/`) - Filesystem, Git, Command, and MCP tools
-- **UI Layer** (`src/ui/terminal-ui.ts`) - Interactive terminal with cancellation support
-- **Agent System** (`src/agents/`) - Agent registry and adapters pattern
-
-## Communication Style
-
-When responding:
-1. Confirm your understanding of the request
-2. Reference which patterns you're following from existing code
-3. Outline your implementation approach
-4. Present complete, working code
-5. Explain key design decisions
-6. Highlight any assumptions requiring user input
-
-## Self-Verification Before Delivery
-
-- [ ] README.md and CLAUDE.md have been read and understood
-- [ ] Reference implementations reviewed for similar patterns
-- [ ] Code follows TypeScript best practices and project conventions
-- [ ] No tests written (unless explicitly requested)
-- [ ] No tests executed (unless explicitly requested)
-- [ ] Code is production-ready and follows DRY/KISS principles
-
-## Escalation Scenarios
-
-Seek user guidance when:
-- Documentation is missing, unclear, or contradictory
-- New dependencies are required
-- Breaking changes are necessary
-- Multiple valid approaches exist
-- Reference implementations don't cover the use case
-- Security or architectural concerns arise
-
 ## Project Overview
 
-**CodeMie Code** is a unified npm package that provides:
-- A built-in AI coding assistant powered by LiteLLM (via LangChain)
-- A CLI wrapper for managing multiple AI coding agents (Claude Code, Aider, Codex)
+**CodeMie** is a unified CLI wrapper for managing multiple AI coding agents, featuring:
 
-The project uses TypeScript with a ReAct agent pattern via LangGraph for autonomous tool execution.
+1. **External Agent Management**: Install and run external agents (Claude Code, Codex)
+2. **Built-in Agent**: CodeMie Native - a LangGraph-based coding assistant
+3. **Configuration Management**: Unified config system supporting multiple AI providers
+4. **Multiple Interfaces**: CLI commands, direct executables, and programmatic APIs
 
-## Quick Architecture Overview
+## Architecture Overview
 
-### Core Components
-
-- **AI Assistant** (`src/code/`): Main assistant class, agent, configuration, prompts
-- **Tool System** (`src/code/tools/`): Filesystem, Git, Command execution, MCP integration
-- **CLI Wrapper** (`src/cli/commands/`): Commands for managing external agents
-- **Agent System** (`src/agents/`): Registry and adapters for different AI agents
-- **UI Layer** (`src/ui/`): Interactive terminal with streaming and cancellation
-- **Environment** (`src/env/`, `src/utils/`): Config management and utilities
-
-### Entry Points
-- `bin/codemie-code.js` - Starts the AI assistant
-- `bin/codemie.js` - CLI wrapper for agent management
-
-### Key Design Patterns
-
-#### ReAct Agent Pattern
-Uses LangGraph's `createReactAgent`:
-1. **Reasoning** - LLM thinks about what to do
-2. **Acting** - Calls tools based on reasoning
-3. **Observing** - Receives tool results
-4. Loops until task is complete
-
-#### Streaming Architecture
-Agent supports streaming via `chatStream()`:
-- `thinking_start/end` - Agent is reasoning
-- `tool_call_start` - Tool invocation begins
-- `tool_call_result` - Tool returns result
-- `content_chunk` - Partial response content
-- `complete/cancelled/error` - Terminal states
-
-#### Security Model
-All filesystem/command operations validate:
-- Paths must be within `allowedDirectories`
-- Symlinks are resolved and validated
-- Dangerous command patterns are blocked
-- Ignore patterns exclude sensitive dirs
-
-## Project Structure
+### High-Level 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 entry
+│   ├── codemie-code.js     # Direct built-in agent executable
+│   ├── codemie-claude.js   # Claude agent wrapper
+│   └── codemie-codex.js    # Codex agent wrapper
 ├── 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    # 8 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
-│   │
-│   ├── 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
-│   ├── test-*.js                # Manual integration tests
-│   └── integration/             # Additional test scenarios
-│
-├── 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
-```
-
-## 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**: LiteLLM (OpenAI-compatible proxy)
-- **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
-
-## Configuration & Environment
-
-### Environment Variable Priority
-The config loader (`src/utils/env-mapper.ts`) checks in order:
-1. `ANTHROPIC_*` - For Claude models
-2. `OPENAI_*` - For GPT models
-3. `AI_*` - Generic provider-agnostic
-4. `LITELLM_*` - Legacy format (still supported)
-
-### Required Environment Variables
-
-```bash
-# Provider-specific (choose one set)
-
-# For Anthropic Claude models
-ANTHROPIC_BASE_URL=https://litellm-proxy.example.com
-ANTHROPIC_AUTH_TOKEN=your-token
-ANTHROPIC_MODEL=claude-4-5-sonnet
-
-# OR for OpenAI models
-OPENAI_BASE_URL=https://api.openai.com/v1
-OPENAI_API_KEY=your-token
-OPENAI_MODEL=gpt-4
-
-# OR generic provider-agnostic
-AI_BASE_URL=https://litellm-proxy.example.com
-AI_AUTH_TOKEN=your-token
-AI_MODEL=claude-4-5-sonnet
-```
-
-### Optional Environment Variables
-
-```bash
-CODEMIE_DEBUG=true                           # Enable debug logging
-CODEMIE_MODEL=claude-opus                    # Override model
-CODEMIE_MCP_SERVERS=filesystem,cli-mcp-server # Load specific MCP servers
-AI_TIMEOUT=300                               # Request timeout in seconds
-```
-
-### MCP Configuration
-MCP servers are defined in:
-1. `mcp/servers.json` - Default server configurations
-2. `~/.codemie/config.json` - User-specific MCP config
-
-MCP integration is handled by `src/code/tools/mcp.ts` which dynamically loads tools from configured servers.
-
-## Development Guidelines
-
-### File Naming Conventions
-
-- **Modules**: kebab-case (e.g., `terminal-ui.ts`, `agent-events.ts`)
-- **Classes**: PascalCase (e.g., `CodeMieCode`, `CodeMieAgent`)
-- **Functions**: camelCase (e.g., `loadConfig`, `getTools`)
-- **Constants**: UPPER_SNAKE_CASE (e.g., `SYSTEM_PROMPT`)
-- **Tests**: `test-*.js` or `*.test.ts`
-
-### Code Style
-
-- **Formatter**: TypeScript default (2 spaces)
-- **Line Length**: No strict limit, but keep reasonable
-- **Quotes**: Single quotes preferred
-- **Semicolons**: Required
-- **Imports**: Organized (standard library, third-party, local)
-- **Type Hints**: Use TypeScript types throughout
-- **Async/Await**: Preferred over promises/callbacks
-
-### Import Organization
-
-```typescript
-// Third-party imports
-import { ChatOpenAI } from '@langchain/openai';
-import { StructuredTool } from '@langchain/core/tools';
-import chalk from 'chalk';
-
-// Local imports
-import { CodeMieConfig } from './config';
-import { logger } from '../utils/logger';
-import { FilesystemTools } from './tools/filesystem';
+│   ├── cli/                # CLI command implementations
+│   ├── agents/             # Agent registry and adapters
+│   ├── env/                # Environment and config management
+│   ├── utils/              # Shared utilities
+│   └── index.ts           # Main package exports
 ```
 
-## Tool Development
-
-### Adding New Filesystem Tools
-
-Extend `FilesystemTools` class in `src/code/tools/filesystem.ts`:
-1. Create tool using `new StructuredTool()` with Zod schema
-2. Add validation via `validatePath()` or `validateInAllowedDirectory()`
-3. Push to tools array in constructor
-4. Handle errors with try-catch, return error messages
-
-Example:
-```typescript
-const myNewTool = new StructuredTool({
-  name: "my_new_tool",
-  description: "Description of what this tool does",
-  schema: z.object({
-    path: z.string().describe("File path"),
-    content: z.string().describe("File content")
-  }),
-  func: async ({ path, content }) => {
-    try {
-      const fullPath = this.validatePath(path);
-      // Tool implementation
-      return "Success message";
-    } catch (error: any) {
-      return `Error: ${error.message}`;
-    }
-  }
-});
-```
+### Core Components
 
-### Adding New Git Tools
+#### 1. Agent System (`src/agents/`)
 
-Extend `GitTools` class in `src/code/tools/git.ts` following the same pattern.
+- **Registry** (`registry.ts`): Central registry managing all available agents
+- **Adapters** (`adapters/`): Standardized interfaces for external agents
+  - `claude-code.ts`: Anthropic Claude Code integration
+  - `codex.ts`: OpenAI Codex integration
+  - `codemie-code.ts`: Built-in agent adapter
+- **Built-in Agent** (`codemie-code/`): Full LangGraph-based agent implementation
 
-### Diff-Based Editing
+#### 2. CLI System (`src/cli/`)
 
-The `edit_file` tool uses `diff` package to generate unified diffs:
-- Preserves indentation (tabs vs spaces)
-- Shows clear before/after changes
-- Validates file exists before editing
+- **Main CLI** (`index.ts`): Commander.js-based CLI with all commands
+- **Commands** (`commands/`): Individual command implementations
+  - `setup.ts`: Interactive configuration wizard
+  - `install.ts`/`uninstall.ts`: Agent management
+  - `run.ts`: Agent execution with environment passing
+  - `doctor.ts`: Health checks and diagnostics
+  - `config.ts`: Configuration management
 
-## Agent Adapters
+#### 3. Configuration System (`src/env/`)
 
-To add a new agent adapter (e.g., for Cursor or Copilot):
+- **EnvManager** (`manager.ts`): Global config at `~/.codemie/config.json`
+- **Priority**: Environment variables override config file
+- **Providers**: Anthropic, OpenAI, Azure, Bedrock, LiteLLM
+- **Model Validation**: Real-time model fetching via `/v1/models` endpoints
 
-1. Create `src/agents/adapters/my-agent.ts` implementing `AgentAdapter` interface
-2. Register in `src/agents/registry.ts`
-3. Implement required methods:
-   - `install()` - Install the agent
-   - `uninstall()` - Uninstall the agent
-   - `isInstalled()` - Check if installed
-   - `run(args)` - Run the agent
-   - `getVersion()` - Get version info
+#### 4. Built-in Agent Architecture (`src/agents/codemie-code/`)
 
-Example:
-```typescript
-export class MyAgentAdapter implements AgentAdapter {
-  name = 'my-agent';
-  displayName = 'My Agent';
-  description = 'Description of my agent';
-
-  async install(): Promise<void> { /* ... */ }
-  async uninstall(): Promise<void> { /* ... */ }
-  async isInstalled(): Promise<boolean> { /* ... */ }
-  async run(args: string[]): Promise<void> { /* ... */ }
-  async getVersion(): Promise<string | null> { /* ... */ }
-}
-```
+**Multi-layered architecture:**
 
-## Error Handling
+- **Main Interface** (`index.ts`): `CodeMieCode` class - primary API
+- **Agent Core** (`agent.ts`): `CodeMieAgent` - LangGraph integration
+- **Configuration** (`config.ts`): Provider config loading and validation
+- **Tools System** (`tools/`): Modular tool implementations
+  - `filesystem.ts`: File operations with security controls
+  - `command.ts`: Shell command execution
+  - `git.ts`: Git operations and status
+  - `security.ts`: Security filters and validation
+- **UI System** (`ui.ts`, `streaming/`): Modern terminal interfaces
+- **Types** (`types.ts`): Comprehensive TypeScript definitions
 
-### Standard Error Pattern
+### Key Architectural Patterns
 
+#### Agent Adapter Pattern
+All agents implement the `AgentAdapter` interface:
 ```typescript
-try {
-  // Operation
-  const result = await performOperation();
-  return result;
-} catch (error: any) {
-  // Log error for debugging
-  logger.error('Operation failed:', error);
-
-  // Return user-friendly error message
-  throw new Error(`Operation failed: ${error.message}`);
+interface AgentAdapter {
+  name: string;
+  displayName: string;
+  description: string;
+  install(): Promise<void>;
+  uninstall(): Promise<void>;
+  isInstalled(): Promise<boolean>;
+  run(args: string[], env?: Record<string, string>): Promise<void>;
+  getVersion(): Promise<string | null>;
 }
 ```
 
-### Custom Error Classes
-
-Located in `src/utils/errors.ts`:
-- `ConfigurationError` - Configuration issues
-- Use standard `Error` for most cases
-
-## Testing Approach
-
-### Test Framework & Structure
-
-- Uses **Node.js native test runner** (`node:test`)
-- All test files are located in `tests/` directory
-- Test files use `.mjs` extension (ES modules)
-- Tests are built using `describe()`, `it()`, `before()`, and `after()` from `node:test`
-
-### Test Categories
-
-1. **Agent Tests** - Test LLM agent functionality (requires base URL configuration)
-   - `agent-direct.test.mjs` - Direct agent tool calling
-   - `agent-output.test.mjs` - Agent output format
-   - `streaming.test.mjs` - Streaming functionality
-   - `conversation-flow.test.mjs` - Multiple question handling
-
-2. **Integration Tests** - Test `codemie-code` (AI assistant) (requires base URL configuration)
-   - `codemie-code.test.mjs` - CodeMieCode tool calling
-   - `tool-count.test.mjs` - Tool loading verification
-   - `interactive-simulation.test.mjs` - Interactive conversation simulation
-   - `ui-state.test.mjs` - UI state management
-   - `live-output.test.mjs` - Live output format
-
-3. **MCP Tests** - Test MCP server integration with AI assistant (requires base URL configuration)
-   - `mcp-context7.test.mjs` - Context7 MCP server
-   - `mcp-time-server.test.mjs` - Time MCP server
-   - `mcp-e2e.test.mjs` - End-to-end MCP integration
-   - `context7-only.test.mjs` - Context7 server only
-
-4. **UI/Format Tests** - Test formatting and UI logic (does NOT require base URL)
-   - `ui-format.test.mjs` - UI formatting
-   - `text-wrapping.test.mjs` - Text wrapping logic
-
-5. **CLI Wrapper Tests** - Test `codemie` CLI commands (does NOT require base URL)
-   - Currently no tests exist for CLI commands (`codemie doctor`, `codemie list`, etc.)
-   - These commands don't interact with LLM, so they don't need base URL configuration
-
-### Test Helpers
-
-The `tests/test-helpers.mjs` file provides utilities for managing test preconditions:
-
-**Key Functions:**
-
-```javascript
-// Check if base URL is configured
-isBaseUrlConfigured()
-
-// Skip test if base URL is not configured (with warning)
-skipIfNoBaseUrl(testContext, customMessage?)
-
-// Get list of missing environment variables
-getMissingEnvVars()
-
-// Check if all required environment variables are configured
-isFullyConfigured()
-
-// Print configuration status for debugging
-printConfigStatus()
-```
-
-**Usage Example:**
-
-```javascript
-import { describe, it, before } from 'node:test';
-import { skipIfNoBaseUrl } from './test-helpers.mjs';
-
-describe('My Test Suite', () => {
-  before(() => {
-    if (skipIfNoBaseUrl()) return;
-    // ... setup code
-  });
-
-  it('should do something', () => {
-    if (skipIfNoBaseUrl()) return;
-    // ... test code
-  });
-});
-```
-
-### Environment Variable Requirements
-
-Tests that interact with LLM agents require one of:
-- `CODEMIE_BASE_URL`
-- `ANTHROPIC_BASE_URL`
-- `OPENAI_BASE_URL`
+#### Configuration Hierarchy
+1. Environment variables (highest priority)
+2. Global config file (`~/.codemie/config.json`)
+3. Default values (lowest priority)
 
-If these are not set, tests will be **skipped with a warning** instead of failing.
+#### Tool System Architecture
+- **Modular Design**: Each tool type in separate file
+- **Security First**: All operations go through security filters
+- **Type Safety**: Full TypeScript coverage with Zod validation
+- **Error Handling**: Structured error types with context
 
-### Running Tests
+#### Execution Modes
+- **Interactive**: Full terminal UI with streaming responses
+- **Task Mode**: Single task execution with `--task` flag
+- **Health Checks**: Connection and configuration validation
 
-```bash
-# Run all tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run specific test file
-node --test tests/agent-direct.test.mjs
-
-# Run tests without base URL (will skip LLM tests)
-unset CODEMIE_BASE_URL ANTHROPIC_BASE_URL OPENAI_BASE_URL
-npm test
-
-# Run tests with debug output
-CODEMIE_DEBUG=true npm test
-```
+### Technology Stack
 
-### Writing New Tests
+- **TypeScript**: Full type safety with ES2024 + NodeNext modules
+- **Commander.js**: CLI framework with subcommands
+- **LangChain/LangGraph**: Agent orchestration and tool calling
+- **Clack**: Modern terminal user interface
+- **Chalk**: Terminal styling and colors
+- **Zod**: Runtime type validation
+- **ESLint**: Code quality (max 10 warnings allowed)
 
-**For tests requiring LLM interaction:**
-
-1. Import test helpers: `import { skipIfNoBaseUrl } from './test-helpers.mjs'`
-2. Add skip checks to `before()` hooks: `before(() => { if (skipIfNoBaseUrl()) return; ... })`
-3. Add skip checks to each test: `it('test name', () => { if (skipIfNoBaseUrl()) return; ... })`
-
-**For tests NOT requiring LLM interaction:**
-
-1. No need to import or use test helpers
-2. Tests will run regardless of environment configuration
-
-### Test Best Practices
-
-- **Always build before testing**: Run `npm run build` to ensure dist/ is up to date
-- **Use descriptive test names**: Clearly state what is being tested
-- **Clean up resources**: Use `after()` hooks to dispose of resources (agents, MCP tools, etc.)
-- **Test isolation**: Each test should be independent and not rely on state from other tests
-- **Mock external dependencies**: When possible, avoid hitting real external services
-- **Handle async properly**: Use `async/await` for asynchronous operations
-
-## Debugging
-
-Enable debug mode to see detailed execution:
-
-```bash
-export CODEMIE_DEBUG=true
-codemie-code
-```
-
-This shows:
-- Tool initialization counts
-- LLM request/response details
-- File operation details
-- Error stack traces
-
-## Important Notes
-
-### Module System
-- Uses ES modules (`"module": "NodeNext"`)
-- Import paths use `.js` extensions even for `.ts` files
-- Example: `import { logger } from '../utils/logger.js'`
-
-### TypeScript Configuration
-- Strict mode enabled
-- Declaration maps for debugging
-- Output to `dist/` directory
-- Source maps enabled
-
-### LangChain Version
-- Uses LangChain 1.x ecosystem
-- `@langchain/core` for base types
-- `@langchain/langgraph` for agent creation
-- `@langchain/openai` for ChatOpenAI model
-
-### Not a Git Repository
-- This directory is NOT initialized as a git repository
-- It's a package within a larger monorepo structure
-
-## Build Process
-
-The build process (`npm run build`):
-1. Compiles TypeScript from `src/` to `dist/`
-2. Copies `src/data/tips.json` to `dist/data/`
-3. Generates declaration files (`.d.ts`)
-4. Generates source maps
-
-## Common Patterns & Utilities
-
-### Configuration Loading
-See `src/code/config.ts` and `src/utils/env-mapper.ts` for how configuration is loaded with fallbacks.
+## Development Guidelines
 
-### Logging
-Use the shared logger from `src/utils/logger.ts`:
-```typescript
-import { logger } from '../utils/logger';
+### Working with Agent Shortcuts
 
-logger.info('Information message');
-logger.success('Success message');
-logger.error('Error message');
-logger.debug('Debug message');  // Only shown when CODEMIE_DEBUG=true
-```
+When modifying the direct agent shortcuts (`codemie-claude`, `codemie-codex`):
 
-### Process Execution
-Use utilities from `src/utils/exec.ts` for running commands.
+1. **Configuration Override Pattern**: All shortcuts support CLI overrides for:
+   - `--model`: Override model selection
+   - `--provider`: Override provider
+   - `--api-key`: Override API key
+   - `--base-url`: Override base URL
+   - `--timeout`: Override timeout
 
-### Tips System
-Loading tips are displayed during initialization from `src/data/tips.json`.
+2. **Pass-through Architecture**: Use `allowUnknownOption()` and `passThroughOptions()` to forward all unrecognized options to the underlying agent
 
-## Best Practices
+3. **Model Validation**:
+   - Codex must validate OpenAI-compatible models only
+   - Claude accepts both Claude and GPT models
+   - Provide helpful error messages with actionable suggestions
 
-1. **Modular Design**: Each component should have clear separation of concerns
-2. **Error Handling**: Always handle errors gracefully with user-friendly messages
-3. **Security**: Validate all paths and commands before execution
-4. **Reusability**: Utilize shared utilities from `src/utils/`
-5. **Documentation**: Provide comprehensive JSDoc comments for all public methods
-6. **TypeScript**: Use proper types throughout, avoid `any` when possible
-7. **Testing**: Write tests for new functionality when requested
-8. **Async/Await**: Handle async operations properly with try-catch
+4. **Health Check Pattern**: Each shortcut should implement a `health` subcommand that:
+   - Verifies agent installation
+   - Shows version information
+   - Tests basic configuration
 
-## Troubleshooting
-
-### Issue: Command not found after installation
-**Solution**: Re-link the package
-```bash
-npm link
-which codemie
-which codemie-code
-```
+### Adding New Agent Shortcuts
 
-### Issue: TypeScript compilation errors
-**Solution**: Clean build
-```bash
-rm -rf dist/
-npm run build
-```
+To add a new direct agent shortcut (e.g., `codemie-newagent`):
 
-### Issue: Import errors
-**Solution**: Check import paths use `.js` extensions and are correct
+1. Create `bin/codemie-newagent.js` following the existing pattern
+2. Add the executable to `package.json` bin field
+3. Implement the adapter in `src/agents/adapters/`
+4. Register in `src/agents/registry.ts`
+5. Update documentation in README.md and CLAUDE.md
 
-### Issue: Environment variables not loaded
-**Solution**: Check variable names match the priority order and verify with:
-```bash
-echo $ANTHROPIC_BASE_URL
-echo $AI_BASE_URL
-codemie doctor
-```
+### Built-in Agent Development
 
-## Support
+When working on the CodeMie Native agent (`src/agents/codemie-code/`):
 
-For questions or issues:
-- Review existing implementations in `src/`
-- Check test examples in `tests/`
-- Consult utilities in `src/utils/`
-- Read comprehensive `README.md`
+- **Tools**: Add new tools in `tools/` directory with proper security filtering
+- **UI**: Use Clack components for consistent terminal interface
+- **Streaming**: Implement proper event handling for real-time responses
+- **Configuration**: Follow the provider config pattern in `config.ts`
+- **Error Handling**: Use structured error types with context information