CodeMode Agent

A Claude agent with an execute tool that provides programmatic access to file operations, system commands, and MCP tools. Features interactive mode with real-time typing, persistent execution context, and seamless integration with multiple MCP servers.

Features

• Interactive Mode: Real-time command input with Escape key to hide/show typing prompt
• Execute Tool: Run JavaScript code with persistent context across executions
• Built-in Functions: Read, Write, Edit, Glob, Grep, Bash, LS, WebFetch, WebSearch, TodoWrite
• MCP Integration: Glootie, Playwright, and Vexify tools available as functions
• Persistent Context: Variables persist across execute calls within the same session
• Signal Handling: Proper Ctrl-C support for graceful shutdown
• Syntax Highlighting: Colorized code blocks and formatted output
• Extended Thinking: 10,000 token thinking budget with real-time streaming

Installation

npm install -g codemode-agent

Or use with npx (no installation required):

npx codemode-agent --agent "Your task here"

Usage

CodeMode supports two modes: Agent Mode (interactive) and MCP Server Mode.

Agent Mode (Interactive)

Run Claude agent with execute tool for autonomous task completion:

# Interactive mode (default)
codemode-agent --agent "Create a React component"

# Single execution mode (non-interactive)
codemode-agent --agent "Fix bugs" --no-interactive

# Using npx
npx codemode-agent --agent "Your task here"

Interactive Mode Features

• Type anytime: Start typing to show the input prompt automatically
• Escape key: Press Escape to hide the typing prompt
• Ctrl-C: Gracefully exit at any time
• Streaming output: Watch the agent think and work in real-time

MCP Server Mode

Start the MCP server that provides the execute tool:

# Start MCP server
codemode-agent --mcp

# Using npx
npx codemode-agent --mcp

# Disable external MCP servers (built-in tools only)
codemode-agent --mcp --nomcp

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "codeMode": {
      "command": "npx",
      "args": ["codemode-agent", "--mcp"]
    }
  }
}

Examples

Basic File Operations

# Create a file
codemode-agent --agent "Create a file called test.txt with content 'Hello World'"

# Search code
codemode-agent --agent "Find all JavaScript files and count the lines of code"

# Edit files
codemode-agent --agent "Replace all console.log with logger.info in src/"

Web Automation

# Navigate and extract data
codemode-agent --agent "Navigate to example.com and get the page title"

# Screenshot capture
codemode-agent --agent "Take a screenshot of github.com"

# Form automation
codemode-agent --agent "Fill out the contact form on example.com"

Code Analysis

# Semantic search
codemode-agent --agent "Find all authentication-related functions"

# AST pattern matching
codemode-agent --agent "Find all useState calls with initial value of null"

# Codebase audit
codemode-agent --agent "List all TODO comments with their locations"

Available Functions

File Operations

• Read(path, offset?, limit?) - Read file content with optional line ranges
• Write(path, content) - Write or overwrite file content
• Edit(path, oldString, newString, replaceAll?) - Exact string replacement in files
• Glob(pattern, path?, as_array?) - Find files matching glob patterns (returns string by default, JSON array if as_array=true)

Search Operations

• Grep(pattern, path?, options?) - Search for patterns using ripgrep
  • Options: {glob, type, output_mode, '-i', '-n', '-A', '-B', '-C', multiline, head_limit}

System Operations

• Bash(command, description?, timeout?) - Execute shell commands
• LS(path?, show_hidden?, recursive?, files_only?) - List directory contents

Web Operations

• WebFetch(url, prompt) - Fetch and analyze web content
• WebSearch(query, allowed_domains?, blocked_domains?) - Search the web

Task Management

• TodoWrite(todos) - Write and manage todo lists
  • Format: [{content, status, activeForm}]
  • Status: 'pending' | 'in_progress' | 'completed'

MCP Tools

All MCP tools are available via namespaced functions. Use serverName.toolName(params) format.

Glootie (Code Execution & Analysis)

• glootie.execute(code, runtime?, workingDirectory?, timeout?) - Execute code in various runtimes
• glootie.ast_tool(operation, workingDirectory, pattern, ...) - AST pattern matching for code structure searches
• glootie.caveat(workingDirectory, action, text?, id?) - Manage technical caveats and limitations

Playwright (Browser Automation)

