timeshell

A time manipulation shell for development and testing on Linux. Launch a shell where all processes see a simulated system time.

Features

• Persistent time shell - All child processes inherit the fake time
• Live time jumping - Change the time without restarting processes
• Two modes - Running (time progresses normally) or static (time frozen)

Usage

# Start a time shell (time progresses normally from the given moment)
ts '2025-01-01 00:00:00'

# Start with frozen time (time never advances)
ts --static '2025-01-01 00:00:00'

# Inside the shell, check current fake time
ts now

# Jump to a new time
ts set '2025-06-15 12:00:00'

# Exit the time shell
exit

This installs the ts and timeshell binaries (they're identical).

How It Works

timeshell uses LD_PRELOAD to intercept time-related system calls (time(), gettimeofday(), clock_gettime()). A shared memory file allows live updates when you jump to a new time.

Only wall-clock time (CLOCK_REALTIME) is faked. Monotonic clocks are left alone so timeouts and intervals work correctly.

Limitations

Due to the LD_PRELOAD approach:

• Static binaries are not affected
• setuid/setgid binaries ignore LD_PRELOAD for security
• Kernel timestamps (file mtimes, etc.) use real time
• Sandboxed apps (Flatpak/Snap) may block LD_PRELOAD

License

MIT