ok

A personal, SSH-accessible TUI todo and done tracker. Run it locally or on a server; SSH in from your phone or laptop with any terminal app.

What is ok?

ok is a minimal productivity tool that lives in your terminal:

• Track what you did today (done items with optional time logging)
• Track what you need to do (todos)
• Tag items for context
• Access everything over SSH from any device
• Data stored locally in SQLite — no cloud, no account

Terminal Screenshot

Today · Todos · Done · Tags · Search

Open Todos
  ○ Write blog post  #writing
  ○ Review PR #412   #work

Done Today
  ✓ Morning standup  #work  15m
  ✓ Fix login bug    #work  45m  unplanned
  ✓ Deploy hotfix    #work  30m

2 done · 1h30m logged · 1 unplanned

? help  q quit  a add  d done  u unplanned  x archive  r refresh  / search  tab views

Quick Start (local)

# Clone and build
git clone https://github.com/stirlinghepburn/ok
cd ok
go build -o ok ./cmd/ok

# Initialise (creates ~/.config/ok/config.toml and ~/.local/share/ok/ok.db)
./ok init

# Open the TUI
./ok

# Or use CLI shortcuts
./ok done "Fixed the login bug" --time 45m --tags work
./ok todo "Write blog post" --tags writing
./ok today

CLI Usage

# Log a done item (positional args)
ok "Reviewed PRs" --time 1h --tags work

# Explicit commands
ok done "Deploy hotfix" -t 30m -f work --unplanned
ok todo "Write tests for auth module" -f work,testing
ok add "Pair programming session" -t 2h -f work

# View items
ok today          # today's summary
ok week           # this week's done items
ok list           # recent done + open todos
ok tags           # list all tags

# Server
ok serve                                    # start SSH server (uses default config)
ok serve --config /etc/ok/config.toml      # explicit config

# Utilities
ok init                   # initialise config and DB
ok backup ~/ok-backup.db  # backup database
ok sync                   # no-op (data is local)

Flags

Flag	Short	Description
--tags	-f	Comma-separated tags
--unplanned	-u	Mark item as unplanned
--time	-t	Time spent (e.g. 30m, 1h30m)
--notes		Free-form notes
--config		Path to config file

Time format

30m, 1h, 1h30m, 2h15m, 90m — hours and minutes only.

TUI Controls

Key	Action
tab	Next view
shift+tab	Previous view
j / ↓	Move cursor down
k / ↑	Move cursor up
a	Add new item (form)
d	Mark selected item as done
u	Toggle unplanned on selected
x	Archive selected item
r	Refresh
enter	View item detail
/	Search
? or h	Toggle help
esc	Cancel form / clear search
q / ctrl+c	Quit

Form controls (when adding an item)

Key	Action
tab / ↓	Next field
shift+tab / ↑	Previous field
enter	Next field / submit (last)
ctrl+t	Toggle todo/done type
ctrl+u	Toggle unplanned
esc	Cancel

Running the SSH Server

# Start interactively
ok serve --config /etc/ok/config.toml

# Or via systemd (see Systemd Install below)
sudo systemctl start ok

Connect from another machine:

ssh -p 23234 ok@<server-ip>

The server uses public-key authentication only. Add your key to /etc/ok/authorized_keys.

Tailscale Setup

Tailscale gives your devices a private network — perfect for accessing ok from anywhere without exposing it to the internet.

1. Install Tailscale on the server:

   curl -fsSL https://tailscale.com/install.sh | sh
   sudo tailscale up

2. Install Tailscale on your laptop/phone (see tailscale.com/download).

3. Find the server's Tailscale IP:

   tailscale ip -4
   # e.g. 100.x.y.z

4. SSH from your device:

   ssh -p 23234 ok@100.x.y.z

Mobile Access

Any SSH client works. Recommended apps:

• iOS: Blink Shell (best terminal font rendering), Terminus
• Android: Terminus, JuiceSSH

Configure a saved host pointing to your server's IP (or Tailscale IP) on port 23234.

Systemd Install

# Quick install (builds binary, creates user, sets up directories)
sudo bash scripts/install.sh

# Enable and start
sudo systemctl enable --now ok

# View logs
sudo journalctl -u ok -f

The service file is at systemd/ok.service. Edit /etc/ok/config.toml to change settings.

Backup and Restore

# Backup
ok backup ~/ok-backup.db
# or
cp ~/.local/share/ok/ok.db ~/ok-backup-$(date +%Y%m%d).db

# Restore
cp ~/ok-backup.db ~/.local/share/ok/ok.db

For server installs, back up /var/lib/ok/ok.db.

Configuration Reference

Default path: ~/.config/ok/config.toml

[server]
host = "0.0.0.0"          # bind address
port = 23234              # SSH port
user = "ok"               # system user (informational)
authorized_keys = "/etc/ok/authorized_keys"
host_key = "/etc/ok/ssh_host_ed25519_key"

[database]
path = "~/.local/share/ok/ok.db"

[ui]
timezone = "local"        # "local" or IANA zone e.g. "America/New_York"
default_view = "today"    # today | todos | done | tags | search

Override config path with --config:

ok --config /etc/ok/config.toml today

Development

# Install dependencies
go mod tidy

# Build
go build ./cmd/ok

# Run tests
go test ./...

# Run tests with verbose output
go test -v ./...

# Build and run
go run ./cmd/ok

Testing

# Unit tests (includes timeparse)
go test ./internal/timeparse/...

# All tests
go test ./...

The test suite covers the time parser (internal/timeparse) with cases for all supported formats and edge cases.