clicodelog: Instructions file for Claude Code

CLAUDE.md

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

Commands

# Install from source (editable, changes take effect immediately)
uv pip install -e .

# Run the app
clicodelog
# or without installing:
uv run python -m clicodelog.cli

# Common flags
clicodelog --port 8080      # custom port (default: 6126)
clicodelog --no-sync        # skip initial sync (faster startup for dev)
clicodelog --debug          # debug logging to console as well as file

# Tests
uv run python -m pytest tests/ -q

# Build for distribution
uv build                    # produces dist/*.whl and dist/*.tar.gz

Never test against port 6126 — that is the user's running instance. Use a different port (--port 6231).

Architecture

clicodelog is a local-first web app that backs up AI agent logs to ~/.clicodelog/data/ and serves them via a FastAPI browser UI.

There are three layers, and keeping them straight is the main thing:

1. The backup (sync.py) — an additive, never-deleting copy of each source tool's log directory, made with APFS clonefile so it costs almost no disk. This is the durable source of truth. It deliberately keeps files the source tool has pruned, so it must never delete and never replace a file non-atomically.
2. The metadata index (search_index.py) — one small record per session, in ~/.clicodelog/search_index.json. Derived state, rebuildable at any time. Session and project listings are served from here, not from the files.
3. The content index (fts.py) — SQLite FTS5 over message bodies in ~/.clicodelog/fts.db. Also derived. Optional: it is only built on request, and refuses to build if it would not fit on disk.

File map

clicodelog/
├── cli.py            # argparse entry point -> server.run_server()
├── app.py            # FastAPI setup, cache policy, template routes
├── config.py         # SOURCES dict, DATA_DIR, APP_DATA_DIR, constants
├── logging_setup.py  # rotating file log at ~/.clicodelog/clicodelog.log
├── storage.py        # atomic JSON read/write, quarantine, disk checks
├── scan.py           # ONE-PASS session metadata extraction (all 3 sources)
├── sync.py           # additive clone-backup, background + initial sync
├── search_index.py   # metadata index; backs listings, projects and search
├── fts.py            # SQLite FTS5 content index, query sanitizer
├── sessions.py       # session listings (from the index)
├── projects.py       # project listings (from the index)
├── conversation.py   # conversation loading, pagination, LRU cache
├── bookmarks.py      # user-authored bookmarks (atomic, locked)
├── metadata.py       # custom project names/tags (atomic, locked)
├── utils.py          # path ids, id validation, per-source helpers
├── server.py         # port handling, startup, uvicorn
├── parsers/          # claude.py, codex.py, gemini.py
├── routes/           # projects, search, export, sync, sources, bookmarks, stats
├── static/css/*.css
├── static/js/*.js    # vanilla, no build step; vendor/ holds marked+purify+hljs
└── templates/        # index.html, view.html