npm package: @kolaborate/kola-code
Description: Terminal-based AI coder powered by OpenRouter API
Author: Kolaborate Team
Latest version: 1.1.0

# Kola-Code

A secure, terminal-based AI coding assistant powered by OpenRouter API with DeepSeek R1 as the default model.

## 🚀 Quick Start for Kolaborate Team

### 1. Install (30 seconds)
```bash
curl -fsSL https://raw.githubusercontent.com/kolaborateplatform/AI-Agents/main/kola-code/install.sh | bash
```

### 2. Get API Key (1 minute)
- Visit https://openrouter.ai/
- Sign up/login
- Go to https://openrouter.ai/keys
- Create a new key (it's free!)

### 3. Login
```bash
kola-code login
# Paste your API key when prompted
```

### 4. Initialize Your Project (Optional but Recommended)
```bash
# Generate project context file
kola-code init
```

### 5. Start Using!
```bash
# Quick question
kola-code "how do I center a div?"

# Interactive chat
kola-code chat

# Analyze your code
kola-code chat -f app.js -p "optimize this code"
```

## Features

- 🔐 Secure API key storage using system keychain
- 💬 Interactive chat sessions with AI models
- 📄 File context support for code analysis
- 🎨 Beautiful terminal UI with custom branding
- ⚙️ Configurable model selection and parameters
- 🚀 Fast and lightweight CLI tool
- 🆓 Default model: DeepSeek R1 (free tier)
- 🔧 Advanced MCP tools integration:
  - 📁 **Filesystem**: read, write, list files  
  - 🧠 **Memory**: persistent conversation memory and knowledge graphs
  - 🤔 **Sequential Thinking**: step-by-step reasoning for complex problems
  - 📚 **Context7**: up-to-date documentation from official sources

## 🔮 Upcoming Features

We're constantly working to enhance Kola-Code. Here's what's coming soon:

### ✅ Recently Implemented
- ✅ **Memory Integration**: Persistent conversation memory with knowledge graphs
- ✅ **Context7 Integration**: Up-to-date documentation from official sources  
- ✅ **Sequential Thinking**: Step-by-step reasoning for complex problems
- ✅ **Enhanced Command System**: Instant suggestions and smart completions
- ✅ **Cross-Platform Support**: Full Windows, macOS, and Linux compatibility

### 🔮 Coming Soon
- ⚙️ **Custom System Prompts**: Personalized AI behavior and team standards
- 🔐 **Enhanced Authentication**: Multiple providers and team management
- 🛠️ **VS Code Integration**: Dedicated extension for seamless development
- 📊 **Analytics & Insights**: Usage metrics and code quality recommendations

> 💡 **Want a specific feature?** [Open an issue](https://github.com/kolaborateplatform/AI-Agents/issues) or reach out to our team!

## Installation

### For Kolaborate Team (Recommended)

**Option 1: Quick Install Script** (Easiest)
```bash
curl -fsSL https://raw.githubusercontent.com/kolaborateplatform/AI-Agents/main/kola-code/install.sh | bash
```

**Option 2: Manual Install**
```bash
# Clone the repository
git clone https://github.com/kolaborateplatform/AI-Agents.git
cd AI-Agents/kola-code

# Install dependencies and build
npm install
npm run build

# Install globally
npm install -g .
```

**Option 3: Direct from GitHub** 
```bash
# Download and install in one command
npx degit kolaborateplatform/AI-Agents/kola-code kola-code-temp && cd kola-code-temp && npm install && npm run build && npm install -g . && cd .. && rm -rf kola-code-temp
```

### Alternative Installation Methods

#### Using npm (when published)
```bash
npm install -g @kolaborate/kola-code
```

#### From source
```bash
git clone https://github.com/kolaborateplatform/AI-Agents.git
cd AI-Agents/kola-code
npm install
npm run build
npm link
```

## Setup

1. Get your OpenRouter API key from [OpenRouter](https://openrouter.ai/)
2. Run the login command:

**For Development/Local Testing:**
```bash
# If you cloned the repo and are developing locally
npm run dev login
```

**For Installed Version:**
```bash
# If you installed globally via npm
kola-code login
```

3. Enter your API key when prompted (it will be stored securely)

## Common Use Cases

### 🐛 Debug Code
```bash
# Debug an error
kola-code "TypeError: Cannot read property 'map' of undefined"

# Analyze error logs
kola-code chat -f error.log -p "what's causing this error?"
```

### 🔍 Code Review
```bash
# Security review
kola-code chat -f api.js -p "check for security vulnerabilities"

# Performance optimization
kola-code chat -f app.js -p "how can I make this faster?"
```

### 💡 Generate Code
```bash
# Create components
kola-code "create a React navbar component with dropdown"

# Write functions
kola-code "write a Python function to validate email addresses"
```

### 📚 Learn & Explain
```bash
# Explain code
kola-code chat -f algorithm.py -p "explain how this works"

# Learn concepts
kola-code "explain async/await in JavaScript with examples"
```

## All Commands

### Essential Commands
- `kola-code login` - Store your OpenRouter API key securely
- `kola-code init` - Initialize project context (creates kola.md)
- `kola-code chat` - Start interactive chat session
- `kola-code "your question"` - Quick one-off question

### Additional Commands
- `kola-code status` - Check authentication status
- `kola-code config` - Configure settings (model, temperature, etc.)
- `kola-code mcp` - Configure MCP servers (enable/disable memory, thinking, etc.)
- `kola-code logout` - Remove stored credentials
- `kola-code --help` - Show all commands

### Chat Options
- `-f, --file <path>` - Include a file in the conversation
- `-p, --prompt <text>` - Initial prompt for the chat
- `-m, --model <model>` - Use a specific AI model
- `--no-tools` - Disable MCP filesystem tools

### Using MCP Tools

Kola-Code includes MCP (Model Context Protocol) filesystem tools that allow the AI to:
- Read files from your project
- Write and create new files
- List directory contents
- Search for files

### Slash Commands

All commands now use the `/` prefix for clarity:
- `/help` (or `/h`) - Show all available commands
- `/tools` (or `/t`) - List available MCP tools
- `/stats` (or `/s`) - Show session statistics
- `/model` (or `/m`) - Show current AI model
- `/context` (or `/ctx`) - Show loaded context files
- `/clear` (or `/c`) - Clear conversation history
- `/exit` (or `/q`) - Exit the chat

**Pro tip**: Just type `/` and you'll see command suggestions!

### Rich Terminal UI

Kola-Code features an enhanced terminal experience:
- 📊 **Token Usage**: See prompt/completion tokens for each response
- ⏱️ **Response Time**: Track how long each response takes
- 💰 **Cost Tracking**: Automatic cost calculation (free for DeepSeek)
- 🔧 **Tool Tracking**: See which tools were used in each response
- 📈 **Session Statistics**: Track total usage with `/stats` command

Example metrics line:
```
⏱️ 2.3s | 📊 Tokens: 1.2k → 450 (1.7k total) | 🔧 Tools: read_file, list_directory
```

The AI can use these tools to help you with tasks like:
```bash
# Generate code and save to file
kola-code "create a React component for a user profile and save it to UserProfile.jsx"

# Analyze project structure
kola-code "list all JavaScript files in the src directory and analyze the project structure"

# Refactor code
kola-code "read the api.js file and refactor it to use async/await"
```

## Security

- API keys are stored in your system's secure keychain (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux)
- No credentials are stored in plain text
- All API communications use HTTPS

## Configuration

Run `kola-code config` to customize:
- Default AI model
- Temperature (creativity level)
- Max tokens (response length)

## Troubleshooting

### "Command not found" after installation
```bash
# Try reopening your terminal or run:
source ~/.bashrc  # or ~/.zshrc for zsh users
```

### API Key Issues
```bash
# Check if you're logged in
kola-code status

# Re-login if needed
kola-code logout
kola-code login
```

### Installation Failed
```bash
# Try manual installation
git clone https://github.com/kolaborateplatform/AI-Agents.git
cd AI-Agents/kola-code
npm install
npm run build
npm install -g .
```

## 📚 Documentation

### For Developers
**📖 [Complete Developer Guide](docs/DEVELOPER_GUIDE.md)** - Comprehensive guide covering:
- Architecture & design patterns
- MCP integration details
- Cross-platform development
- Command system implementation
- Publishing & release workflows
- Recent improvements & changelog

### Quick Development Setup
```bash
# Clone and setup
git clone https://github.com/kolaborateplatform/AI-Agents.git
cd AI-Agents/kola-code
npm install

# Run in development mode
npm run dev

# Quick dev cycle (build, install, chat)
npm run dev:chat
```

### Additional Documentation
- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
- **[Cross-Platform Guide](docs/CROSS_PLATFORM.md)** - Platform compatibility details
- **[MCP Integration](docs/MCP_INTEGRATION.md)** - Model Context Protocol setup
- **[Publishing Guide](docs/PUBLISHING.md)** - NPM publishing instructions

## Support

- 📧 Email: support@kolaborate.com
- 🐛 Issues: https://github.com/kolaborateplatform/AI-Agents/issues
- 📚 Docs: See QUICK_START.md for detailed guide

## License

MIT © Kolaborate Team