📂 TOsk — A Terminal Task Planner

TOsk is a terminal-based task planner built with curses in Python. It features a splash screen, grid-based task UI, CSV import/export, due dates, history logs, and more — all inside a beautiful fullscreen TUI.

📦 For users who just want it to work without setup, a prebuilt binary is available under Prebuilt Binary (Linux Only).

---

✅ Requirements

For End Users

• No special requirements!
• 📂 Just download TOsk for Linux and make it executable (chmod +x tosk-linux-x86_64 , then run it.
• 📦 Rather install it as tosk in your terminal?

For Development

• Python 3.8+
• python3-venv
• PyInstaller
• Static Linux build of viu

---

✨ Features

• 📋 Grid-based Task Manager: Scrollable, sortable, real-time editable grid.
• ✅ Task Completion Tracking: Toggle with space bar.
• ⌛ Estimated Duration Support: Helps plan your day. Enter an estimated duration for each task to help plan your day and manage your workload.
• 🎯 Priority System: Focus on what matters most. Assign priority levels to tasks to focus on what matters most. Browse to the top of app page, select PRI, enter to sort.
• 📅 Due Date Picker: Asign due dates. Set a due date on a selected task, select due dates using full-screen calendar widgets.
• 🧮 Built-in Status Bar: Always visible summary showing task count and completion status.
• 📂 CSV Import/Export: Backup or transfer tasks.
• 📝 Plaintext Task Import: Use this format or even by creating a task within the app itself:

  Task sentence::duration::priority::YYYY-MM-DD
  

  Example:

  Fix bug::30::1::2025-04-15
  

  If only a task name is given, defaults apply.
• 🔄 Sortable Headers: Sort by clicking headers.
• 📷 Splash Screen Support: Terminal image with viu.
• 🎨 Colorized UI: Themed, bold visuals.
• 🔐 Encrypted Configuration: Securely store sensitive configuration data (e.g., GitHub Token, Encryption Passphrase, GitHub Owner, and GitHub Repository) in an encrypted file (config.json), ensuring your credentials remain protected.
• 💾 GitHub Backup & Import: See guide
• 🔒 Secure Communication: All interactions with GitHub are transmitted over HTTPS for data security.
• 🔄 Offline Capability: Core functionality works without an internet connection.
• 🐧 Linux Native: Optimized for Linux terminal environments (e.g., GNOME Terminal, xterm, etc.).

---

📚 Additional Documentation

• 🔄 Backup How‑To Guide
• 🔒 Security and token access explained

---

🔑 How to Set Up a GitHub Personal Access Token

1. Visit: https://github.com/settings/tokens
2. Click "Generate new token" → "Fine-grained token"
3. Name it (e.g. TOsk Backup Token)
4. Choose your repo scope (e.g. tosk-backups)
5. Permissions:
   • Contents → Read and write
6. Generate token and copy it.
7. Paste into TOsk when prompted.

💡 Stored in config.json, encrypted with your master password.

---

📘 Changelog

Check out what’s new: CHANGELOG ➜

---

🚀 Build Instructions (Linux Only)

Expand for full build steps

# Install dependencies
sudo apt-get update
sudo apt-get install python3-venv curl tar

# Set up project directory
mkdir -p ~/ncurses_TOsk_app/bin
cd ~/ncurses_TOsk_app

# Download and extract viu
curl -L https://github.com/atanunq/viu/releases/latest/download/viu-x86_64-unknown-linux-musl.tar.gz -o /tmp/viu.tar.gz
mkdir -p /tmp/viu-install
tar -xzf /tmp/viu.tar.gz -C /tmp/viu-install
cp /tmp/viu-install/bin/viu bin/
chmod +x bin/viu

# Clone repo or add main.py, tosk.jpg

# Setup virtual env
python3 -m venv ~/pyenv
source ~/pyenv/bin/activate
pip install pyinstaller

# Patch main.py
# def resource_path(relative_path):
#     import sys, os
#     if hasattr(sys, '_MEIPASS'):
#         return os.path.join(sys._MEIPASS, relative_path)
#     return os.path.join(os.path.abspath("."), relative_path)
# Replace all static paths to viu and tosk.jpg with resource_path(...)

# Build
pyinstaller --onefile \
  --add-data "bin/viu:bin" \
  --add-data "tosk.jpg:." \
  main.py

# Rename and run
mv dist/main dist/tosk
chmod +x dist/tosk
./dist/tosk

# Deactivate
deactivate

---

🧰 What the Build Process Does

• Creates a venv
• Downloads and embeds viu
• Uses PyInstaller to bundle:
  • All code
  • Splash image
  • viu binary
• Outputs single-file executable tosk

---

🗼 Screenshots

📸

---

📥 Installation

1. Download from Releases
2. Make it executable:

   chmod +x tosk-linux-x86_64

3. Run it:

   ./tosk-linux-x86_64

Or install it permanently:

mkdir -p ~/.local/bin && cp tosk-linux-x86_64 ~/.local/bin/tosk && chmod +x ~/.local/bin/tosk

🗑️ Uninstallation

To remove TOsk if it is installed:

rm ~/.local/bin/tosk

Optionally, remove the downloaded binary:

rm ~/tosk-linux-x86_64

---

⚠️ Notes

• Requires Linux (64-bit)
• Includes statically built viu for splash
• Terminal must support image previews (Kitty, iTerm2, etc.)

---

🙈 How to Disable the Splash Screen

🛠 Option 1: Quick & Safe (If you build it, not using the binary)

1. Open tosk.py
2. Scroll to the bottom
3. Find:

   show_splash()
   

4. Comment it out:

   # show_splash()
   

---

⚙️ Option 2: Make It Configurable

1. Replace:

   show_splash()
   

   With:

   config = prompt_for_config()
   if not config.get("DISABLE_SPLASH", False):
       show_splash()

2. Edit your config.json:

   {
     "DISABLE_SPLASH": true
   }

3. Binary users should build from source to enable this option.

---

❗ Note on Splash Rendering

• Requires statically compiled viu
• Not distributed in this repo
• Download and include via build guide above

---

📜 Acknowledgments

• Splash support uses viu by Tanuj Sinha
• MIT Licensed — see LICENSE.viu