🤖 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)

npx @pedrocid/ollama-assistant

Option 2: Global Installation

npm install -g @pedrocid/ollama-assistant
ollama-assistant

Option 3: One-time Commands

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:

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:

# 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

ollama-assistant -m "codellama:13b"

Batch Processing

echo "Create a REST API with Express.js" | ollama-assistant --yolo

Project-Specific Assistant

cd my-project
ollama-assistant -p "Analyze this codebase and suggest architectural improvements"

🐛 Troubleshooting

Ollama Server Issues

# Check if Ollama is running
ollama list

# Start Ollama manually
ollama serve

Permission Issues

# 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

# Manually pull a model
ollama pull llama3.1:8b

📝 Examples

Create a Complete React Component

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

Code Review

ollama-assistant -p "Review my Python script for security vulnerabilities and performance improvements"

Documentation Generation

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 file for details.

🙏 Acknowledgments

• Built with Ollama 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 or start a discussion!