scip-atlas

Python CLI that reads a scip-cli SQLite index plus a git worktree and upserts a sidecar SQLite file (atlas.db). The two databases are the artifact you ship. Consumers ATTACH and join on path strings.

Install

pip install -e ".[dev]"
pip install -e ../scip-cli   # for integration tests / indexing
pre-commit install

# Fast loop while iterating (skips integration unless sync/summarize core changed):
./scripts/test.sh --changed
# scip-atlas is on PATH inside the active venv (same as scip-cli)

Usage

# From the repo root (after scip-cli reindex):
cd /path/to/repo
scip-atlas sync
scip-atlas summarize

# Defaults: git root = cwd, index = ~/.cache/scip-cli/projects/<slug>/index.db, sidecar = atlas.db beside index
# Override when needed:
scip-atlas sync --repo /path/to/repo --index /path/to/index.db --sidecar /path/to/atlas.db

# Index can include tests; atlas skips git/summary augment by default (same globs as scip-cli)
scip-atlas sync --include-tests
scip-atlas sync --exclude 'generated/**'

# SQL across index + sidecar (`files`, … are SELECT-only views; sidecar DML via atlas.*):
scip-atlas query 'SELECT COUNT(*) FROM documents d JOIN files f ON f.relative_path = d.relative_path'
scip-atlas query --write "DELETE FROM atlas.files WHERE relative_path = 'path/removed/from/index'"

summarize uses ~/.config/scip-atlas/config.toml ([models.*] endpoints, [prompts], [summarize] limits). First run copies a template and exits until models.<name>.configured = true. After upgrading scip-atlas, merge new template keys without losing your models:

scip-atlas config merge --dry-run   # preview
scip-atlas config merge             # writes backup, then merges

See docs/spec.md § Config file.

Query without git

Copy both files anywhere (sync checkpoints WAL so atlas.db alone is enough). Join on relative_path. scip-atlas query attaches the sidecar and exposes sidecar tables as unqualified names for SELECT (TEMP VIEWs). --write allows mutations; target the sidecar with atlas.files, atlas.dirs, etc. (not unqualified names). Index writes are possible but prefer scip-cli reindex.

ATTACH '/path/to/atlas.db' AS atlas;

SELECT d.relative_path, ct.name, c.commit_time, c.message
FROM documents d
JOIN atlas.files f ON f.relative_path = d.relative_path
JOIN atlas.commits c ON c.sha = f.commit_sha
JOIN atlas.committers ct ON ct.email = c.committer_email
WHERE d.relative_path = 'src/helper.ts';

SELECT relative_path, name, parent_path
FROM atlas.dirs
WHERE parent_path = 'src';

SELECT relative_path, name FROM atlas.files WHERE name LIKE 'Handler%' LIMIT 10;

Docs

Development

./scripts/test.sh          # ruff, basedpyright, pytest
./scripts/smoke.sh         # end-to-end: index fixture, sync, ATTACH, FTS
pytest -m integration -q   # needs scip-typescript (npx)

Sibling tools

1. scip-cli — SCIP → SQLite index (structure, refs, analyze).
2. scip-atlas (this) — git metadata + search overlay + LLM summaries.