npm package: @pedrocid/ollama-assistant
Description: Interactive CLI for the Ollama Assistant AI coding companion
Author: Pedro Cid
Latest version: 0.1.1

# 🤖 Ollama Assistant

An intelligent AI coding companion powered by Ollama - your local development assistant that helps you code, debug, and learn without sending your data to the cloud.

## ✨ Features

- 🔒 **100% Local** - Your code never leaves your machine
- 🛠️ **Tool Integration** - Read, write, and execute files safely
- 💬 **Interactive Chat** - Natural conversation with your AI assistant
- 🚀 **Fast Setup** - Automatic Ollama installation and model recommendations
- 🎯 **Smart Recommendations** - Optimized model selection based on your system
- 🔧 **Flexible Usage** - Interactive and non-interactive modes

## 🚀 Quick Start

### Option 1: Use with npx (Recommended)
```bash
npx @pedrocid/ollama-assistant
```

### Option 2: Global Installation
```bash
npm install -g @pedrocid/ollama-assistant
ollama-assistant
```

### Option 3: One-time Commands
```bash
npx @pedrocid/ollama-assistant -p "Create a React component for a login form"
```

## 📋 Prerequisites

- **Node.js** 18+ 
- **Ollama** (will be installed automatically if not present)

## 🎯 Usage

### Interactive Mode (Default)
Start a conversational session with your AI assistant:

```bash
ollama-assistant
```

Example conversation:
```
🧑 You: Create a Python function to calculate fibonacci numbers

🤖 Assistant: I'll create a Python function to calculate Fibonacci numbers for you.

🔧 Executing write_file...
⚠️ Execute write_file with {"path":"fibonacci.py","content":"def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n-1) + fibonacci(n-2)"} ? (y/N): y

✅ Successfully wrote 94 characters to fibonacci.py
```

### Non-Interactive Mode
Execute single commands:

```bash
# Create files
ollama-assistant -p "Create a package.json for a React app"

# Code review
ollama-assistant -p "Review the code in ./src/app.js and suggest improvements"

# Auto-approve all actions (use with caution)
ollama-assistant -p "Refactor my code" --yolo
```

### Available Options

| Option | Description |
|--------|-------------|
| `-p, --prompt` | Run in non-interactive mode with a specific prompt |
| `-m, --model` | Override the default model (e.g., `llama3.1:8b`) |
| `--yolo` | Auto-approve all tool executions (⚠️ use with caution) |
| `--help` | Show help information |
| `--version` | Show version number |

## 🛡️ Safety Features

- **Confirmation Prompts** - All file operations require your approval
- **Path Validation** - Prevents writing outside your project directory
- **Blacklist Protection** - Blocks dangerous files (.env, .git/, etc.)
- **Sandbox Mode** - Safe execution environment

## 🔧 Commands (Interactive Mode)

| Command | Description |
|---------|-------------|
| `/help` | Show available commands |
| `/clear` | Clear chat history |
| `/exit` or `/quit` | Exit the application |

## 🧠 Supported Models

The assistant automatically recommends the best model for your system:

- **llama3.1:8b** - Best balance of performance and capability
- **llama3.2:3b** - Faster responses, good for basic tasks  
- **qwen2.5:7b** - Excellent coding capabilities

## 🔧 Advanced Usage

### Custom Model
```bash
ollama-assistant -m "codellama:13b"
```

### Batch Processing
```bash
echo "Create a REST API with Express.js" | ollama-assistant --yolo
```

### Project-Specific Assistant
```bash
cd my-project
ollama-assistant -p "Analyze this codebase and suggest architectural improvements"
```

## 🐛 Troubleshooting

### Ollama Server Issues
```bash
# Check if Ollama is running
ollama list

# Start Ollama manually
ollama serve
```

### Permission Issues
```bash
# macOS/Linux: Fix npm permissions
sudo npm install -g @pedrocid/ollama-assistant

# Or use npx to avoid global installation
npx @pedrocid/ollama-assistant
```

### Model Download Failed
```bash
# Manually pull a model
ollama pull llama3.1:8b
```

## 📝 Examples

### Create a Complete React Component
```bash
ollama-assistant -p "Create a React component with TypeScript for a user profile card with avatar, name, email, and status indicator"
```

### Code Review
```bash
ollama-assistant -p "Review my Python script for security vulnerabilities and performance improvements"
```

### Documentation Generation
```bash
ollama-assistant -p "Generate comprehensive documentation for the functions in my utils.js file"
```

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

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

## 🙏 Acknowledgments

- Built with [Ollama](https://ollama.ai/) for local AI inference
- Powered by state-of-the-art language models
- Inspired by the open-source AI community

---

**Made with ❤️ by Pedro Cid**

Need help? [Open an issue](https://github.com/pedrocid/ollama-assistant/issues) or start a discussion!