intentKeeper: Instructions file for Claude Code

CLAUDE.md

Before any PR: read MERGE_CHECKLIST.md Before any release: run python3 scripts/check_version.py

Project Overview

intentKeeper is a local-first content filter that classifies social media content by its underlying intent - ragebait, fearmongering, hype, or genuine insight. It runs entirely on local hardware via Ollama. No external API calls, no telemetry, no cloud.

Core philosophy: "The content isn't the problem. The intent behind it is."

Development Commands

# Install with dev dependencies
pip install -e ".[dev]"

# Start the classification server
intentkeeper-server
# or
uvicorn server.api:app --reload --port 8420

# Run unit tests (93 tests, Ollama not required - all mocked)
pytest tests/

# Run tests with coverage
pytest tests/ --cov=server

# Run the classification eval (requires Ollama running)
python eval/run_eval.py
python eval/run_eval.py --verbose          # show every item
python eval/run_eval.py --filter ragebait  # one intent only

# Version consistency check
python3 scripts/check_version.py

# Linting and formatting
ruff check server/
ruff check --fix server/
black server/

Required Environment Variables

Configure in .env (see .env.example):

Required:

• OLLAMA_HOST - Ollama server URL (default: http://localhost:11434)
• OLLAMA_MODEL - Model name (default: llama3.1:8b - the model the 96% baseline is measured on)

Optional:

• OLLAMA_TEMPERATURE - LLM temperature (default: 0.1)
• OLLAMA_SEED - Pin sampling seed for reproducible output (unset = non-deterministic)
• OLLAMA_VISION_MODEL - Vision model for image/thumbnail analysis (e.g. moondream, llava:7b); when unset, image analysis is skipped and only text is classified
• INTENTKEEPER_HOST - Server bind address (default: 127.0.0.1)
• INTENTKEEPER_PORT - Server port (default: 8420)
• MANIPULATION_THRESHOLD - Score threshold for treatments (default: 0.6)
• CACHE_TTL - Cache time-to-live in seconds (default: 300)
• CACHE_MAX_SIZE - Max LRU cache entries (default: 1000)
• DEBUG - Enable debug logging (default: false)