tokenjam: Instructions file for Claude Code

CLAUDE.md

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

This file is deliberately small. Only what governs every file lives here. Everything else — architecture detail and path-scoped Critical Rules alike — lives in .claude/rules/*.md, each of which loads only when you touch a file its paths: frontmatter matches. The single index is at the bottom of this file — if you are looking for a rule by number, or for an area's architecture notes, go there first.

Project Overview

tj (TokenJam) is a local-first, OTel-native cost-optimization layer for AI agents (with a full observability stack underneath). No cloud backend, no signup. It captures telemetry from agent runtimes, stores it in a local DuckDB database, and runs the optimize analyzers (the live list is ANALYZER_REGISTRY / ANALYZER_ORDER in tokenjam/core/optimize/runner.py — derive it from there rather than trusting a hand-maintained enumeration) that surface cost-saving candidates from real usage — plus a CLI, local REST API, web UI, and MCP server for querying. Install via pipx install tokenjam (recommended — sidesteps PEP 668 on Homebrew Python and Debian 12+/Ubuntu 24+) or pip install tokenjam in a venv. Run via tj <subcommand>. Requires Python >=3.10.

Build & Development

pip install -e ".[dev]"                 # dev install
ruff check tokenjam/                    # line-length=100, target py310
mypy tokenjam/                          # only attr-defined + no-any-return disabled (with justification); see [tool.mypy] in pyproject.toml
# Tests — CI runs all except e2e. Layers: unit = pure logic no I/O <1s; synthetic = span
# injection via factories, zero cost; agents = mock agent scenarios, full SDK path;
# integration = CLI + API. e2e needs TJ_ANTHROPIC_API_KEY and is auto-skipped otherwise.
pytest tests/unit/ tests/synthetic/ tests/agents/ tests/integration/
pytest tests/unit/test_config.py::test_function_name -v    # one test
cd sdk-ts && npm install && npm test    # TypeScript SDK (independent package)