<div align="center">
<img src="static/track.svg" width="128" height="128" alt="Track Logo" />
<h1>Track</h1>
</div>
A lightweight CLI tool for managing development tasks with integrated JJ workspace support.
## Features
- **Context-based Task Management**: Switch to a task and all operations apply automatically
- **Ticket Integration**: Seamlessly integrate with Jira, GitHub Issues, and GitLab Issues
- **JJ Workspace Management**: Automatically manage isolated working directories for parallel development
- **Web UI**: Modern browser-based interface with real-time updates
## Installation
```bash
# Build
cargo build --release
# Install (optional)
cargo install --path .
```
## Quick Start
```bash
# Create a new task
track new "Implement User Authentication" \
--ticket AUTH-456 \
--ticket-url https://jira.example.com/browse/AUTH-456
# Add TODOs
track todo add "Design database schema"
track todo add "Implement JWT token generation" --worktree
# Register repo and sync workspaces
track repo add .
track sync
# Add reference links
track link add https://jwt.io/introduction "JWT Documentation"
# Record work notes
track scrap add "Using bcrypt for password hashing"
# Work in the TODO workspace
cd "$(track todo workspace 2)"
jj status
jj describe -m "Implement JWT token generation"
# Mark TODO as complete
track todo done 2
# View current task status
track status
```
## Command Reference
### Task Management
| `track new <name>` | Create a new task and set it as active |
| `track new <name> --template <task_ref>` | Create task from template (copies TODOs) |
| `track list [--all]` | Display task list |
| `track switch <task_id>` | Switch tasks |
| `track switch today` | Switch to today's task (auto-creates if needed) |
| `track status [id]` | Display task information |
| `track status --json` | Output in JSON format |
| `track status --all` | Show all scraps |
| `track desc [description]` | View or set task description |
| `track ticket <ticket_id> <url>` | Link a ticket to the task |
| `track alias set <alias>` | Set an alias for the current task |
| `track alias set <alias> --force` | Overwrite existing alias on another task |
| `track alias remove` | Remove alias from the current task |
| `track archive [task_id]` | Archive a task |
### Configuration
| `track config set-calendar <calendar-id>` | Set Google Calendar ID for today task |
| `track config show` | Show current configuration |
### TODO Management
| `track todo add <text> [--worktree]` | Add a TODO (optionally create workspaces) |
| `track todo list` | Display TODO list |
| `track todo update <index> <status>` | Update TODO status |
| `track todo done <index>` | Complete a TODO (rebases and removes workspaces) |
| `track todo workspace <index> [--recreate --force --all]` | Show or recreate workspaces for a TODO |
| `track todo next <index>` | Move a TODO to the front (make it the next todo to work on) |
| `track todo delete <index>` | Delete a TODO |
| `track todo delete <index> --force` | Delete without confirmation |
### Link Management
| `track link add <url> [title]` | Add a reference URL |
| `track link list` | Display link list |
| `track link delete <index>` | Delete a link |
### Scrap (Work Notes) Management
| `track scrap add <content>` | Add a work note |
| `track scrap list` | Display note list |
### Repository Management
| `track repo add [path]` | Register a repository to the current task |
| `track repo add --base <bookmark>` | Register repository with custom base bookmark |
| `track repo list` | Display registered repositories |
| `track repo remove <id>` | Remove a repository registration |
### Sync
| `track sync` | Sync repositories and setup task bookmarks |
### Web UI
<img width="2520" height="2001" alt="de5e316bf86187756a01c867ddb199df" src="https://github.com/user-attachments/assets/49c5ce74-2eac-4448-87d7-1eadb4214743" />
| `track webui` | Start web-based user interface on port 3000 |
| `track webui --port 8080` | Start on custom port |
| `track webui --open` | Start and open browser automatically |
The Web UI provides a modern, browser-based interface with real-time updates via Server-Sent Events (SSE).
**Key Features:**
- **Today Task**: Special task type that automatically inherits incomplete TODOs from the previous day. Access with `track switch today`.
- **Calendar Integration**: Display your Google Calendar in the today task view. Configure with `track config set-calendar <calendar-id>`.
- **Todo-Scrap Linking**: Click the 📝 button on any todo to jump to related scraps. Scraps are automatically linked to the active todo when created.
- **Todo Reordering**: Use the "⬆️ Make Next" option in the todo menu to move a todo to the front of your work queue.
- **Real-time Updates**: All changes are instantly reflected across all connected browsers.
- **Focus Mode**: Toggle between overview and focus modes to concentrate on the current task.
- **Dark/Light Theme**: Automatic theme switching with calendar color adaptation.
- **Safe Markdown Rendering**: Markdown is sanitized and raw HTML is stripped; links open safely in a new tab.
### Shell Completion
`track` provides shell completion scripts for bash, zsh, fish, and powershell.
| `track completion bash` | Generate bash completion script |
| `track completion zsh` | Generate zsh completion script |
| `track completion fish` | Generate fish completion script |
| `track completion powershell` | Generate PowerShell completion script |
**Quick Install (Dynamic - Recommended):**
```bash
# Bash (dynamic)
mkdir -p ~/.local/share/bash-completion/completions
track completion bash --dynamic > ~/.local/share/bash-completion/completions/track
source ~/.local/share/bash-completion/completions/track
# Zsh (dynamic)
mkdir -p ~/.zsh/completions
track completion zsh --dynamic > ~/.zsh/completions/_track
# Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)
# Then: exec zsh
# Fish (static only)
mkdir -p ~/.config/fish/completions
track completion fish > ~/.config/fish/completions/track.fish
```
**What you get with dynamic completions:**
```bash
track switch <TAB> # Shows your actual task IDs and names
track todo done <TAB> # Shows pending TODO IDs with content
track todo update 6 <TAB> # Shows status: pending, done, cancelled
track link delete <TAB> # Shows link IDs with titles
track repo remove <TAB> # Shows repository IDs with paths
track new --template <TAB> # Shows task IDs for templates
```
For detailed installation instructions and troubleshooting, see [completions/README.md](completions/README.md).
## Additional Features
For detailed information on the following features, see [docs/USAGE_EXAMPLES.md](docs/USAGE_EXAMPLES.md):
- **Task Aliases**: Assign human-readable aliases to tasks
- **Task Templates**: Create new tasks from existing task templates
- **Ticket Reference**: Reference tasks by ticket ID
- **Bookmark Naming Convention**: Automatic bookmark naming based on ticket IDs
- **JJ Workspace Workflows**: Detailed workflows for parallel development
## Database
Data is stored at the following path:
```
$HOME/.local/share/track/track.db
```
Complies with the XDG Base Directory specification.
## Technology Stack
- **Language**: Rust (Edition 2021)
- **CLI**: clap v4.4+
- **Database**: SQLite (rusqlite with bundled feature)
- **Error handling**: anyhow, thiserror
- **Date/time**: chrono
- **Display**: prettytable-rs
- **Web UI**: Axum, MiniJinja, HTMX, SSE
## Project Structure
See [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) for details.
## Documentation
- [DESIGN.md](DESIGN.md) - Design specification
- [docs/FUNCTIONAL_SPEC.md](docs/FUNCTIONAL_SPEC.md) - Functional specification
- [docs/TODAY_TASK.md](docs/TODAY_TASK.md) - Today task feature guide
- [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) - Project structure
- [docs/USAGE_EXAMPLES.md](docs/USAGE_EXAMPLES.md) - Detailed usage examples
- [docs/LLM_INTEGRATION.md](docs/LLM_INTEGRATION.md) - LLM agent integration guide (includes `track llm-help` command)
## License
MIT License
## Development
```bash
# Development build
cargo build
# Run tests
cargo test
# Release build
cargo build --release
```