claudesync-index

csindex builds a hierarchical, AI-generated INDEX.md tree over a claudesync export of your claude.ai conversations — one summary per conversation, rolled up into per-project summaries, rolled up into a single root summary of the whole export.

It caches by content hash, so a re-run only pays to summarize conversations that are new or changed since the last pass — everything else is skipped.

Unofficial tool. claudesync-index is a community project, not affiliated with or endorsed by Anthropic. It processes exports produced by claudesync — an unofficial tool that reads your claude.ai session cookie to access the undocumented web API, which may violate Anthropic's Terms of Service and could put your account at risk. Use both tools at your own risk.

Install

uv tool install claudesync-index

# one-off, no install
uvx claudesync-index --help

pipx install claudesync-index

Quickstart

Export your conversations with claudesync, then index them:

claudesync export-all --output ~/claude-export
csindex full --root ~/claude-export --provider anthropic --wait

The anthropic provider submits work as message batches: without --wait the command submits and exits immediately, and a later re-run resumes and collects whatever's ready (handy for cron); --wait blocks until the batches finish.

Open ~/claude-export/INDEX.md when it's done.

Providers

claude-cli is the default provider. Select another with --provider, --api (alias for --provider anthropic), --subscription (alias for --provider claude-cli), or $CSINDEX_PROVIDER.

How it works

csindex full walks the export depth-first:

1. Leaves — every conversation (standalone, or nested under a project) gets its own summary.
2. Projects — each project's leaf summaries are aggregated into one project-level summary.
3. Root — every project and standalone-conversation summary rolls up into one root INDEX.md for the whole export.

Each level's INDEX.md stamps a content hash of its inputs. On the next run, anything whose inputs haven't changed is skipped — only new or edited conversations get re-summarized. Pass --force to ignore the cache and re-summarize everything.

If a provider call fails in a retryable way (malformed structured output, a parse failure), the runner retries once against that provider's configured escalation model — a stronger model for the cases the normal tier can't handle. Escalation is per-provider and configurable in reindex.toml. The root step never escalates — it already runs the strongest configured model, so retrying "up" would be a downgrade.

Commands

quick shells out to claude -p directly — it needs an authenticated claude binary on PATH and consumes your Claude Pro/Max subscription quota, not a separate API charge. It reads and writes only README.md and METADATA.json at the export root. The prompt it sends is packaged as quick.md; override it like any other template with --prompts-dir.

Semantic search (optional)

embed/search/embed-migrate need the [embed] extra (chromadb):

uv tool install 'claudesync-index[embed]'
# or: pip install 'claudesync-index[embed]'

Both embed and search need an embedding backend — there's no default, so an unconfigured run exits 78 (CONFIG). Configure one via --backend, $CSINDEX_EMBED_BACKEND, or [embedding].backend in reindex.toml (see reindex.example.toml):

--base-url / $CSINDEX_EMBED_BASE_URL / [embedding].base_url override the endpoint for openai/ollama (cloudflare derives its endpoint from the account id). --model / $CSINDEX_EMBED_MODEL / [embedding].model override the model.

Vectors persist to <export root>/.vector-db by default (--persist to override). A collection is stamped with the backend and model it was embedded with: switching backends or models means wiping .vector-db/ and re-embedding — mixing vector spaces in one collection would corrupt search silently, so csindex fails loudly (exit 65) instead.

Config

Optional reindex.toml at the export root overrides provider selection, model tiers, and pricing — see reindex.example.toml for the full annotated shape. Copy it in and edit.

The model IDs and per-token prices baked into claudesync-index are point-in-time defaults. When Anthropic changes pricing or ships new models, override them in reindex.toml — no need to wait on a new release.

Environment variables:

--prompts-dir PATH overrides individual prompt templates with your own — any template name not present in the directory falls back to the packaged default.

Docker

docker run --rm \
  -e ANTHROPIC_API_KEY \
  -v "$HOME/claude-export:/export" \
  --user "$(id -u)" \
  ghcr.io/infiniteroomlabs/claudesync-index \
  full --root /export --provider anthropic

See docs/docker.md for the provider-support matrix (claude-cli/ollama need extra wiring), UID guidance, and a cron example.

Exit codes

csindex follows the sysexits.h convention, cron-friendly (cron mails stderr on any non-zero exit):

Development

uv sync
mise run test
mise run lint
mise run build

For a live run against the anthropic provider, export your key first (or use whatever secret manager you prefer):

export ANTHROPIC_API_KEY=...
uv run csindex full --root <export> --provider anthropic

See docs/adding-a-provider.md to add a new provider.

License

MIT — see LICENSE.