• playwright.browser_navigate(url) - Navigate to URL
• playwright.browser_snapshot() - Capture accessibility snapshot
• playwright.browser_click(element, ref) - Click on element
• playwright.browser_type(element, ref, text, slowly?, submit?) - Type text into element
• playwright.browser_evaluate(function, element?, ref?) - Execute JavaScript in browser
• playwright.browser_take_screenshot(element?, ref?, filename?, type?, fullPage?) - Take screenshot
• playwright.browser_close() - Close browser
• playwright.browser_resize(width, height) - Resize browser window
• playwright.browser_console_messages(onlyErrors?) - Get console messages
• playwright.browser_handle_dialog(accept, promptText?) - Handle dialogs
• playwright.browser_file_upload(paths?) - Upload files
• playwright.browser_fill_form(fields) - Fill multiple form fields
• playwright.browser_press_key(key) - Press keyboard key
• playwright.browser_navigate_back() - Navigate back
• playwright.browser_network_requests() - Get network requests
• playwright.browser_hover(element, ref) - Hover over element
• playwright.browser_drag(startElement, startRef, endElement, endRef) - Drag and drop
• playwright.browser_select_option(element, ref, values) - Select dropdown option
• playwright.browser_tabs(action, index?) - Manage browser tabs
• playwright.browser_wait_for(text?, textGone?, time?) - Wait for conditions

Vexify (Semantic Code Search)

• vexify.search_code(query, top_k?, include_content?) - Semantic code search using embeddings

Architecture

CodeMode consists of three main components:

1. cli.js - Unified Entry Point

Routes to agent mode or MCP server mode based on command-line flags.

2. agent.js - Interactive Claude Agent

• Streams responses with real-time thinking display
• Manages interactive input with Escape key support
• Handles signal interrupts (Ctrl-C)
• Formats output with syntax highlighting
• Integrates with MCP servers via execute tool

3. code-mode.js - MCP Server

• Exposes execute tool to Claude
• Manages persistent execution context
• Spawns and manages child MCP servers
• Handles graceful shutdown of all processes
• Injects tool functions into JavaScript runtime

4. execution-worker.js - Persistent Worker

• Maintains execution context across calls
• Handles IPC communication with parent
• Manages variable persistence
• Responds to shutdown signals

5. interactive-mode.js - Input Handler

• Manages readline interface
• Handles keyboard events (typing, Escape, Ctrl-C)
• Shows/hides input prompt dynamically
• Queues commands for agent execution

Configuration

Create .codemode.json to configure MCP servers:

{
  "mcpServers": {
    "builtInTools": {
      "command": "node",
      "args": ["built-in-tools-mcp.js"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "vexify": {
      "command": "npx",
      "args": ["-y", "vexify@latest", "mcp"]
    }
  }
}

Configuration file is searched in order:

1. Current working directory: ./.codemode.json
2. Library directory: ./node_modules/codemode-agent/.codemode.json
3. User home directory: ~/.claude/.codemode.json

Persistent Execution Context

Variables persist across execute calls within the same session:

// First execute call
myVar = 42;
console.log(myVar);

// Second execute call (same session)
console.log(myVar);

Variables declared with let, const, or var do NOT persist. Use bare assignment or global.myVar for persistence.

Use clear_context() to reset the execution context.

Testing

Run the test suite:

npm test

For full integration testing:

# Start MCP server
node code-mode.js

# In another terminal
node test-builtin-tools.js

Command-Line Flags

Agent Mode

• --agent [task] - Run in agent mode with optional initial task
• --no-interactive - Run single execution without interactive mode

MCP Server Mode

• --mcp - Start MCP server mode
• --nomcp - Disable external MCP servers (built-in tools only)

Signal Handling

CodeMode properly handles interrupt signals:

• Ctrl-C (SIGINT): Gracefully shuts down all processes
• SIGTERM: Clean shutdown of worker and MCP servers
• Escape Key: Hides typing prompt in interactive mode

All child processes (MCP servers, execution worker) receive proper shutdown signals and clean up resources.

Keyboard Shortcuts

Interactive Mode

• Type: Show input prompt automatically
• Escape: Hide input prompt and clear current line
• Enter: Submit command to agent
• Ctrl-C: Exit application

Dependencies

• @anthropic-ai/claude-agent-sdk - Agent framework and streaming
• @modelcontextprotocol/sdk - MCP protocol implementation
• chalk - Terminal colors and styling
• highlight.js - Code syntax highlighting
• fast-glob - File pattern matching
• chokidar - File system watching
• uuid - Unique identifier generation
• which - Command resolution
• zod - Schema validation

Troubleshooting

Ctrl-C Not Working

If Ctrl-C doesn't interrupt execution, ensure you're running the latest version:

npm install -g codemode-agent@latest

MCP Server Timeout

For long-running operations, the timeout is set to 180 seconds. If you need longer:

Edit execution-worker.js and increase the timeout value in __callMCPTool.

Variable Not Persisting

Variables declared with let, const, or var don't persist. Use bare assignment:

// Won't persist
let myVar = 42;

// Will persist
myVar = 42;

// Will persist
global.myVar = 42;

Terminal Colors Not Showing

Ensure your terminal supports ANSI colors. For Windows, use Windows Terminal or WSL.

Version

Current version: 2.0.38

See CHANGELOG.md for full version history and recent changes.

License

MIT

Author

lanmower

Contributing

Contributions welcome! Please open an issue or submit a pull request.

Links

• GitHub Repository
• npm Package
• MCP Documentation