chronx

A time-travel debugger for shell sessions. Shell history records what you typed — chronx also records what each command did to your files, so you can scrub back through your own workflow, inspect any command's effects, and safely revert them.

A lightweight background daemon snapshots working-directory state on every command executed in an instrumented shell. Snapshots are content-addressed diffs (git-style, deduplicated by blake3 hash) — never full copies.

$ tar xf release.tar --strip-components=1        # oops, extracted over my tree
$ chronx diff last                               # what did that just overwrite?
$ chronx blame src/config.py                     # which command clobbered this?
$ chronx undo                                    # put everything back

Install

pipx install chronx

(or pipx install . from a checkout / pip install chronx into any env).

Setup (once)

1. Create the store and print setup instructions:

   chronx init
   

2. Add the hook to your shell rc file and restart the shell:

   # ~/.bashrc
   eval "$(chronx hook bash)"
   
   # ~/.zshrc
   eval "$(chronx hook zsh)"
   
   # ~/.config/fish/config.fish
   chronx hook fish | source
   

3. Start the recorder:

   chronx daemon start
   

From then on, every command you run in an instrumented shell is recorded together with the exact file changes it caused. The hook is fire-and-forget: if the daemon isn't running it does nothing, and it never slows your prompt.

Commands

Marks & full rollback

chronx mark before-upgrade         # checkpoint this moment
./upgrade.sh && make migrate       # ... things go sideways ...
chronx rollback before-upgrade     # entire tree back to the checkpoint

Rollback reconstructs the tree state at that moment from history (files changed since are restored, files created since are deleted, files deleted since come back) and applies it as one recorded event — so chronx undo reverts the rollback itself. --path src/ limits the blast radius, --dry-run shows the plan.

Finding the culprit

chronx search 'pip install'        # grep your command history + effects
chronx search -S 'timeout *= *30'  # pickaxe: which command changed this line?

When you know what broke but not which command did it, let chronx find it automatically — binary search over history, running your test at each step:

chronx daemon stop                 # bisect drives the tree itself
chronx bisect --good shipped -- pytest -x tests/test_api.py
#   GOOD  #41  ./refactor.sh
#   BAD   #47  ./optimize-queries.sh
#   ...
#   first bad event (the regression):
#   event #45  $ sed -i 's/LIMIT 100/LIMIT 10/' query.sql

chronx reconstructs the tree at each candidate moment from recorded blobs, runs the test, and restores your starting state when done. --good is a moment the test passed (a mark, event id, or time); --bad defaults to the latest event.

Alternate timelines

chronx isn't limited to one line of history. Fork the timeline, try a risky approach on a separate branch, and switch back and forth — the working tree is reconstructed each time, and both realities are kept:

chronx daemon stop                 # switching rewrites the tree
chronx fork try-async              # branch off "main", start experimenting
# ... hack, run commands, they record on try-async ...
chronx switch main                 # tree snaps back to main's state
chronx branches                    # see both timelines

chronx fork <name> --at 1h forks from a past moment, so you can explore what might have happened if you'd taken a different path an hour ago.

When an experiment works out, bring it back with a three-way merge:

chronx switch main
chronx merge try-async             # auto-merges non-conflicting changes

chronx finds the common-ancestor state, takes whichever side changed each file, content-merges non-overlapping edits within a file, and reports real conflicts (which you can force in with --allow-conflicts to get the usual <<<<<<</>>>>>>> markers). The merge is one reversible event.

Single-file time travel

chronx blame src/config.py tells you event #42 clobbered the file; chronx restore src/config.py -e 42 --before puts back the content from just before that command ran. chronx cat is the read-only version — pipe an old state anywhere without touching the working tree. Both accept --at '14:32' style moments too.

chronx undo safety

Undo shows the full plan and asks for confirmation. Before touching anything it snapshots the current content of every affected file and records the revert as an event of its own — so undo is itself undoable (the command prints the event id that re-applies the change). Files that changed again after the target event are flagged as conflicts and skipped unless you pass --force. Use --event <id> to revert a specific event rather than the last one.

