Code Agent CLI

An intelligent code analysis and modification tool built with Mastra framework that can work on any codebase.

Features

• Comprehensive Code Analysis: Understands project structure, languages, and frameworks
• File Operations: Read, write, and edit files with safety checks
• Code Search: Powerful grep and glob pattern matching
• Command Execution: Run bash commands with proper timeouts
• LSP Integration: Get diagnostics, hover info, and symbol information
• Testing Support: Run tests across multiple frameworks
• Web Research: Fetch documentation and resources when needed
• Interactive Mode: Chat with the agent about your codebase

Setup

1. Install dependencies:

   bun install

2. Set up environment variables:

   cp .env.example .env

   Edit .env and add your OpenRouter API key:

   OPENROUTER_API_KEY=your_openrouter_api_key_here
   CODE_MODEL=google/gemini-2.5-flash  # or anthropic/claude-3.7-sonnet

   Get your API key from: https://openrouter.ai/keys

Usage

Basic Usage

Analyze any codebase by providing a folder path:

bun run cli /path/to/your/project

With Specific Task

Give the agent a specific task to perform:

bun run cli /path/to/your/project -t "Add error handling to all API calls"

Or:

bun run cli /path/to/your/project "Refactor the authentication system"

Interactive Mode

Start an interactive session where you can chat with the agent:

bun run cli /path/to/your/project -i

Advanced Options

# Use a different AI model
bun run cli /path/to/your/project -m "anthropic/claude-3.7-sonnet"

# Combine task with interactive mode
bun run cli /path/to/your/project -t "Analyze the code quality" -i

# Show help
bun run cli --help

Examples

1. Analyze a New Project

bun run cli ./my-react-app

The agent will:

• Explore the directory structure
• Identify React as the framework
• Check package.json and dependencies
• Look for documentation
• Provide insights about the project structure

2. Add Features

bun run cli ./my-api -t "Add input validation to all endpoints"

3. Debug Issues

bun run cli ./my-app -t "Find and fix any TypeScript errors" -i

4. Code Review

bun run cli ./my-project -t "Review the code for security vulnerabilities and performance issues"

Available Tools

The code agent has access to these powerful tools:

• readTool: Read files with line limits and offset support
• editTool: Advanced string replacement with fallback strategies
• writeTool: Create new files with directory structure validation
• bashTool: Execute shell commands with safety checks
• grepTool: Text search using ripgrep with regex support
• listTool: Directory listing with tree structure
• globTool: Pattern-based file matching
• webfetchTool: Fetch web content and documentation
• lspDiagnosticsTool: Get syntax errors and type checking
• lspHoverTool: Get symbol information and documentation
• testTool: Run tests using various frameworks
• patchTool: Apply patches and diffs safely

Safety Features

• File Validation: Checks file paths and permissions before operations
• Command Timeouts: Prevents hanging operations
• Safe Execution: Avoids destructive commands
• Backup Creation: Creates backups before applying patches
• Dry-run Mode: Preview changes before applying them

Development

Run Tests

bun test

Type Checking

bun run typecheck

Development Mode (Mastra Server)

bun run dev

Troubleshooting

Common Issues

1. Missing API Key:

   ❌ Error: OPENROUTER_API_KEY environment variable is required
   

   Solution: Set your OpenRouter API key in the .env file

2. Folder Not Found:

   ❌ Error: Folder './my-project' does not exist
   

   Solution: Check the path and ensure the folder exists

3. Permission Issues: Make sure you have read/write permissions for the target folder

Getting Help

• Use bun run cli --help for command options
• Check the OpenRouter API status if you get API errors
• Ensure your API key has sufficient credits

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

ISC License