🐄 TruShell

A modern, Linux-native productivity shell that integrates seamlessly with your workflow

TruShell is not just another terminal—it's a productivity powerhouse that combines task management, time utilities, jokes for breaks, and a native shell experience. Built for developers who want to stay in flow without switching contexts.

Why TruShell?

• All-in-one workspace - Tasks, time, alarms, and shell in one place
• Beautiful prompts - Customizable trushell ❯ prompt with ASCII art
• Linux-first design - Respects Unix philosophy, works alongside bash/zsh/fish
• Persistent state - SQLite-backed todos and settings survive restarts
• Fun breaks - Cow/T-Rex jokes with sound effects when you need a laugh
• Global awareness - World clocks, timezone manager, alarms, stopwatch
• Built-in editor - Quick file editing without leaving the shell

Installation

Using pip (Recommended)

pip install trushell

From Source

git clone https://github.com/AkshajSinghal/trushell.git
cd at-office-shell
pip install -e .

Quick Start

$ trushell
Entering TruShell. Type 'exit' to quit.
trushell ❯ help
Available commands: joke, joke_trex, addtask, deletetask, updatetask, completetask, showtask, now, time, world, tz, alarm, sw, settings, exit, help

trushell ❯ addtask "Review PR" "Work"
Task added.

trushell ❯ showtasks
Todos 💻
┏━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
 # ┃ Todo         ┃ Category ┃ Done   ┃
┡━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━┩
│ 1 │ Review PR    │ Work     │ ❌     │
└───┴──────────────┴──────────┴────────┘

trushell ❯ time
  __
 / _)
/_)_
 /_)

trushell ❯ joke
 _________________________
< Your Python code works! >
 -------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

trushell ❯ ls -la  # Native OS commands work too!
total 48
drwxr-xr-x  5 user user 4096 May 29 10:30 .
...

Command Reference

Fun & Breaks

Task Management

Time & Productivity

Configuration

Shell Features

Customization

Configure your experience with the settings command:

trushell ❯ settings

Adjust:

• Clock style - Choose ASCII art format
• Time template - Customize time display format
• Joke character - Switch between cow, trex, dragon, etc.
• Sound effects - Enable/disable joke sounds

Settings are stored persistently in your user data directory.

Architecture

TruShell is built with a modular architecture:

trushell/
├── cli.py              # CLI entrypoint & command routing
├── project.py          # Interactive shell REPL loop
├── todocli.py          # Todo management commands
├── pyfunny.py          # Jokes & ASCII art
├── settings.py         # Persistent configuration
├── database.py         # SQLite storage layer
└── chronoterm/         # Time utilities
    ├── shell.py        # ChronoTerm command handler
    ├── state.py        # State management
    └── sounds/         # Sound effect files

Key Design Principles:

• SQLite-backed storage - Todos and settings persist across sessions
• Platform-safe paths - Uses OS-specific app data directories
• Native fallback - Unrecognized commands pass through to system shell
• Textual UI - Modern terminal UI framework for settings & editor

TruShell vs Traditional Shells

TruShell complements your existing shell—use it for productivity tasks while keeping bash/zsh for system administration.

️ Development

Prerequisites

• Python 3.10+
• Poetry or pip

Setup

git clone https://github.com/AkshajSinghal/trushell.git
cd at-office-shell
poetry install
# or
pip install -e .

Run Tests

pytest tests/

Build Package

python -m build
twine upload dist/*

Contributing

Contributions are welcome! Please:

1. Read CONTRIBUTING.md
2. Check existing issues
3. Fork and create a pull request

See CODE_OF_CONDUCT.md for community guidelines.

Dependencies

• Typer - Modern CLI framework
• Textual - Terminal UI toolkit
• pyjokes - Joke library
• cowsay - ASCII art
• playsound - Audio playback
• SQLite3 - Built-in database (no extra install needed)

License

Apache 2.0 - See LICENSE for details.

Acknowledgments

• Inspired by the Unix philosophy of small, composable tools
• Built with love for the Linux community
• Thanks to all contributors and early testers

🌟 Star this repo if TruShell boosts your productivity!

Made for Linux users who value productivity and fun.