Package Exports

@codemieai/code
@codemieai/code/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@codemieai/code) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

🤖 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

📦 Installation

From npm (when published)

npm install -g @codemieai/code

From Source (Development)

# 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

Verify Installation

# Check if commands are available
codemie --help
codemie-code --help

# Run health check
codemie doctor

🚀 Quick Start

1. Set Up Environment Variables

CodeMie Code requires AI provider credentials:

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:

# 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

codemie-code test

Expected output:

✓ Configuration loaded
✓ Testing connection...
✓ Connection successful
✓ Model: claude-4-5-sonnet

3. Start the Assistant

# In current directory
codemie-code

# In specific directory
codemie-code /path/to/your/project

# Execute one-off task
codemie-code exec "Add error handling to api.ts"

4. Interact with the Assistant

╔═══════════════════════════════════════╗
║       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

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

# Enable debug logging
export CODEMIE_DEBUG="true"

# Timeout for AI requests (seconds)
export CODEMIE_TIMEOUT="300"

# Load specific MCP servers
export CODEMIE_MCP_SERVERS="time,context7"

MCP Configuration

Configure MCP (Model Context Protocol) servers in ~/.codemie/config.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:

# Load specific MCP servers
export CODEMIE_MCP_SERVERS="context7,time"
codemie-code

# Or with CLI flag
codemie-code --mcp-servers context7,time

When no --mcp-servers flag is provided, all servers configured in ~/.codemie/config.json are loaded automatically.

Configuration Methods

Method 1: Shell Environment (Recommended)

# 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

Method 2: Project .env File

# 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

Method 3: Inline

CODEMIE_BASE_URL="https://your-ai-proxy.com" \
CODEMIE_AUTH_TOKEN="your-token" \
CODEMIE_MODEL="claude-4-5-sonnet" \
codemie-code

Advanced: Provider-Specific Configuration

For advanced scenarios, you can use provider-specific environment variables. These act as fallbacks if generic CODEMIE_* variables are not set:

For Anthropic Claude:

export ANTHROPIC_BASE_URL="https://api.anthropic.com"
export ANTHROPIC_AUTH_TOKEN="your-anthropic-token"
export ANTHROPIC_MODEL="claude-4-5-sonnet"

For OpenAI GPT:

export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_API_KEY="your-openai-key"
export OPENAI_MODEL="gpt-4"

Configuration Priority:

CODEMIE_* (generic - checked first)
ANTHROPIC_* or OPENAI_* (provider-specific - fallback)

🎯 Usage

CodeMie Code Assistant

The built-in AI assistant with filesystem, git, and command execution tools.

# Interactive mode (default)
codemie-code
codemie-code /path/to/project

# Execute one-off task
codemie-code exec "Add error handling to api.ts"

# 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

Interactive Commands

Once inside the assistant:

exit - Exit the assistant
clear - Clear conversation history
Any coding question or task

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

MCP Server Management

Extend capabilities with Model Context Protocol servers.

# List available servers
codemie-code mcp list

# List with detailed configuration
codemie-code mcp list -v

# Add new server
codemie-code mcp add <name> <command-or-url> [options]

# Test server configuration
codemie-code mcp test <server-name>

# Remove server
codemie-code mcp remove <server-name>

# Preview which servers will load
codemie-code mcp servers
codemie-code mcp servers --servers time,context7

Popular MCP Servers

Time Server - Query times in any timezone:

codemie-code mcp add time uvx -a "mcp-server-time"
codemie-code --mcp-servers time

# Then ask: "What time is it in Hong Kong?"

Context7 - Access up-to-date library documentation:

codemie-code mcp add context7 npx -a "-y" "@upstash/context7-mcp"
codemie-code --mcp-servers context7

# Then ask: "Show me LangChain documentation for chains"

CLI Wrapper (codemie)

Manage multiple AI coding agents from one interface.

List Available Agents

codemie list                    # List all agents
codemie list --installed        # List only installed agents

Install Agents

codemie install claude-code     # Install Anthropic Claude Code
codemie install aider           # Install Aider
codemie install codex           # Install OpenAI Codex

Run Agents

# Run built-in CodeMie Code
codemie run codemie-code

# Run other agents
codemie run claude-code
codemie run aider
codemie run codex

# With custom model
codemie run codemie-code --model claude-opus

# Pass additional arguments
codemie run aider --no-auto-commits

Uninstall Agents

