task-terminal 0.2.0

Task Terminal - A local-first developer tool for generating and tracking task IDs

Task Terminal (tt)

A local-first developer tool for generating and tracking task IDs that seamlessly link to GitHub PRs.

Task Terminal (tt) is a polished terminal application that helps developers maintain a monotonically increasing, globally unique sequence of task IDs across all their projects, with automatic GitHub PR detection and linking.

✨ Features

• 🎯 Global Task IDs - Monotonically increasing IDs (tt-1, tt-2, tt-3...) that never reset
• 💾 Local SQLite Storage - All data stored locally in ~/.tt/tasks.db
• 🔗 GitHub PR Integration - Automatic detection and linking of PRs via GitHub CLI
• 🚀 Cross-Project - One global sequence across all your repositories
• 🔍 PR Management - View, link, and open PRs directly from the terminal

📦 Installation

Prerequisites

• Python 3.9 or higher
• GitHub CLI (optional, for PR features)

Install from PyPI

pip install task-terminal

Or with uv:

uv pip install task-terminal

Setup GitHub CLI (Optional)

For PR detection and linking features:

# Windows
winget install --id GitHub.cli

# macOS
brew install gh

# Authenticate
gh auth login

Quick Start

1. Install Task Terminal

   pip install task-terminal
   

2. Launch the application

   tt
   

   If tt command is not found, try:

   python -m tt.main
   

3. Navigate to your project (for PR features)

   cd ~/projects/your-repo
   tt
   

4. Create your first task

   • Navigate to "Create Task" with arrow keys
   • Press Enter to generate a task ID
   • The ID (e.g., tt-1) is copied to your clipboard

5. Use the task ID in your workflow

   git checkout -b feature/tt-1-implement-auth
   # Make your changes
   git push origin feature/tt-1-implement-auth
   

6. Import and link PRs

   • Create a PR on GitHub with tt-1 in the branch name or title
   • Open tt and navigate to "PR Inbox"
   • Press 'l' or Enter on tt-1 to import and link the PR

📖 Usage Guide

Main Menu

Navigate with arrow keys and select with Enter:

• Create Task - Generate a new task ID
• Tasks - View all tasks and their status
• PR Inbox - Detect and link PRs to tasks
• Settings - Coming soon
• Quit - Exit the application

Shortcuts: q or Escape to quit

Create Task Screen

Shortcuts:

• Enter - Generate a new task ID
• Escape - Go back to main menu

The generated task ID is automatically copied to your clipboard for immediate use.

Tasks Screen

View all your tasks with their status, creation date, and linked PRs.

Shortcuts:

• Arrow keys - Navigate tasks
• d - Delete the highlighted task
• o - Open the linked PR in your browser
• r - Refresh the task list
• Escape - Go back to main menu

PR Inbox Screen

Automatically scans for PRs in the current repository and detects task IDs in branch names and PR titles.

Features:

• Import - Task IDs found in the repo but not in your local database
• Link - PRs for existing tasks that need to be linked

Shortcuts:

• Arrow keys - Navigate items
• Enter or l - Link PR or import task ID
• i - Ignore the highlighted item (session only)
• r - Refresh and rescan the repository
• Escape - Go back to main menu

🎯 Workflow Example

# 1. Install Task Terminal
pip install task-terminal

# 2. Generate a task ID
tt
# Navigate to "Create Task", press Enter
# Result: tt-42 (copied to clipboard)

# 3. Navigate to your project and create a branch
cd ~/projects/my-api
git checkout -b feature/tt-42-add-authentication

# 4. Implement your feature
# ... make changes ...
git add .
git commit -m "Add JWT authentication for API"
git push origin feature/tt-42-add-authentication

# 5. Create a PR on GitHub (with task ID in title or branch)
gh pr create --title "tt-42: Add authentication" --body "Implements JWT auth"

# 6. Import and link the task in tt
tt
# Navigate to "PR Inbox"
# You'll see "Import | tt-42 | #123 | Add authentication"
# Press 'l' or Enter to import and link

# 7. View your tasks
# Navigate to "Tasks"
# See tt-42 status: linked, with PR #123 and title
# Press 'o' to open the PR in your browser

🔧 Development

Setup Development Environment

# Clone the repository
git clone https://github.com/sumanthaka/TerminalTask.git
cd TerminalTask

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Run from Source

tt

Code Style

# Format code
ruff format

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Textual - An amazing TUI framework
• Inspired by the need for simple, local-first developer tools
• GitHub CLI integration powered by gh

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

• Task search and filtering
• Export tasks to JSON/CSV
• Multi-PR support per task

---