trushell 0.1.0

A polished productivity CLI shell with jokes, todos, and ChronoTerm features.

🐧 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)

Note: coming soon

Using uv (Faster)

Note: coming soon

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

Command	Description	Example
joke	Random joke with ASCII cow	joke
joke-trex	T-Rex joke with sound	joke-trex

Task Management

Command	Description	Example
addtask "<task>" "<category>"	Add a new todo	addtask "Fix bug" "Dev"
deletetask <position>	Delete task by number	deletetask 2
updatetask <pos> "<task>" "<cat>"	Update task text/category	updatetask 1 "New text" "Cat"
completetask <position>	Mark task as done	completetask 1
showtasks	Display all tasks	showtasks

Time & Productivity

Command	Description	Example
now	Current local time	now
time	ASCII clock display	time
world	Show favorite timezones	world
tz list	List saved timezones	tz list
tz add <IANA>	Add timezone	tz add Europe/London
tz remove <name>	Remove timezone	tz remove London
alarm list	List alarms	alarm list
alarm add "<HH:MM>" --label "X"	Set alarm	alarm add "07:30" --label "Morning"
sw start	Start stopwatch	sw start
sw pause	Pause stopwatch	sw pause
sw lap	Record lap time	sw lap
sw reset	Reset stopwatch	sw reset
sw show	Show current time	sw show

Configuration

Command	Description	Example
settings	Interactive settings UI	settings
edit <file>	Edit file in built-in editor	edit config.txt

Shell Features

Command	Description	Example
cd <dir>	Change directory (native)	cd ~/projects
Any OS command	Falls back to system shell	ls, git status, etc.
help	Show available commands	help
exit or quit	Exit TruShell	exit

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

Feature	Bash/Zsh/Fish	TruShell
Task Management	External tools needed	Built-in
Time Utilities	Manual setup	World clocks, alarms, stopwatch
Productivity Focus	General purpose	Optimized for workflow
Fun Breaks	None	Jokes with ASCII art
Learning Curve	Moderate-High	Low (familiar commands)
Extensibility	Plugins/scripts	Python-based

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.