tempo-tracker-cli 0.3.1

The Most Advanced Automatic Project Time Tracker - Lightning-fast Rust-powered CLI

Tempo

Simple, Fast, and Privacy-Focused Time Tracking for Developers

Tempo is a lightweight, terminal-based time tracking tool designed specifically for developers. It automatically detects your project context, tracks time with precision, and stores everything locally. No cloud services, no subscriptions, just a fast binary that gets out of your way.

---

📖 Table of Contents

• Why Tempo?
• Features
• Architecture
• Installation
• Quick Start
• Usage Guide
  • Session Management
  • Project Management
  • Reporting
  • Interactive UI
• Configuration
• Troubleshooting
• Contributing
• License

---

🚀 Why Tempo?

• Zero Friction: Start tracking in seconds. Tempo infers your project from your current directory.
• Local & Private: Your data lives on your machine in a standard SQLite database. You own it.
• Resource Efficient: The background daemon is written in Rust, consuming negligible CPU and memory (< 5MB).
• Developer Native: Integrates with your existing workflow. Detects Git, Node, Rust, Python, and Go projects automatically.
• Terminal First: Includes a beautiful TUI dashboard and interactive timer for those who live in the terminal.

---

✨ Features

🧠 Smart Context Detection

Tempo automatically recognizes project roots by looking for common markers:

• .git/
• package.json
• Cargo.toml
• pyproject.toml / requirements.txt
• go.mod
• pom.xml

⏱️ Intelligent Session Management

• Auto-Resume: Pick up exactly where you left off.
• Idle Detection: Automatically pauses tracking when you step away (configurable).
• Concurrent Projects: Switch contexts instantly without losing data.

📊 Powerful Reporting

Generate detailed reports to analyze your productivity or for billing purposes:

• Formats: ASCII tables, CSV, JSON.
• Filters: Date ranges, specific projects, or tags.
• Aggregation: View daily, weekly, or project-based totals.

🖥️ Interactive Dashboard

A full-featured Terminal User Interface (TUI) offering:

• Real-time status monitoring.
• Visual project switcher.
• Activity timeline and statistics.
• Keyboard-driven navigation.

---

🏗️ Architecture

Tempo follows a Client-Daemon architecture to ensure reliability and speed.

graph LR
    CLI[Tempo CLI] -- Unix Socket --> Daemon[Tempo Daemon]
    Daemon -- Reads/Writes --> DB[(SQLite DB)]
    Daemon -- Monitors --> System[System Activity]

1. CLI: A thin client that sends commands to the daemon. It exits immediately, keeping your shell responsive.
2. Daemon: A background process that manages state, handles database I/O, and monitors system idle time. It ensures time is tracked accurately even if you close your terminal.
3. Storage: All data is persisted in a local SQLite database at ~/.tempo/data.db.

---

📥 Installation

Option 1: Python Package (Recommended)

The easiest way to install Tempo is via pip or uv. The Python package automatically installs the Rust binary for your platform.

# Fast installation with uv
uv add tempo-tracker-cli

# Or using standard pip
pip install tempo-tracker-cli

Option 2: Rust / Cargo

If you have a Rust toolchain installed, you can install directly from crates.io or build from source.

# Install from crates.io
cargo install tempo-cli

# Or build from source
git clone https://github.com/own-path/vibe.git
cd vibe
cargo build --release
cargo install --path .

Package Information

Tempo is distributed as two packages:

• Python Package: tempo-tracker-cli - Provides easy installation and automatically manages the Rust binary
• Rust Package: tempo-cli - The core application binary

Both packages install the same tempo command-line tool. Choose Python for convenience or Rust for building from source.

System Requirements

• OS: macOS, Linux, or Windows (WSL recommended)
• Terminal: A terminal with TrueColor support (e.g., iTerm2, Alacritty, Ghostty) and a Nerd Font installed is recommended for the best TUI experience

---

⚡ Quick Start

1. Start the Daemon

   tempo start
   

2. Initialize a Project Navigate to your project folder and tell Tempo to track it.

   cd ~/my-cool-project
   tempo init "My Cool Project"
   

3. Start Tracking

   tempo session start
   

   Tempo will confirm that tracking has started for "My Cool Project".

4. Check Status

   tempo status
   

5. View the Dashboard

   tempo dashboard
   

---

📖 Usage Guide

Session Management

Command	Description
tempo session start	Start tracking time for the current project.
tempo session stop	Stop the current session.
tempo session pause	Pause the current session (useful for breaks).
tempo session resume	Resume a paused session.
tempo session current	Display details of the active session.
tempo session list	Show a history of recent sessions.
tempo session edit <id>	Modify a past session (e.g., fix start/end times).
tempo session delete <id>	Permanently remove a session.

Project Management

Command	Description
tempo init "<Name>"	Initialize tracking for the current directory.
tempo list	List all tracked projects.
tempo project archive <id>	Archive a project (hides it from default lists).
tempo project update-path	Update the path if you moved the project folder.

Reporting

Generate reports to visualize your time usage.

# Standard ASCII report
tempo report

# Export to CSV for Excel/Numbers
tempo report --format csv > timesheet.csv

# Filter by date
tempo report --from 2024-01-01 --to 2024-01-31

# Filter by project
tempo report --project "My Cool Project"

Interactive UI

• tempo dashboard: The main command center. View active sessions, switch projects, and see daily stats.
• tempo timer: A focused, full-screen timer view. Great for keeping on a secondary monitor.
• tempo history: An interactive browser for your session history.

---

⚙️ Configuration

Tempo is highly configurable. Settings are stored in ~/.tempo/config.toml.

You can view and modify settings via the CLI:

# View current config
tempo config show

# Set a value
tempo config set idle_timeout_minutes 10

Available Options

Key	Type	Default	Description
idle_timeout_minutes	Number	30	Minutes of inactivity before auto-pausing.
auto_pause_enabled	Boolean	true	Whether to enable auto-pause functionality.
default_context	String	"terminal"	Default tag for sessions (terminal, ide, manual).
max_session_hours	Number	48	Safety limit to auto-stop extremely long sessions.
backup_enabled	Boolean	true	Enable automatic database backups.
log_level	String	"info"	Log verbosity (error, warn, info, debug).

---

🔧 Troubleshooting

Daemon Not Starting

If tempo start fails, check if a stale PID file exists:

rm ~/.tempo/daemon.pid
tempo start

"Connection Refused"

This usually means the daemon isn't running. Start it with:

tempo start

Missing Icons in TUI

If you see boxes [] or ? instead of icons, ensure you are using a Nerd Font in your terminal emulator.

---

🤝 Contributing

We welcome contributions! Whether it's bug reports, feature requests, or code, your help is appreciated.

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

See CONTRIBUTING.md for detailed guidelines.

Release Process

Releases are fully automated via release-plz:

• Version Management: Automated PRs are created for version bumps based on conventional commits
• Dual Publishing: Merging to main triggers simultaneous publication to both crates.io and PyPI
• Synchronized Versions: Both packages maintain version parity automatically

---

📄 License

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

---

_{Built with ❤️ by Developers, for Developers.}