cc-session-tools (CCST)
Infrastructure for running Claude Code as your default way of working, not just an occasional tool.
If you open Claude Code a few times a day across a handful of projects, you don't need this. If you run a dozen named sessions a day across a dozen projects, expect to pick up exactly where you left off three weeks ago, want two sessions to leave notes for each other, and want scheduled housekeeping to just happen - CCST is the layer that makes that sustainable. It replaces "which terminal tab was that in" and "let me grep my shell history" with sessions you can name, find, resume, message, and schedule like real infrastructure.
What you get
- Named, findable sessions -
ccdstarts a session under a tag you choose,ccrresumes it later by that tag, andccssearches across all of them by name, contents, or transcript text. - A per-session scratch space - every session gets its own
working/andout/directories, so drafts and deliverables don't get lost when the conversation ends. - Cross-session messaging - one session leaves a note for "whoever next works on project X"; it's there waiting, even if that's a different session on a different day.
- A local job scheduler - recurring housekeeping and periodic routines run themselves, reconciled the next time you open Claude Code.
- A structured per-project data store (
pdata) - stop losing track of things in drifting CSVs and markdown logs. - A safety layer - a hard block on destructive commands, tiered LLM review for everything else, and an 8-digit confirmation gate for anything genuinely high-stakes.
- 24 bundled skills covering session hygiene, data-store workflows, usage analysis, document extraction, and multi-agent orchestration patterns.
- Token/cost analytics over your own Claude Code transcripts, cross-checked against an independent tool so the numbers are trustworthy.
Install
uv tool install cc-session-tools # or: pip install cc-session-tools
ccst install-everything --apply # wires hooks, skills, shell functions, and
# standard scheduled jobs into ~/.claude
ccst doctor # confirms everything's wired up correctly
Requires Python 3.11+. install-everything is idempotent - safe to re-run after every
upgrade, and it's also what happens automatically the first time you run any ccst
command from a newer version than the one currently installed.
The daily workflow: ccd, ccr, ccs
Three commands cover almost everything you do day to day.
ccd <tag> starts a new session and scaffolds cc-sessions/<date>-<tag>/ with empty
working/ and out/ subdirectories, ready to use:
ccd fix-login-bug
# -> starts Claude Code, session tagged 20260928-fix-login-bug (if today is 20260928)
ccr <fragment> resumes an existing session by fuzzy name match - you don't need the
exact tag or date, and if more than one session matches you get an interactive picker:
ccr login-bug
# -> resumes 20260928-fix-login-bug, right where you left it
ccs / ccl (the same tool - ccl is the shell-function wrapper ccst shell install
sets up) searches and lists sessions by name, by file contents, or by full transcript text,
with date filters and multiple sort orders:
ccs --global # every session, across every project
ccs "rate limit" --contents --global # full-text search across working/ and out/
ccs --order-by active --limit 5 --global # your 5 most recently active sessions anywhere
working/ and out/: draft, then finalize
The convention this repo's own sessions follow: intermediate versions accumulate in
working/; only the confirmed, final artefact gets copied into out/ (sometimes in a
different format from the draft - a markdown draft finalized as a formatted document, for
example). Nothing on disk enforces this - but it's exactly what the workflow CLAUDE.md
section below teaches Claude to do, and tooling like ccs --contents and pdata reconcile-session-output assume it once it's there.
cc-sessions/20260928-fix-login-bug/
├── working/ # draft-v1.md, draft-v2.md, scratch notes, intermediate data
└── out/ # final-report.md - the thing you actually wanted
Where agents write their files
The same pattern extends to subagents: a dispatched agent gets its own folder at
agents/<tag>--<task-slug>/ inside the session directory, with its exact prompt recorded
in prompt.md and its progress in WORKLOG.md, so a large or parallel task leaves an
audit trail instead of filling up the chat. Again, nothing forces this - it's what the
agents CLAUDE.md section teaches.
Recurring routines get a fresh tag each time
A periodic task (a weekly review, a daily sync check) isn't one long-lived session - it's a new dated session each time it recurs, sharing a task-type suffix so it's easy to find the whole series later:
ccd myproject-weekly-review # -> 20260901-myproject-weekly-review
# ... a week later ...
ccd myproject-weekly-review # -> 20260908-myproject-weekly-review
ccs myproject-weekly-review --global # lists every occurrence
Sessions talking to each other: ccmsg
Leave a message for a session that isn't open right now - most commonly, for "whoever next works on this project," delivered automatically the next time a matching session starts:
ccmsg send --to-project myproject \
--subject "heads up: shared config file renamed" \
--body "renamed config/settings.yaml -> config/app.yaml, update references"
# in a later, unrelated session opened in the same project:
ccmsg deliver # also runs automatically via a SessionStart hook
ccmsg read <id>
ccmsg claim <id> # first session to claim wins, for description-addressed messages
Messages can also be addressed to a specific session (--to-session) or to a free-text
description for whichever session picks it up first (--to-description) - project-
addressed is by far the most common pattern in practice.
The easiest way to use sessions is just to tell your session to send a message to another session (e.g. by name tag and/or location).
Scheduled housekeeping: ccsched
Recurring jobs that don't need a real cron daemon - they're reconciled and caught up the next time you open Claude Code, not run in the background while your laptop is asleep.
ccsched add --id nightly-lint --cadence 'daily@22:00' -- npm run lint
ccsched status
ccsched sweep # reconcile + run anything due + surface results; also runs at session start
Cadences support every:<duration>, daily@HH:MM, weekly:<day>@HH:MM,
monthly:<day>@HH:MM, and monthly:<weekday>#<n>@HH:MM. Jobs auto-suspend after repeated
failures rather than silently failing forever. CCST itself ships nine bundled jobs (data
verification, doctor drift checks, telemetry trimming, and similar upkeep) installed via
ccst ccsched-jobs install.
ccst: the administrative CLI
Everything else lives under one umbrella command, ccst <noun> <verb>:
| Noun | What it's for |
|---|---|
hooks |
install/uninstall Claude Code hooks, manage the security-review allowlist |
skills |
install/uninstall the bundled skills into ~/.claude/skills/ |
doctor |
full health check across every subsystem; --drift for unmuted issues only |
pdata |
per-project structured data store - see below |
gc |
find and clean up orphaned rows/directories from deleted sessions |
telemetry |
inspect and trim the hook-invocation log |
sessions / repair |
maintain sessions.db; fix corrupted or ambiguous entries |
migrate |
one-shot migrations from legacy flat-file storage to SQLite |
claude-md |
install/uninstall CCST's managed sections in your global CLAUDE.md |
install-everything |
run every install step, then a full doctor check |
Run ccst <noun> --help for the full flag reference on any of these - the sections below
cover what each subsystem is for, not every flag.
Safety: hooks that watch every command
Every Bash tool call passes through a hard deny list first (destructive deletes, force
pushes, branch deletion, sudo, and similar - no bypass, by design), then a tiered review
for everything else: a fast allowlist for routine commands, escalating to an LLM-backed
review only for anything unusual, with results cached so the common case stays fast.
Genuinely high-stakes actions (configurable per deployment, via the confirm-gate CLAUDE.md
section) require a fresh 8-digit code exchanged between Claude and you before they run.
ccst hooks install --apply # wire the hooks into settings.json
ccst hooks allowlist list # see what's pre-approved to skip LLM review
Teaching Claude the conventions above: claude-md
The working//out/ and agent-folder conventions aren't magic - they're taught. ccst claude-md install inserts small, sentinel-delimited sections into your global
~/.claude/CLAUDE.md, each independently installable:
ccst claude-md install --apply # install every section
ccst claude-md install --section workflow --apply # just the working/out convention
ccst claude-md uninstall --section agents --apply # remove one section
Current sections: messaging (how to use ccmsg proactively), workflow (the
working/→out/ convention above), agents (the agent-folder convention above), and
confirm-gate (how the 8-digit confirmation gate works, for anyone who's turned it on).
install-everything installs all of them; each is a plain, human-editable block you can
read, remove, or override in your own CLAUDE.md at any time.
pdata: stop losing track of things in drifting flat files
Projects accumulate CSVs and markdown logs that drift out of sync and can't be queried.
pdata gives each project one SQLite database instead - while deliberately leaving prose
and free-form notes as ordinary files, not everything has to move in.
ccst pdata init --write # classify and migrate a project's data files
ccst pdata add mygroup --content '{"status": "open"}' --file-path notes/item-1.md
ccst pdata query mygroup --where 'status = "open"'
ccst pdata sync-check --all-projects # cross-machine sync, safe fast-forward only
Records support optional typed extension tables (ccst pdata schema add-field) alongside
a generic content field, soft deletes, and optimistic-concurrency versioning. Multi-machine
sync uses a vector clock per project: a genuine fork between two machines' edits is
flagged for a manual choice, never silently merged.
Usage and cost analytics
claude-code-usage query --group-by model,day --format markdown
claude-code-usage report --since 2026-09-01 --output report.md
claude-code-usage reconcile # cross-checks totals against an independent tool
Groups by project, session, model, MCP server, plugin, tool, or time period; separates subagent cost (already counted in the parent session) from hook-review cost (billed separately) so totals aren't double-counted either way.
Skills
24 bundled skills, symlinked into ~/.claude/skills/ by ccst skills install, covering:
- Session hygiene - find, clean up, or permanently delete old sessions
pdataworkflows - schema design, project audits, migration, conflict resolution- Multi-agent patterns - model-tier selection, an executor/critic/assessor quality loop
- Document extraction - PowerPoint, Word, PDF, email, and other formats to clean text
- Cross-session coordination - natural-language front ends for
ccmsgandccsched
Browse src/cc_session_tools/skills/ for the full list - each ships its own SKILL.md.
How it fits together
CCST is deliberately not a server or a shared team tool - it's local infrastructure for
one person running Claude Code hard, on one or more of their own machines. Everything is
SQLite under ~/.local/share/claude/, one file per subsystem, all inspectable with
ccst telemetry query, ccst gc report, or a plain sqlite3 shell if you want to look
yourself. ccst doctor is the single command that checks all of it is healthy at once -
run it any time something feels off.
Contributing
Development uses git worktrees and uv; see .claude/CLAUDE.md in this repo for the full
workflow, versioning policy, and release process.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for cc-session-tools 3.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| cc_session_tools-3.9.1.tar.gz | 678.5 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cc_session_tools-3.9.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.3 MB
Release files / cc_session_tools-3.9.1.tar.gz
| Download URL | cc_session_tools-3.9.1.tar.gz |
|---|---|
| Size | 678.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bd9052f96eb1770540ee4c2dd52ee2b310faa82e24de10bc4774bd2a82cc6b5b
|
|
BLAKE2b-256 checksum How to use checksums |
c58010b05a5c52c03a8efb40dc235a6bcaf8d14ebad9ab63e0f22124bf833b79
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / cc_session_tools-3.9.1-py3-none-any.whl
| Download URL | cc_session_tools-3.9.1-py3-none-any.whl |
|---|---|
| Size | 578.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
15c5aab148cc06a255f2cf4607e367c1c772a3f338043057ee2235c9fa9d89e2
|
|
BLAKE2b-256 checksum How to use checksums |
60f8d026ab87cede97dfc43f06f03f1552bafe76f704db9bc63294ef4993ec91
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logSecurity for cc-session-tools 3.9.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for cc_session_tools-3.9.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
