Skip to content

USAGE.md

Latest commit

 

History

History
370 lines (264 loc) · 6.6 KB

USAGE.md

File metadata and controls

370 lines (264 loc) · 6.6 KB

Usage Guide - Ollama Code

Installation

cd /home/core/dev/bricked-code/ollama-code
npm install
npm run build

# Optional: Install globally
npm run link

Basic Usage

Start Interactive Chat (Default)

# Using npm dev
npm run dev

# Or after global install
ollama-code

# Or explicitly with 'chat' command
ollama-code chat

CLI Flags & Options

Select a Specific Model

# Use Qwen3-Coder (best for code)
npm run dev -- chat --model qwen3-coder:30b

# Use GPT-OSS (best for reasoning)
npm run dev -- chat --model gpt-oss:20b

# Use Llama 3.1 (fastest)
npm run dev -- chat --model llama3.1:8b

Enable Verbose Mode

# See all tool calls and iterations
npm run dev -- chat --verbose

# Short form
npm run dev -- chat -v

Combine Options

# Qwen3-Coder with verbose output
npm run dev -- chat -m qwen3-coder:30b -v

# GPT-OSS with custom temperature
npm run dev -- chat -m gpt-oss:20b -t 0.5

# All options
npm run dev -- chat -m qwen3-coder:30b -v -t 0.7 --url http://localhost:11434

Custom Ollama Server

# Connect to remote Ollama
npm run dev -- chat --url http://192.168.1.100:11434

# Or use environment variable
export OLLAMA_URL=http://192.168.1.100:11434
npm run dev

Quick Commands

# Check health
npm run dev -- health

# List models
npm run dev -- models

# Show help
npm run dev -- --help
npm run dev -- chat --help

Example Sessions

Example 1: File Operations

$ npm run dev -- chat -m qwen3-coder:30b -v

ollama-code> Create a file called hello.txt with "Hello World!"

[Iteration 1]
Tool calls: write_file
✓ Response: File created successfully: hello.txt

ollama-code> Now read that file
[Iteration 1]
Tool calls: read_file
✓ Response:
1→Hello World!

Example 2: Code Search

$ npm run dev -- chat -m qwen3-coder:30b

ollama-code> Find all TypeScript files in the src directory

✓ Response: Found 15 TypeScript files:
src/cli.ts
src/cli/repl.ts
src/llm/agent.ts
src/llm/model-manager.ts
...

Example 3: Complex Task

$ npm run dev -- chat -m gpt-oss:20b -v

ollama-code> Search for all files containing "OllamaClient", then read the main one

[Iteration 1]
Tool calls: grep
[Files found: src/llm/ollama-client.ts, src/llm/agent.ts]

[Iteration 2]
Tool calls: read_file
[Reading src/llm/ollama-client.ts]

✓ Response: The OllamaClient class provides...
[Shows summary of the file]

Environment Variables

# Ollama server URL
export OLLAMA_URL=http://localhost:11434

# Default model
export DEFAULT_MODEL=qwen3-coder:30b

# Then start
npm run dev

Configuration File

Create ~/.ollama-code/config.json:

{
  "ollamaUrl": "http://localhost:11434",
  "defaultModel": "qwen3-coder:30b",
  "temperature": 0.7,
  "maxTokens": 4096
}

REPL Commands

Once in the REPL:

/help          Show help
/models        List available models
/model NAME    Switch to a different model
/verbose       Toggle verbose mode
/clear         Clear conversation history
/exit          Exit REPL

Example Workflows

Workflow 1: Code Review

# Start with Qwen3-Coder for code analysis
ollama-code chat -m qwen3-coder:30b

> Find all .ts files in src/tools
> Read the file-ops.ts file
> Explain what the write_file function does
> Are there any potential bugs?

Workflow 2: Project Exploration

# Use verbose mode to see tool usage
ollama-code chat -v

> What TypeScript files exist in this project?
> Show me the directory structure
> Search for all occurrences of "ToolManager"

Workflow 3: Development Assistant

# Use GPT-OSS for planning, then Qwen for coding
ollama-code chat -m gpt-oss:20b

> Plan a new feature: add support for JSON file validation
> /model qwen3-coder:30b
> Implement the JSON validation tool we discussed

Advanced Usage

Direct Tool Testing

# Run the tool test suite
npx tsx test-simple.ts

# Run integration tests
npx tsx test-integration.ts

Development Mode

# Watch mode (auto-rebuild on changes)
npm run watch

# In another terminal, run
npm run dev

Custom Script with Ollama Code

import { Agent } from './src/llm/agent.js';
import { ModelManager } from './src/llm/model-manager.js';
import { ToolManager } from './src/tools/tool-manager.js';
import { ConfigManager } from './src/config/index.js';
import { allTools } from './src/tools/index.js';

const config = new ConfigManager();
await config.load();

const toolManager = new ToolManager();
toolManager.registerTools(allTools);

const modelManager = new ModelManager(config.get());
await modelManager.initialize();

const agent = new Agent(config.get(), toolManager, modelManager);

const response = await agent.run('List all files in src/', {
  verbose: true,
  model: 'qwen3-coder:30b'
});

console.log(response);

Troubleshooting

"Cannot connect to Ollama server"

# Check if Ollama is running
ollama list

# If not, start it
ollama serve

# Or specify a different URL
ollama-code chat --url http://localhost:11434

Model Not Found

# List available models
ollama list

# Pull a model if needed
ollama pull qwen3-coder:30b
ollama pull gpt-oss:20b
ollama pull llama3.1:8b

# Verify
ollama-code models

Tool Call Not Working

Some models have better tool calling support than others:

  • ✅ Llama 3.1 - Excellent tool calling
  • ⚠️ Qwen3-Coder - Understands tools but uses non-standard format
  • ⚠️ GPT-OSS - Variable support

For best results, use: -m llama3.1:8b

Performance Tips

  1. Use smaller models for simple tasks

    ollama-code chat -m llama3.1:8b

  2. Lower temperature for deterministic outputs

    ollama-code chat -t 0.3

  3. Use verbose mode only when debugging

    # Adds overhead
ollama-code chat -v

  4. Enable GPU acceleration

    • Ensure NVIDIA drivers are installed
    • Ollama automatically uses GPU if available

Comparison with Similar Tools

vs Aider

# Aider
aider --model gpt-4

# Ollama Code (100% local)
ollama-code chat -m qwen3-coder:30b

vs GitHub Copilot CLI

# Copilot (cloud-based)
gh copilot suggest "list files"

# Ollama Code (local)
ollama-code chat -m llama3.1:8b
> list files in current directory

Next Steps

  1. Try the examples above
  2. Explore different models
  3. Create custom workflows
  4. Contribute to the project

Support

  • 📖 README: README.md
  • 🔧 Implementation: IMPLEMENTATION.md
  • 🚀 Quick Start: QUICKSTART.md
  • 🧪 Test Report: TEST-REPORT.md
  • 📝 This guide: USAGE.md

Happy Coding with Ollama Code! 🚀