npm package: @godwin-ngabo/ai-coding-agent
Description: Production-ready AI coding agent system for IDE integration
Author: AI Systems Engineer
Latest version: 1.0.0

# AI Coding Agent

A production-ready AI-powered coding assistant that integrates with IDEs like VS Code, providing intelligent code generation, modification, and analysis capabilities.

## Features

- **Natural Language Commands**: Generate and modify code using plain English
- **Multi-file Editing**: Handle complex projects with multiple files
- **IDE Integration**: Native VS Code extension support
- **Web Dashboard**: Optional web-based interface
- **Safety Features**: Automatic backups and confirmation prompts
- **Project Context Awareness**: Understands your codebase structure
- **Multiple AI Models**: Support for OpenAI, Anthropic, and other models via OpenRouter

## Quick Start

### Prerequisites

- Node.js 18+ 
- OpenRouter API key (get one at [openrouter.ai](https://openrouter.ai))

### Installation

1. **Clone and install**:
```bash
git clone <repository-url>
cd ai-agent
npm install
```

2. **Configure API key**:
```bash
# Option 1: Environment variable
export OPENROUTER_API_KEY="your-api-key-here"

# Option 2: Interactive setup
npm run setup
```

3. **Install globally** (optional):
```bash
npm link
```

### Basic Usage

#### CLI Tool
```bash
# Generate code
ai-agent "create a login component with validation"

# Modify existing code
ai-agent "optimize the performance of this function"

# Analyze code
ai-agent "analyze this file for security issues"

# Explain code
ai-agent "explain how this authentication system works"
```

#### VS Code Extension
1. Install the extension from the `extension/` directory
2. Open Command Palette (`Ctrl+Shift+P`)
3. Run "AI Agent: Setup AI Agent"
4. Start using commands like:
   - "AI Agent: Execute AI Agent"
   - "AI Agent: Explain Selected Code"
   - "AI Agent: Optimize Selected Code"

#### Web Dashboard
```bash
cd web-ui
npm install
npm start
```
Visit `http://localhost:3000` to access the web interface.

## Architecture

### Core Components

```
ai-agent/
|
|-- src/                          # Core source code
|   |-- cli/                      # CLI tool components
|   |-- prompt/                   # Prompt generation system
|   |-- files/                    # File system management
|   |-- agent/                    # AI agent core
|   `-- utils/                    # Shared utilities
|
|-- extension/                    # VS Code extension
|-- web-ui/                       # Web dashboard
|-- config/                       # Configuration files
`-- docs/                         # Documentation
```

### Data Flow

```
User Input -> Command Parser -> Prompt Generator -> AI API -> Response Parser -> File Editor -> Output
```

## Configuration

### CLI Configuration

Create `config/user.json` or use environment variables:

```json
{
  "api": {
    "provider": "openrouter",
    "model": "openai/gpt-3.5-turbo",
    "maxTokens": 4000,
    "temperature": 0.7
  },
  "cli": {
    "confirmChanges": true,
    "createBackups": true,
    "maxFilesPerRequest": 50
  },
  "backup": {
    "enabled": true,
    "directory": ".ai-agent-backups"
  }
}
```

### Environment Variables

```bash
OPENROUTER_API_KEY=your-key-here
AI_AGENT_MODEL=openai/gpt-4
AI_AGENT_MAX_TOKENS=4000
AI_AGENT_LOG_LEVEL=info
```

### VS Code Settings

```json
{
  "aiAgent.apiKey": "your-api-key",
  "aiAgent.model": "openai/gpt-3.5-turbo",
  "aiAgent.autoApply": false,
  "aiAgent.createBackups": true
}
```

## Commands Reference

### CLI Commands

```bash
# Execute AI agent
ai-agent "your task description"

# Setup configuration
ai-agent setup

# Show status
ai-agent status

# View configuration
ai-agent config --show

# Reset configuration
ai-agent config --reset
```

### VS Code Commands

- `ai-agent.execute` - Execute AI Agent
- `ai-agent.setup` - Setup AI Agent  
- `ai-agent.status` - Show Status
- `ai-agent.openPanel` - Open AI Agent Panel
- `ai-agent.quickChat` - Quick Chat with AI
- `ai-agent.explainCode` - Explain Selected Code
- `ai-agent.optimizeCode` - Optimize Selected Code
- `ai-agent.generateTests` - Generate Tests for Selection

### Keyboard Shortcuts

- `Ctrl+Shift+A` - Execute AI Agent
- `Ctrl+Shift+/` - Quick Chat
- `Ctrl+Shift+E` - Explain Selected Code
- `Ctrl+Shift+O` - Optimize Selected Code

## Prompt Examples

### Code Generation
```bash
# Create components
ai-agent "create a React login form with email/password validation and error handling"

# Build APIs
ai-agent "create a REST API for user management with CRUD operations"

# Add features
ai-agent "add dark mode toggle to this application"
```

### Code Modification
```bash
# Refactoring
ai-agent "refactor this function to use async/await instead of promises"

# Performance
ai-agent "optimize this database query for better performance"

# Security
ai-agent "add input validation and sanitization to this form"
```

### Code Analysis
```bash
# Security review
ai-agent "analyze this authentication code for security vulnerabilities"

# Code review
ai-agent "review this component for React best practices"

# Documentation
ai-agent "generate comprehensive documentation for this API"
```

## File Operations

### Supported File Types
- JavaScript/TypeScript (.js, .jsx, .ts, .tsx)
- Python (.py)
- Java (.java)
- C/C++ (.c, .cpp, .h, .hpp)
- Web (.html, .css, .scss)
- Data (.json, .xml, .yaml)
- Documentation (.md, .txt)

### Safety Features
- **Automatic Backups**: Creates backups before modifications
- **Confirmation Prompts**: User approval for destructive changes
- **Rollback Capability**: Undo recent changes
- **Validation**: Syntax checking before applying changes

### Output Format

The AI agent follows this format for code changes:

```
FILE: filename.js
<complete code content>

FILE: another-file.js
<complete code content>
```

## API Integration

### OpenRouter Setup

1. Sign up at [openrouter.ai](https://openrouter.ai)
2. Get your API key
3. Configure in the agent:
   ```bash
   export OPENROUTER_API_KEY="your-key"
   ```

### Supported Models

- OpenAI: GPT-3.5 Turbo, GPT-4
- Anthropic: Claude 3 Haiku, Claude 3 Sonnet
- Meta: Llama 3 70B
- And more via OpenRouter

### Rate Limiting

Built-in rate limiting prevents API abuse:
- Requests per minute: 60 (configurable)
- Requests per hour: 1000 (configurable)
- Automatic retry with exponential backoff

## Development

### Project Structure

```
ai-agent/
|-- src/cli/           # Command-line interface
|-- src/prompt/        # Prompt generation
|-- src/files/         # File system operations
|-- src/agent/         # AI agent core
|-- src/utils/         # Utilities
|-- extension/         # VS Code extension
|-- web-ui/           # Web dashboard
|-- tests/            # Test files
|-- docs/             # Documentation
```

### Running Tests

```bash
# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage
```

### Building

```bash
# Build all components
npm run build

# Build extension only
npm run build:extension

# Build web UI only
npm run build:web
```

### Development Mode

```bash
# CLI development
npm run dev

# Web UI development
cd web-ui && npm run dev

# Extension development
cd extension && npm run watch
```

## Troubleshooting

### Common Issues

**API Key Error**:
```bash
# Set environment variable
export OPENROUTER_API_KEY="your-key"

# Or run setup
ai-agent setup
```

**Module Error**:
```bash
# Install dependencies
npm install

# Use .mjs extension for ES modules
node agent.mjs "your task"
```

**Permission Denied**:
```bash
# Check file permissions
ls -la your-file.js

# Fix permissions
chmod 644 your-file.js
```

### Debug Mode

Enable verbose logging:
```bash
ai-agent --verbose "your task"
```

Or set log level in config:
```json
{
  "logging": {
    "level": "debug"
  }
}
```

### Getting Help

```bash
# Show help
ai-agent --help

# Check status
ai-agent status

# View logs
tail -f logs/agent.log
```

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make changes and add tests
4. Run tests: `npm test`
5. Submit a pull request

### Code Style

- Use ES6+ features
- Follow the existing code style
- Add JSDoc comments
- Include error handling
- Write unit tests

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and updates.

## Support

- **Documentation**: Check the `docs/` directory
- **Issues**: Report bugs on GitHub
- **Discussions**: Use GitHub Discussions for questions
- **Community**: Join our Discord server

## Roadmap

- [ ] Support for more AI providers
- [ ] Advanced code analysis features
- [ ] Team collaboration features
- [ ] Plugin system for custom integrations
- [ ] Mobile app support
- [ ] Advanced debugging tools

---

**Built with Node.js, Express, VS Code Extension API, and modern web technologies.**