stint-cli 0.1.0

# Stint

> **Terminal-native project time tracking that starts when you do.**

![Status: Alpha](https://img.shields.io/badge/status-alpha-yellow)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

Stint is an open-source, local-first time tracker built in Rust. Its killer feature: **automatic time tracking via shell hooks**. Open a terminal in a project directory and the clock starts. Switch projects — it switches too. Close the last terminal — it stops. No buttons to click, no browser tabs to manage.

## Why Stint?

Most developer time trackers require you to remember to start and stop timers. You forget, your data is wrong, and the tool becomes useless.

Stint takes a different approach: it hooks into your shell prompt so tracking happens transparently as you work. You can also start/stop manually or add time retroactively — but the default path is zero friction.

## Features

### Available Now
- **Zero-config auto-tracking** — auto-discovers `.git` repos and tracks time via shell hooks, no manual setup needed
- **Manual tracking** — `stint start`, `stint stop`, `stint status`, `stint add` for full control
- **One-command setup** — `stint init bash|zsh|fish` installs the shell hook automatically (recommended)
- **Multi-shell support** — bash, zsh, and fish via `stint shell <type>` (advanced/manual hook installation)
- **Multi-terminal handling** — merge mode keeps one timer per project across terminals
- **Idle detection** — configurable auto-pause (default 5 minutes), resumes on next prompt
- **Project management** — register projects with paths, tags, and hourly rates; archive, delete, ignore
- **Rich reporting** — grouped by project or tag, with table/CSV/JSON/Markdown export and earnings calculation
- **Quick summary** — `stint summary` for a one-line overview of today and this week
- **Entry editing** — `stint edit` and `stint delete-entry` to fix the most recent entry
- **CSV import** — `stint import <file.csv>` for one-time migration from Toggl, Clockify, or any tracker
- **TUI dashboard** — `stint dashboard` with live timer, today's entries, and weekly project totals
- **Configurable** — `~/.config/stint/config.toml` for idle threshold, default rate, default tags, and auto-discovery toggle
- **Pluggable storage** — SQLite by default (WAL mode), trait-based architecture for future adapters

### Planned
- **Invoicing** — `stint invoice <project>` to generate invoices directly from tracked time
- **VS Code & Neovim extensions** — see your current project and timer in the editor status bar
- **Local API** — HTTP API on localhost for editor plugins and custom integrations
- **Apt repository** — `sudo apt install stint` for one-command installation and upgrades
- **Optional cloud sync** — self-hostable web dashboard with team features

## Install

### From GitHub Releases (recommended)

Download the latest binary for your platform from [GitHub Releases](https://github.com/DaltonR121/stint/releases):

```sh
# Linux (x86_64) — tarball
curl -LO https://github.com/DaltonR121/stint/releases/latest/download/stint-x86_64-unknown-linux-gnu.tar.gz
tar xzf stint-x86_64-unknown-linux-gnu.tar.gz
sudo mv stint /usr/local/bin/

# Linux (x86_64) — .deb package
curl -LO https://github.com/DaltonR121/stint/releases/latest/download/stint-x86_64-unknown-linux-gnu.deb
sudo dpkg -i stint-x86_64-unknown-linux-gnu.deb

# macOS (Apple Silicon)
curl -LO https://github.com/DaltonR121/stint/releases/latest/download/stint-aarch64-apple-darwin.tar.gz
tar xzf stint-aarch64-apple-darwin.tar.gz
sudo mv stint /usr/local/bin/
```

### From Source

```sh
git clone https://github.com/DaltonR121/stint.git
cd stint
cargo build --release
sudo cp target/release/stint /usr/local/bin/
```

#### Requirements

- Rust 1.75+ (2021 edition)
- SQLite (bundled via `rusqlite`, no system dependency needed)

## Quick Start

```sh
# 1. Set up auto-tracking (one-time)
stint init bash    # or: stint init zsh / stint init fish

# 2. Restart your shell, then just work normally.
#    Navigate to any git repo — tracking starts automatically.

# Quick overview of your time
stint summary

# Detailed views
stint status
stint log --from "last monday"
stint report --group-by project
stint report --format csv > timesheet.csv

# Interactive dashboard
stint dashboard
```

### Registering Projects Manually

Auto-discovery handles most git repos, but you can register projects explicitly for custom names, tags, or hourly rates:

```sh
stint project add my-app --path ~/Projects/my-app --tags client,frontend --rate 150
```

### Manual Tracking

If you prefer explicit control (or haven't set up auto-tracking):

```sh
stint start my-app
stint stop

# Add time retroactively
stint add my-app 2h30m --date yesterday --notes "Forgot to track"
```

### Importing Existing Data

Migrate from another time tracker with a CSV export:

```sh
stint import timesheet.csv
```

The CSV must have `project` and `start` columns. Optional: `end`, `duration_secs`, `notes`.

## Configuration

Stint reads optional configuration from `~/.config/stint/config.toml`:

```toml
# Idle detection threshold in seconds (default: 300 = 5 minutes)
idle_threshold = 300

# Default hourly rate in cents for auto-discovered projects (e.g., 15000 = $150/hr)
# default_rate = 15000

# Enable/disable .git auto-discovery (default: true)
auto_discover = true

# Default tags applied to auto-discovered projects
# default_tags = "rust, cli"
```

Environment variable overrides for the hook (no file I/O):
- `STINT_IDLE_THRESHOLD=600` — override idle threshold (seconds)
- `STINT_NO_DISCOVER=1` — disable auto-discovery

## How It Works

Stint installs a shell hook that fires on every prompt render. The hook calls a fast-path subcommand (`stint _hook`) that:

1. Checks your current directory against registered project paths and `.git` repos
2. Compares the detected project to the last-known context for your shell session
3. Starts, stops, or switches timers as needed
4. Detects idle gaps and trims them from tracked time

The hook is engineered to execute in **under 2 milliseconds** — you won't notice it.

### Multi-Terminal Behavior

- **Merge mode** (default): One timer per project, regardless of how many terminals are open. The timer only stops when the last terminal tracking that project closes or leaves the directory.

### Data Storage

All data lives locally in `~/.local/share/stint/stint.db` (SQLite, XDG-compliant). No account, no cloud, no telemetry. Your data stays on your machine unless you explicitly opt into cloud sync (future feature).

## Roadmap

| Phase | Milestone | Status |
|-------|-----------|--------|
| 0 — Foundation | Project scaffolding, data model, CI | Done |
| 1 — Core CLI | Manual time tracking, reporting, export | Done |
| 2 — Auto-Tracking | Shell hooks, idle detection, multi-terminal | Done |
| 3 — TUI + v0.1.0 | Interactive dashboard, first public release | Done |
| 4 — Zero-Config | Auto-discovery, config, import, entry editing | Done |
| **4.5 — Invoicing** | Invoice generation from tracked time | **Up Next** |
| 5 — Local API + Plugins | HTTP API, VS Code/Neovim extensions, apt repo | Planned |
| 6 — Cloud + Web | Optional hosted sync, web dashboard, billing | Planned |

See [CHANGELOG.md](CHANGELOG.md) for release history.

## Who Is This For?

- **Freelance developers** tracking billable hours across client projects
- **Solo/indie developers** who want to understand where their time goes
- **Team developers** reporting time to project management systems

## Project Structure

```
stint/
  Cargo.toml                # Workspace root
  crates/
    stint-core/             # Domain logic, storage, data models, services
    stint-cli/              # CLI commands, TUI dashboard, user interaction
```

## Contributing

Stint is maintained by a single developer under a [BDFL governance model](CONTRIBUTING.md). Contributions are welcome but please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a pull request.

**TL;DR:** Open an issue first to discuss. PRs without prior discussion may not be reviewed.

## Security

Found a vulnerability? Please report it responsibly. See [SECURITY.md](SECURITY.md) for details.

## License

Stint is licensed under the [MIT License](LICENSE).

See [LICENSE](LICENSE) for the full text.

---

Built by [Ryan Dalton](https://github.com/DaltonR121) / [Mosaic Ridge LLC](https://mosaicridge.com)