OpsTrail

Your Terminal Activity Time-Machine

OpsTrail is a local-first, privacy-focused terminal activity tracker that records everything you do in your shell and lets you search, analyze, and time-travel through your work history.

Features

• Automatic Activity Tracking - Every command, directory change, and session
• Time Travel - Jump back to where you were working hours or days ago
• Analytics - See your most-used commands, active projects, and productivity patterns
• Context Notes - Attach notes to your timeline for future reference
• Session Management - Tracks terminal sessions and idle time
• Project Awareness - Integrates with projwarp for smart project tracking
• Private & Local - All data stays on your machine
• Blazing Fast - Built with Rust for maximum performance

Installation

Quick Install

Choose your preferred installation method:

# Windows (PowerShell Script) - Downloads and installs the latest release, including PowerShell integration
irm https://raw.githubusercontent.com/ricky-ultimate/opstrail/master/quick-install.ps1 | iex

# Chocolatey (Windows) - Downloads and installs via Chocolatey, includes PowerShell integration
choco install opstrail

# Cargo (Cross-platform) - Installs the Rust binary from crates.io
cargo install opstrail

Build from Source

git clone https://github.com/ricky-ultimate/opstrail.git
cd opstrail
cargo build --release

# Copy binary to PATH
cp target/release/trail ~/.local/bin/  # Unix
# or
copy target\release\trail.exe C:\Users\YourName\.local\bin\  # Windows

Shell Integration

If you installed via Cargo or built from source, you'll need to set up shell integration manually. (Note: The PowerShell Quick Install script and Chocolatey package already handle this for Windows.)

PowerShell (Windows)

# Run the installer script
.\install.ps1

# Reload your profile
. $PROFILE

Bash/Zsh (Unix)

# Run the installer script
chmod +x install.sh
./install.sh

# Reload your shell
source ~/.bashrc  # or ~/.zshrc

---

Quick Start

Once installed, OpsTrail automatically tracks your terminal activity. Try these commands:

See What You've Been Up To

# Today's summary
trail today

# View your activity timeline
trail timeline

# This week's statistics
trail stats

Search Your History

# Find all git commands
trail search "git"

# Search today's activity
trail search "cargo" --today

# Search within a specific project
trail search "build" --project myproject

Time Travel

# Jump back to where you were 1 hour ago (auto-cd)
trail back 1h

# Jump back to 30 minutes ago
trail back 30m

# Go back to yesterday
trail back yesterday

# Alternative helper function (Unix/PowerShell)
trail-back 2h

Resume Your Work

# See your last session with interactive prompt
trail resume

# Alternative helper function (Unix/PowerShell)
trail-resume

Leave Breadcrumbs

# Add a note to your timeline
trail note "Fixed the recursive parser bug in main.rs:145"

# Search your notes later
trail search "parser"

Track Projects

# See all project activity
trail projects

# View all your sessions
trail sessions

---

Real-World Use Cases

1. "Where was I working?"

You switched contexts hours ago and forgot where you were:

# Jump back to where you were 2 hours ago
trail back 2h

# Output:
#   Jumped back 2h to: /home/user/projects/myapp

2. "What did I do today?"

End-of-day review:

trail today

# Output:
# Today's Summary
#
#   Events: 89
#   Commands: 45
#   Projects: 3
#
#   Active Projects:
#     • opstrail (58 activities)
#     • projwarp (23 activities)
#     • website (8 activities)

3. "Resume my work after a break"

Came back after lunch:

trail resume

# Output shows last active project with interactive prompt:
# Last Active Session:
#
#   Project: opstrail
#   Path: /home/user/projects/opstrail
#   Time: 2025-11-14 11:23:45
#   Last command: cargo test
#
# Jump to this location? (y/n)

4. "Find that command I ran last week"

Can't remember the exact docker command:

trail search "docker compose"

# Shows all matching commands with timestamps

5. "Track my productivity patterns"

Weekly review:

trail stats

