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: Terminal AI assistants (Claude, Codex, Gemini CLI), subprocess orchestration, and cost-aware workflows

Primary Use Case: AI Agent Subprocess Integration

Built for terminal-based AI assistants: Claude, Codex, Gemini CLI, and other interactive AI tools.

When terminal AI agents need deep analysis but must preserve their context window, they delegate to ollama-prompt as a subprocess:

How Claude Uses This:

1. Context Preservation - Claude delegates heavy analysis without consuming its 200K token budget
2. Structured Parsing - JSON output with token counts, timing, and session IDs
3. File Reference Chaining - @file syntax lets Claude reference multiple files in one call
4. Session Continuity - Multi-turn analysis without manual context management

Example Claude Code Workflow:

# Claude delegates codebase analysis to ollama-prompt
ollama-prompt --prompt "Analyze @./src/auth.py for security issues" \
              --model deepseek-v3.1:671b-cloud \
              > analysis.json

# Claude parses JSON response and continues with its own reasoning

Who Uses This:

• Primary: Terminal AI assistants (Claude, Codex, Gemini CLI, Cursor)
• Secondary: Python scripts orchestrating multi-agent workflows
• Advanced: Custom AGI systems with local Ollama backends

Learn More: Subprocess Best Practices | Architectural Comparison

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
• Directory Operations - List, tree view, and search with @./dir/ syntax (full read access within repo root)
• Secure File Access - TOCTOU-safe operations with path validation via llm-fs-tools
• 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.10+

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.10 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"

Directory Operations

Reference entire directories with the @./dir/ syntax:

# List directory contents
ollama-prompt --prompt "What's in @./src/?"

# Show directory tree
ollama-prompt --prompt "Show the structure: @./src/:tree"

# Search for pattern in files
ollama-prompt --prompt "Find TODO comments: @./src/:search:TODO"

⚠️ Security Note: ollama-prompt has read access to all files and directories within the current working directory (repository root). File operations are TOCTOU-safe and validate paths to prevent traversal attacks, but the tool can read any accessible file. Only run in trusted directories.

Directory Syntax:

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?

ollama-prompt is a specialized tool. It's not a general-purpose CLI, but an automation-first subprocess designed to be called by other AI agents (like Claude or Gemini) to preserve their primary context window.

This table clarifies its niche compared to other common tools:

Comparison of Ollama Interaction Methods

Built for:

• Terminal AI assistants (Claude, Codex, Gemini CLI) - Delegate analysis via subprocess
• Context preservation - Save your AI's token budget for reasoning
• Multi-agent systems - Orchestrate parallel analysis tasks
• Cost-aware workflows - Track token usage explicitly

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