ollama-prompt 1.1.8

Ollama CLI prompt tool for local LLM code analysis

ollama-prompt

Quick Start • Documentation • Use Cases • Contributing

---

What is ollama-prompt?

A lightweight Python CLI that transforms Ollama into a powerful analysis tool with:

• Session persistence - Multi-turn conversations with full context
• Structured JSON output - Token counts, timing, and metadata
• File references - Inline local files with @file syntax
• Multi-agent orchestration - Perfect for subprocess workflows

Perfect for: Code review, analysis pipelines, agent systems, and cost-aware LLM workflows

Features

• Session Management - Persistent conversations across CLI invocations
• Rich Metadata - Full JSON output with token counts, timing, and cost tracking
• File References - Reference local files with @./path/to/file.py syntax
• Subprocess-Friendly - Designed for agent orchestration and automation
• Cloud & Local Models - Works with both Ollama cloud models and local instances
• Cross-Platform - Windows, macOS, Linux with Python 3.7+

---

Quick Start

Prerequisites: Ollama CLI installed (server starts automatically)

# 1. Install
pip install ollama-prompt

# 2. First question (creates session automatically)
ollama-prompt --prompt "What is 2+2?"

# 3. Follow-up with context
ollama-prompt --session-id <id-from-output> --prompt "What about 3+3?"

Session created automatically! See session_id in output.

Next steps: 5-Minute Tutorial | Full CLI Reference

---

Installation

PyPI (Recommended)

pip install ollama-prompt

Development Install

git clone https://github.com/dansasser/ollama-prompt.git
cd ollama-prompt
pip install -e .

Prerequisites

• Python 3.7 or higher
• Ollama installed and running
• For cloud models: ollama signin (one-time authentication)

Verify installation:

ollama-prompt --help
ollama list  # Check available models

Full setup guide: Prerequisites Documentation

---

Usage

Basic Example

ollama-prompt --prompt "Explain Python decorators" \
              --model deepseek-v3.1:671b-cloud

Multi-Turn Conversation

# First question
ollama-prompt --prompt "Who wrote Hamlet?" > out.json

# Follow-up (remembers context)
SESSION_ID=$(jq -r '.session_id' out.json)
ollama-prompt --session-id $SESSION_ID --prompt "When was he born?"

File Analysis

ollama-prompt --prompt "Review @./src/auth.py for security issues"

Stateless Mode

ollama-prompt --prompt "Quick question" --no-session

More examples: Use Cases Guide with 12 real-world scenarios

---

Documentation

Complete Documentation - Full guide navigation and reference

Quick Links:

• 5-Minute Quick Start
• Session Management Guide
• Complete CLI Reference

---

Use Cases

Software Development:

• Multi-file code review with shared context
• Iterative debugging sessions
• Architecture analysis across modules

Multi-Agent Systems:

• Subprocess-based agent orchestration
• Context-aware analysis pipelines
• Cost tracking for LLM operations

Data Analysis:

• Sequential data exploration with memory
• Research workflows with source tracking
• Report generation with conversation history

See all 12 scenarios: Use Cases Guide

---

Why ollama-prompt?

vs. Direct Ollama API:

• Session persistence (no manual context management)
• Structured JSON output (token counts, timing, metadata)
• File reference syntax (no manual file reading)

vs. Other CLI Tools:

• Session-first design (context by default)
• Subprocess-optimized (perfect for agent orchestration)
• Local-first (SQLite, no cloud dependency)

Built for:

• Developers building agent systems
• Code analysis automation
• Cost-aware LLM workflows
• Multi-turn conversations at scale

Architecture: Subprocess Best Practices | Architectural Comparison

---

Troubleshooting

• If you get ModuleNotFoundError: ollama, ensure you ran pip install ollama in the correct Python environment.
• Ensure Ollama CLI is installed (ollama --version should work). The server starts automatically when needed.
• For maximum context windows, check your model's max token support.
• Unexpected session_id in output? Sessions are auto-created by default in v1.2.0+. This is normal behavior. Use --no-session for stateless operation.
• Session context not persisting? Ensure you're using the same --session-id value across invocations. Use --list-sessions to see available sessions.

---

Contributing

We welcome contributions! Here's how to get started:

Development Setup:

git clone https://github.com/dansasser/ollama-prompt.git
cd ollama-prompt
pip install -e .

Running Tests:

pytest

Contribution Guidelines:

• Fork the repo and create a branch
• Write tests for new features
• Follow existing code style
• Submit PR with clear description

Areas We Need Help:

• Documentation improvements
• New use case examples
• Bug reports and fixes
• Feature suggestions

Questions? Open an issue or discussion.

---

Community & Support

• Bug Reports: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/README.md
• Troubleshooting: Reference Guide

---

License

MIT License - see LICENSE file for details.

Third-Party Licenses:

• Uses Ollama (separate licensing)

---

Credits

Author: Daniel T. Sasser II

• GitHub: github.com/dansasser
• Blog: dansasser.me

Built With:

• Ollama - Local LLM runtime
• Python - Language and ecosystem

Acknowledgments:

• Inspired by the need for structured, cost-aware LLM workflows
• Built for the AI agent orchestration community

---

PyPI Package