How it works

 shell hook ──PRE/POST──▶ named pipe ──▶ chronx daemon
                                            │
                          watchdog marks dirty paths per watched root
                                            │
                          on POST: hash dirty files (blake3), compare
                          with the manifest, store changed blobs
                                            │
              ~/.chronx/objects/  (content-addressed, zlib, dedup'd)
              ~/.chronx/chronx.db (sqlite: command ↔ file deltas ↔ time)

• The hook sends PRE (command string + cwd) before each command and POST (exit code) after it, over ~/.chronx/daemon.fifo.
• The daemon recursively watches each working directory it sees ("root"), doing a one-time baseline scan on first contact.
• Filesystem events between PRE and POST define the set of candidate paths; each is re-hashed and compared against the manifest, so only real content changes become deltas — attributed to exactly that command.
• Changes made between commands (editor saves, cron, other tools) are recorded too, as (external change) events, so they are never mis-blamed on your next command.
• Blobs are stored once per unique content (objects/<blake3[:2]>/<rest>), zlib-compressed. Unchanged files cost nothing, ever.

Pull a session from another machine

chronx history is networked. On the machine that recorded it:

chronx serve --host 0.0.0.0        # expose read-only history

On yours:

chronx daemon stop
chronx pull http://their-host:7373 --as ./debug-repro
chronx log        # their commands
chronx graph      # their timelines
chronx rollback shipped   # reconstruct their tree at any point

Re-pull anytime — only new events are added (idempotent, incremental). The server side is strictly read-only; the pull imports into your local store.

Turn a session into git history

Debugged for hours with no commits? Replay the whole thing into a real git repository — one commit per command:

chronx to-git /tmp/session.git
git -C /tmp/session.git log --stat     # every command, as a commit
git -C /tmp/session.git blame config.py

chronx synthesizes a git fast-import stream from its recorded deltas (a "chronx baseline" commit for the starting tree, then one commit per command with the command as the message). The result is ordinary git — browse it, bisect it, or git push it to GitHub. Your chronx store is only read.

Storage layout

~/.chronx/
├── chronx.db      # events, deltas, manifests (sqlite, WAL)
├── objects/       # content-addressed blob store
├── config.toml    # tunables (size cap, ignores, settle delay)
├── daemon.fifo    # shell-hook -> daemon signal pipe
├── daemon.pid
└── daemon.log

Configuration

~/.chronx/config.toml (created by chronx init, read at daemon start):

.git, node_modules, __pycache__, virtualenvs, build dirs, editor swap files, etc. are ignored by default. Set CHRONX_HOME to relocate the store.

Per-project rules go in <root>/.chronxignore (read when the daemon starts tracking that directory): one pattern per line, # comments; lines ending in / prune directories by name anywhere in the tree, anything else is a glob matched against file basenames.

Limitations

• Tracks regular files only: symlinks, sockets, and empty directories are not recorded; files over the size cap are ignored (and stop being tracked if they grow past it).
• The very first hooked command in a brand-new directory may have its changes folded into the baseline snapshot (the watch is only set up when chronx first sees the directory). chronx exec doesn't have this race — it waits for the watch before running.
• A file created and deleted within a single command is not captured: the recorder reads content at settle time (after the command), when the transient file no longer exists.

Extending chronx (plugins)

Feature commands live as self-contained modules under chronx/plugins/, each exposing register(main) and using the stable chronx.pluginlib helper surface. They are auto-discovered from the filesystem and loaded defensively (a broken plugin is skipped, never fatal), so dropping a new .py in that directory adds a command with no reinstall. Most of the commands above (checkout, grep, annotate, find, audit, du, activity, summary, format-patch, cherry-pick) are built this way.

• Two commands running simultaneously in the same directory race for attribution; the first to finish claims the change.
• chronx is a workflow debugger, not a backup system — the object store lives on the same disk as your files.

Uninstall

chronx daemon stop
pipx uninstall chronx
rm -rf ~/.chronx        # removes all recorded history

...and remove the eval "$(chronx hook ...)" line from your rc file.