# Output:
# Activity Statistics
#
# Most Active Projects:
#   1. opstrail (234 activities)
#   2. projwarp (128 activities)
#   3. website (89 activities)
#
# Most Used Commands:
#   1. cargo (127)
#   2. git (89)
#   3. code (45)

6. "Leave context for future me"

While debugging:

trail note "The async trait issue is in main.rs:145, related to lifetime bounds"

# Two weeks later:
trail search "async trait"
# Finds your note instantly

---

What Gets Tracked

OpsTrail automatically logs:

Event Type	Description	Example
Commands	Every command you execute	cargo build, git commit
Directory Changes	When you cd anywhere	cd /home/user/projects
Session Start	When you open a terminal	New shell session
Session End	When you close a terminal	Shell exit
Idle Time	Detects when you're away (10+ min)	Inactivity detection
Projects	Which project you're in (via projwarp)	[opstrail], [website]
Notes	Manual context you add	trail note "Bug fixed"

---

ProjWarp Integration

OpsTrail works beautifully with projwarp:

What is ProjWarp?

A fast project navigation tool that lets you jump between projects instantly:

proj add myproject          # Register current project
proj myproject              # Jump to a project
proj myproject -code        # Open in VS Code

How They Work Together

ProjWarp = Where your projects exist OpsTrail = What you're doing inside them

When both are installed:

Automatic project detection - OpsTrail reads your projwarp config Cleaner logs - Shows [myproject] instead of long paths Project-based stats - Time tracking per project Smart search - Search by project alias

Example log output:

12:45:23 [opstrail] ⚡ cargo test
12:46:15 [opstrail] ⚡ git commit -m "Add tests"
12:50:30 [website] ⚡ npm run dev

Install both:

# Windows - Chocolatey
choco install projwarp
choco install opstrail

# Cross-platform - Cargo
cargo install projwarp
cargo install opstrail

---

Commands Reference

Automatic Logging (via shell integration)

These run automatically - no action needed:

• trail log --cmd <cmd> --cwd <path> - Logs commands
• trail log --session-start - On terminal open
• trail log --session-end - On terminal close

Query Commands

Command	Description	Example
trail today	Today's activity summary	trail today
trail timeline	View activity timeline	trail timeline --today
trail stats	Activity statistics	trail stats
trail search <q>	Search your history	trail search "git" --today
trail back <time>	Time travel (auto-cd)	trail back 1h
trail resume	Show last session (interactive)	trail resume
trail note <text>	Add a note	trail note "Fixed bug"
trail sessions	List all sessions	trail sessions
trail projects	Show project activity	trail projects

Time Travel Formats

Format	Example	Description
Minutes	30m	Go back 30 minutes
Hours	1h, 2h	Go back N hours
Days	1d, 2d	Go back N days
Weeks	1w, 2w	Go back N weeks
Keywords	yesterday	Go to yesterday
	today	Start of today
	last-session	Previous session

Shell Helper Functions

Available in both PowerShell and Bash/Zsh after installation:

Function	Description
trail-back <time>	Jump back in time and cd there
trail-resume	Interactive resume with prompt

Note: trail back and trail resume now include auto-cd functionality built-in!

---

Data Storage

All data is stored locally in your home directory:

~/.opstrail/
├── timeline.jsonl    # Activity log (JSON Lines format)
├── state.json        # Current session state
└── config.json       # Configuration

Timeline Format (JSONL)

Each line is a JSON event:

{
  "timestamp": "2025-11-14T01:33:24.243Z",
  "event_type": {"type": "command", "cmd": "cargo run"},
  "cwd": "/home/user/projects/opstrail",
  "project": "opstrail",
  "session_id": "session_1731545604"
}

Why JSONL?

• Fast append-only writes
• Easy to parse line-by-line
• Human-readable
• No database required
• Easy backups (just copy the file)

---

Configuration

Edit ~/.opstrail/config.json:

{
  "idle_timeout_minutes": 10,
  "enable_projwarp_integration": true
}

