Analytics, Hooks & Local File Sync

Three local capabilities round out the ecosystem once tasks, checkpoints, and the graph are in regular use: carryctx stats reports on how work is actually going, carryctx hooks wires CarryCtx into Git automatically, and carryctx sync copies project state to or from a local directory you choose. CarryCtx records lifecycle state and evidence; the external harness still launches agents, schedules processes, chooses models, and runs validation.

carryctx stats

carryctx stats

Computes project-wide and per-agent statistics directly from the local database: total tasks broken down by status (planned, ready, in progress, completed, cancelled), total graph nodes and edges, total sessions and checkpoints, total agent working time, and, per agent, session count, total seconds worked, checkpoint count, tasks completed, and blockers reported.

Default (human-readable) output:

Project Overview:
   Tasks: 12 Total (Done: 7, In Progress: 2, Ready: 2, Planned: 1)
   Graph: 84 Nodes, 211 Edges
   Sessions: 9 | Checkpoints: 23

Agent Name           | Sessions   | Time Spent   | Checkpoints  | Tasks Done      | Blockers
---------------------+------------+--------------+--------------+-----------------+----------
claude-code          | 5          | 6h 12m       | 14           | 4               | 1
codex                | 4          | 3h 40m       | 9            | 3               | 0

Flags:

Flag	Purpose
--for-agent <NAME>	Restrict all stats (overview and table) to a single agent
--markdown	Print (or, with --output, write) the report as a Markdown document instead of the plain-text table
-o, --output <PATH>	Write the report to a file instead of printing it. Format is picked from the extension: .csv → CSV, .json → the raw ProjectStats struct as JSON, anything else → Markdown

carryctx stats --markdown --output /tmp/project_stats.md

Successfully exported project stats to /tmp/project_stats.md

The generated Markdown looks like:

# CarryCtx Project Statistics

## Overview
- **Total Tasks**: 12 (Completed: 7, In Progress: 2, Ready: 2, Planned: 1)
- **Code Graph**: 84 Nodes, 211 Edges
- **Sessions & Checkpoints**: 9 Sessions, 23 Checkpoints
- **Total Agent Work Time**: 9h 52m

## Agent Performance
| Agent Name | Sessions | Time Spent | Checkpoints | Tasks Done | Blockers |
| :--- | :--- | :--- | :--- | :--- | :--- |
| claude-code | 5 | 6h 12m | 14 | 4 | 1 |
| codex | 4 | 3h 40m | 9 | 3 | 0 |

This is the same content the use-carryctx skill points agents at when it suggests exporting project stats for a PR description or documentation: drop --markdown --output into a PR body or a weekly project update instead of writing it by hand.

Tip

CSV output (carryctx stats --output stats.csv) is one row per agent with columns agent_name,sessions,total_seconds,checkpoints,tasks_completed,blockers_reported, useful for pulling into a spreadsheet across several projects.

Note

Since 0.11.2, text-mode carryctx stats on an empty local state prints a restore hint when the repository carries an in-repo publication ref (refs/heads/carryctx-snapshots, usually origin/carryctx-snapshots after a clone) — fetch it and run carryctx import --from-git <ref> --mode replace. The hint changes nothing on its own.

carryctx hooks

carryctx hooks installs Git hooks that keep CarryCtx state in sync with commits automatically, without needing to remember to run checkpoint by hand.

carryctx hooks install

Installs two hooks into the repository’s .git/hooks directory:

• post-commit: after every commit, looks up the active task from carryctx context and creates an auto-checkpoint noting the commit SHA.
• prepare-commit-msg: prepends the active task’s display ID (e.g. [CTX-0001]) to the commit message, skipping merge and squash commits.

Caution

If the repository is Jujutsu (jj) colocated (a .jj/ directory sits alongside .git/), hooks install refuses instead of writing these hooks. jj writes commits directly to the Git object store and syncs refs via jj git export, a path that never invokes Git’s hook mechanism at all — installed hooks here would silently never fire. Run carryctx checkpoint manually after jj commit/jj describe instead.

Flags:

Flag	Effect
--post-commit-only	Install only the post-commit hook, skip prepare-commit-msg
--force	Overwrite existing hooks at those paths, backing up the original as <hook>.bak first

carryctx hooks status
carryctx hooks uninstall --restore

hooks status reports, per hook, whether it’s installed and whether CarryCtx manages it (hooks that don’t contain the CarryCtx marker comment are reported as present but not managed, and are left alone). hooks uninstall removes only hooks that carry that marker; with --restore, it restores the .bak backup instead of deleting, if one exists.

carryctx sync

carryctx sync push --remote /path/to/shared/backup
carryctx sync pull --remote /path/to/shared/backup

sync push publishes a checkpointed VACUUM INTO snapshot of the project’s SQLite database into the given local --remote directory (required, no default — pick a path you control); sync pull brings it back into the local project database location. That’s the entire mechanism: a plain local file copy to and from a directory you name. There is no network protocol, no cloud service, no server, no scheduled sync, and the binary ships no network stack at all — --remote is a filesystem path, not a URL.

In v0.11.4 (since v0.8), sync pull validates the local-directory database fully before it replaces anything, and refuses a database belonging to a different project:

Error: Remote database belongs to a different CarryCtx project.

That failure is reported as SYNC_PROJECT_MISMATCH. pull also takes a pre-pull backup of the current database and stages the replacement, so an interrupted pull doesn’t leave you with a half-written state file.

Caution

sync is never invoked automatically by any other command, and it does not cross machines or networks by itself: it writes a file to a local path and reads a file from a local path. If that path happens to be a mounted network share, an external drive, or a folder some other tool synchronizes for you, then it’s that mount or that tool moving the bytes, not CarryCtx. There’s no cloud account, default remote, or background process; if you never run carryctx sync, no project data ever leaves the machine.

Because sync pull overwrites the local database wholesale, treat it as a full-state replace, not a merge: pulling from a remote after making local-only changes discards those local changes in favor of the remote copy.

Moving state across machines

sync copies a whole database file; export/import (0.11.4, since 0.8.2) go one step further and produce a portable directory (manifest.json plus per-table *.jsonl) that survives path changes between machines — importing into a fresh checkout re-anchors absolute paths instead of carrying the old ones over. Transport is still yours (scp, a shared folder, Syncthing); CarryCtx only serializes, validates, and swaps atomically. Start with carryctx export --help.