https://github.com/nexneo/samay
Command line Time tracking and reporting. Built for software developers using Go.
https://github.com/nexneo/samay
command-line-tool dropbox golang protobuf protocol-buffers time-tracker
Last synced: 6 months ago
JSON representation
Command line Time tracking and reporting. Built for software developers using Go.
- Host: GitHub
- URL: https://github.com/nexneo/samay
- Owner: nexneo
- License: bsd-3-clause
- Created: 2013-04-08T18:47:37.000Z (about 13 years ago)
- Default Branch: master
- Last Pushed: 2025-10-19T09:48:54.000Z (9 months ago)
- Last Synced: 2025-10-30T19:56:45.955Z (8 months ago)
- Topics: command-line-tool, dropbox, golang, protobuf, protocol-buffers, time-tracker
- Language: Go
- Homepage:
- Size: 308 KB
- Stars: 37
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Samay
Terminal-first time tracking and reporting.
Samay is a Go application that lets you track work entirely from the terminal. It stores data in a local SQLite database, offers a Bubble Tea interface for daily use, and keeps the old command-line workflows around as future enhancements.
## Why?
- Frustration with existing time trackers, slow, complex.
- The terminal is always open.
- A playground for learning Go, [sqlc](https://sqlc.dev/), and Bubble Tea.
## Highlights
- TUI for starting and stopping timers, adding manual entries, and reviewing history.
- Data stored in a single SQLite database (defaults to `~/Documents/Samay.db`, configurable on first launch).
- Built-in monthly report and weekly overview views.
## Prerequisites
- Go 1.23+ (the repo is configured with the Go 1.24.2 toolchain).
- SQLite is bundled; Samay uses the pure Go `modernc.org/sqlite` driver, so no external system packages are required.
## Installation
Install Samay with the Go toolchain so you always pull the latest tagged release. On macOS the shortest path is to use Homebrew for Go itself, then install Samay in one step:
```sh
brew install go
go install github.com/nexneo/samay@latest
```
The binary ends up at `$(go env GOPATH)/bin/samay` (typically `~/go/bin/samay`); add that directory to your `PATH` if it is not already there.
## Version
Check the installed version with:
```sh
samay --version
```
When cutting a release, update the constant in `util/version/version.go` and create a matching Git tag (for example `v1.0.0`) so `go install github.com/nexneo/samay@latest` resolves to the correct binary.
## Running Samay
Launch the interface with:
```sh
./samay
```
On the first launch Samay asks where to create the SQLite database (press Enter to accept the default `~/Documents/Samay.db`). Subsequent runs reuse the saved location.
Use `./samay -database /path/to/custom.db` to point at a different database for a single run—handy for testing or migrating data. When you quit, Samay prints the path to the database that backed the session so you always know where entries were written.
The TUI opens to a project list backed by that database. Use the arrow keys (or `j`/`k`) to highlight a project and from there:
- `s` starts a timer. The project is persisted as soon as you start tracking against it.
- `p` stops the active timer and prompts for a summary message.
- `e` records a manual entry—enter a duration such as `45m` or `1h30m`, then the description.
- `l` shows the project log with scrollable history (`↑/↓/PgUp/PgDn`), and `a` toggles between recent entries and the full timeline.
- `v` lists entries so you can review details, move them to another project, or delete them.
- `r` renames the project; `d` deletes it.
At the project list level, press `r` to open the monthly report for the highlighted month and `o` for the weekly overview dashboard. `Esc` navigates back; `q` quits from anywhere.
## Data Storage
Samay persists everything in a single SQLite database. The default location is `~/Documents/Samay.db`, but you can point it anywhere on disk. The schema tracks:
- `projects`: project metadata plus timestamps and a hidden flag.
- `entries`: individual time entries with nanosecond precision duration, start/stop timestamps, billable flag, and optional creator.
- `entry_tags`: many-to-many join table for hashtag extraction.
- `timers`: one active timer per project.
The schema lives in `data/sql/schema.sql` and the sqlc query definitions are in `data/sql/queries.sql`.
## Development & Testing
Run the full test suite with:
```sh
go test ./...
```
If you change `data/sql/schema.sql` or `data/sql/queries.sql`, regenerate the typed data access layer with:
```sh
sqlc generate
```
Dependencies are managed through Go modules; see `go.mod` for the current set.
## Troubleshooting
- The database location is stored in `$(os.UserConfigDir())/samay/config.json`. Delete that file to re-run the first-time setup prompt.
- Because the SQLite driver is pure Go, the binary runs anywhere Go runs—no CGO or native SQLite is required.
- Samay is provided without warranty—use at your own risk.