Setting	Default	Description
idle_timeout_minutes	10	Minutes of inactivity to mark as idle
enable_projwarp_integration	true	Auto-detect projects from projwarp

Auto-CD Behavior

Control whether trail back and trail resume automatically change your directory:

Setting	Default	Description
auto_cd.back	true	Auto-cd for trail back
auto_cd.resume	true	Auto-cd for trail resume

Example:

{
  "auto_cd": {
    "back": true,
    "resume": false
  }
}

Disable auto-cd if you prefer explicit control:

• trail back 1h will print the path instead of changing directory
• trail resume will show manual instructions

Commands Reference

Update trail back and trail resume descriptions to mention config.

Why This Matters

Problem Solved

• Some users don't like unexpected directory changes
• Scripting scenarios need predictable behavior
• Teams may have policies against auto-cd
• Advanced users want explicit control

Solution Benefits

• Backward compatible (default = current behavior)
• Simple configuration (two boolean flags)
• Zero breaking changes
• Clear documentation
• Graceful fallbacks

Future Enhancements

Potential additions:

1. CLI flag override: trail back 1h --no-cd to temporarily disable
2. Per-command defaults: Different defaults for back vs resume
3. Environment variable: OPSTRAIL_AUTO_CD=false for session-level control
4. Confirmation prompt: auto_cd.confirm: true to always ask

---

🛠️ Shell Integration Details

PowerShell (Windows)

The PowerShell integration (install.ps1):

Logs every command using PowerShell history Tracks session start/end automatically Provides helper functions (trail-back, trail-resume) Auto-cd support for trail back and trail resume Handles UTF-8 encoding properly

Bash/Zsh (Unix)

The Unix shell integration (install.sh):

Logs commands using preexec hooks Tracks session start/end automatically Provides helper functions (trail-back, trail-resume) Auto-cd support for trail back and trail resume Compatible with both Bash and Zsh

---

Example Daily Workflow

# Morning - Start fresh terminal
# OpsTrail automatically logs session start

# Check what you did yesterday
trail timeline --date 2025-11-13

# Resume yesterday's work
trail resume
# Shows info and prompts: Jump to this location? (y/n)
# → Type 'y' to jump to /home/user/projects/opstrail

# Work on the project
cargo build
cargo test
git commit -m "Add feature"

# Leave a note for context
trail note "Implemented time-travel navigation, needs testing on edge cases"

# Switch to different project
proj website
npm run dev

# Lunch break (OpsTrail detects 10+ min idle)

# Back to work - check progress
trail today
# Shows: 2 projects, 23 commands, 2h 15m tracked

# Find that git command from last week
trail search "git rebase" --project opstrail

# Jump back to where you were this morning
trail back 3h

# End of day review
trail stats

Contributing

Contributions are welcome! Here's how you can help:

1. Report bugs - Open an issue on GitHub
2. Suggest features - Share your ideas
3. Submit PRs - Improve the code
4. Write documentation - Help others use OpsTrail
5. Share feedback - Tell us what you think

Development Setup

# Clone the repo
git clone https://github.com/ricky-ultimate/opstrail.git
cd opstrail

# Build
cargo build

# Run tests
cargo test

# Run locally
cargo run -- today

---

Inspiration

Inspired by:

• zoxide / autojump - Smart directory jumping
• Shell history - But much more powerful
• VSCode timeline - But for your terminal
• RescueTime - But local and privacy-focused
• Git commit history - But for all your work

---

Why OpsTrail?

Ever wondered:

• "Where was I working on that feature?"
• "What command did I run to fix that issue?"
• "How much time did I actually spend on this project?"
• "What was I doing before I got distracted?"

OpsTrail answers all of these - automatically, privately, and locally.

It's like having a DVR for your terminal. Rewind, replay, and review your development workflow.

---

Related Projects

• ProjWarp - Project navigation tool (pairs perfectly with OpsTrail)

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ by リッキー

Track your journey, boost your productivity 🚀