codemie uninstall claude-code
codemie uninstall aider

Health Check

codemie doctor

Checks:

✅ Node.js version (>= 24.0.0)
✅ npm installation
✅ git availability
✅ Environment variables configuration
✅ Installed agents

Version Information

codemie version
codemie-code --version

🛠️ 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

Git Tools (4 tools)

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

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

Command Security

The execute_command tool blocks dangerous patterns:

🚫 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

Security Best Practices

Set Allowed Directories: Only the working directory is accessible
Review Changes: Always review diffs before applying
Use Version Control: Work in git repositories
Test in Isolation: Test in separate environments first

🎨 Usage Examples

Example 1: Code Review

codemie-code

You: Read src/utils/helper.ts and review the code
Assistant: [Reads file, provides detailed review with suggestions]

You: Create a test file for this module
Assistant: [Creates tests/utils/helper.test.ts with test cases]

Example 2: Refactoring

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]

Example 3: Git Workflow

You: Show me the current git status
Assistant: [Shows modified, staged, and untracked files]

You: Show diff for src/app.ts
Assistant: [Displays git diff]

You: Show the last 5 commits
Assistant: [Shows commit history]

Example 4: Project Setup

You: Create a new directory called "api"
Assistant: [Creates directory]

You: Create index.ts in api/ with a basic Express setup
Assistant: [Creates file with boilerplate code]

You: Create a README.md in api/ documenting the API
Assistant: [Creates documentation]

Example 5: Search and Replace

You: Search for all files containing "TODO"
Assistant: [Lists files with TODO comments]

You: Read components/Header.tsx
Assistant: [Shows file content]

You: Replace the TODO with an implementation
Assistant: [Shows diff and applies changes]

🐛 Troubleshooting

Common Issues

"Base URL not configured"

Solution:

export CODEMIE_BASE_URL="https://your-ai-proxy.com"
export CODEMIE_AUTH_TOKEN="your-token"
export CODEMIE_MODEL="claude-4-5-sonnet"

"Connection test failed"

Possible causes:

Invalid CODEMIE_AUTH_TOKEN
CODEMIE_BASE_URL not accessible
Network/VPN issues

Solution:

# Verify URL is accessible
curl -I $CODEMIE_BASE_URL

# Check environment variables
echo $CODEMIE_BASE_URL
echo $CODEMIE_AUTH_TOKEN
echo $CODEMIE_MODEL

# Run doctor
codemie doctor

# Try test again
codemie-code test

"Command not found: codemie"

Solution:

# Re-install globally
npm install -g @codemieai/code

# Or re-link the package (from source)
cd /path/to/codemie-code
npm link

# Verify
which codemie
which codemie-code

"Path outside allowed directories"

Solution: CodeMie Code only operates within the working directory for security.

# Start in the correct directory
cd /path/to/your/project
codemie-code

# Or specify the directory
codemie-code /path/to/your/project

Environment Variables Not Loaded

# Verify variables are set
env | grep CODEMIE_

# If empty, reload shell profile
source ~/.bashrc  # or ~/.zshrc

# Or export again
export CODEMIE_BASE_URL="..."
export CODEMIE_AUTH_TOKEN="..."
export CODEMIE_MODEL="..."

Debug Mode

Enable debug logging to diagnose issues:

export CODEMIE_DEBUG="true"
codemie-code

Debug mode shows:

Tool initialization details
AI request/response info
File operation details
Error stack traces

Clean Installation

If you encounter persistent issues:

# Clean build
rm -rf dist/ node_modules/
npm install
npm run build

# Re-link
npm link

📊 Architecture

Package Structure

codemie-code/
├── bin/
│   ├── codemie-code.js      # AI assistant entry point
│   └── codemie.js           # CLI wrapper entry point
│
├── 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

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:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Development Setup

# 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

Running Tests

# 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
Inspired by Aider and Claude Code
CLI framework by Commander.js
MCP specification by Anthropic

📞 Support

For issues, questions, or contributions:

🐛 Report bugs via GitHub Issues
💬 Ask questions in Discussions
📖 Read the full User Guide

Quick Reference

Essential Commands

# Setup
export CODEMIE_BASE_URL="https://your-ai-proxy.com"
export CODEMIE_AUTH_TOKEN="your-token"
export CODEMIE_MODEL="claude-4-5-sonnet"

# Verify
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

Common Tasks

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`

Made with ❤️ by the CodeMie Team