txr - Transactional Command Runner

txr is a standalone CLI tool that provides transactional execution of shell commands. It acts as a safety net, allowing you to run commands (like npm install, generators, or scripts) and undo them completely if they don't produce the desired outcome.

It works independently of any user Git repository, maintaining its own internal state store to track and rollback filesystem changes with strict safety guarantees.

Philosophy

• One executed command = one transaction.
• Correctness over convenience: txr will strictly refuse to undo if a file was externally modified. It never guesses.
• Linear History: There are no branches or merges. It works like an editor's undo stack.
• Invisible Storage: The internal Git repo is hidden and purely used as an efficient storage engine.

Installation

txr is available as a global npm package.

npm install -g @amoghvj/txr

Once installed, the txr command will be available anywhere on your system.

Usage Instructions

1. Initialize a Workspace

Before running transactional commands, initialize txr in your project root. This creates a .txr/ hidden directory to store history and internal state.

txr init

By default, txr runs in workspace scope. This means it only tracks files inside your project directory. If you run a command that modifies files outside the project (like npm install -g or writing to an absolute path), txr will detect this, flag it as a scope violation, and ask for confirmation before running (and it won't track those external changes).

If you want txr to track everything a command does, no matter where it writes on your system, initialize with global scope:

txr init --global

Using txr everywhere on your system: If you want to use txr run in any folder on your computer without typing init for every new project, you can initialize a single global state store in your user's home directory:

cd ~
txr init --global

With this setup, txr will place the .txr folder in your home directory (~/.txr). Whenever you use txr run anywhere on your machine, it will traverse up the folder tree, find ~/.txr, and record the transaction there. Because you used --global, it will gladly track changes across your entire filesystem.

2. Run Commands

Execute any command through txr. It will automatically track the filesystem changes and record a transaction.

txr run "npm install express"
txr run "npx create-react-app frontend"
txr run "node script.js"

Non-transactional Commands: txr analyzes commands before running. If you try to run a command that modifies state outside the filesystem (like databases or containers), it will warn you:

txr run "docker compose up -d"
# ⚠ WARNING: This command may modify state outside the transaction engine.
# Continue? [y/N]

You can bypass the prompt with -y: txr run -y "docker compose up -d". These commands are logged in history but don't create a transaction.

3. Undo a Transaction

If a command broke your project, simply undo the most recent transaction. This restores all created, modified, or deleted files to their exact previous state.

txr undo

Note: If any touched file was manually edited outside of txr after the transaction, txr undo will safely abort to prevent data loss.

4. Redo a Transaction

If you undid a transaction by mistake, you can redo it (as long as you haven't run any new commands since).

txr redo

5. Check Status and History

View the current active transaction and attribution tier:

txr status

View an audit log of all commands run through txr:

txr history

Advanced Options

• txr clear: Permanently reset the internal state and delete all transaction history in the active .txr folder. Useful if the system enters an unrecoverable state or you want to start fresh. Use -y to skip confirmation.
• txr run --transactional "cmd": Force a command to be tracked as transactional, even if the classifier flags it as unsafe.
• txr run --no-transaction "cmd": Force a command to run directly without tracking or generating a transaction.

Attribution Tiers

txr uses different methods to track process changes depending on your OS and privileges:

• Tier 3 (Hybrid / Scoped Diff): Default for unprivileged execution. It tracks process lifetimes and diffs declared watch paths.
• Tier 2 (Linux ptrace): Planned. Exact syscall interception without root.
• Tier 1 (ETW / eBPF): Planned. Exact low-overhead tracking requiring Admin/Root.

Configuration

You can tweak settings in .txr/metadata/config.json, such as:

• watchPaths: Array of directories to track for changes (defaults to ["."]).
• ignorePaths: Glob patterns to ignore (e.g., node_modules/.cache).