# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

orun-py is a Python CLI wrapper for interacting with local LLMs via Ollama, featuring built-in screenshot analysis and conversation history.

## Build and Development Commands

```bash
# Install dependencies (using uv)
uv sync

# Install package in development mode
uv pip install -e .

# Build distribution packages
uv build

# Publish to PyPI
uv publish

# Run the CLI directly
uv run orun "your prompt"
```

## Versioning and Release Workflow

When making changes to the package:

1. **Test functionality** by running `orun` command to verify changes work correctly
2. **Update version** in `pyproject.toml` - increment by `0.0.1` (e.g., `1.0.1` -> `1.0.2`)
   - When version reaches `X.Y.9`, next version becomes `X.(Y+1).0` (e.g., `1.0.9` -> `1.1.0`)
3. **Build**: `uv build`
4. **Publish**: `uv publish`
5. **Commit** with message format:
   ```
   Update to {version}. Changes: {description of changes}
   ```

## Project Structure

```
src/orun/
├── __init__.py    # Package init (empty)
├── main.py        # CLI logic - entry point, argument parsing, Ollama integration
└── db.py          # Database module (Peewee ORM) for conversation history
```

Key components in `main.py`:
- **SCREENSHOT_DIRS**: Default paths for screenshot discovery
- **Subcommands**: models, refresh, shortcut, set-active, history, c, last

Database stored at `~/.orun/history.db` (SQLite).

## Key Dependencies

- **ollama**: Python client for Ollama API (local LLM server)
- **peewee**: ORM for SQLite conversation history
- **hatchling**: Build backend for package distribution

## CLI Commands

```bash
# Query
orun "prompt"              # Basic query with active model
orun "prompt" -m coder     # Use model alias (and set as active)
orun "prompt" -i           # Attach most recent screenshot
orun "prompt" -i 3x        # Attach last 3 screenshots
orun --chat                # Interactive chat mode

# Subcommands
orun models                # List available model aliases
orun refresh               # Sync models from Ollama
orun set-active <model>    # Set active model
orun shortcut <m> <s>      # Change model shortcut
orun history               # List recent conversations
orun c <id>                # Continue conversation by ID
orun last                  # Continue last conversation
```
