dee-timer 0.1.0

Time tracking and pomodoro session CLI with JSON output
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# dee-timer — Agent Guide

## Install
```bash
cargo install dee-timer
```

## Setup
- No API key required.
- Local SQLite DB is created automatically.

## Quick Start
```bash
dee-timer start "Research competitors" --project growth --json
```

## Commands
```bash
dee-timer start [task] [--project <name>] [--tags tag1,tag2] [--notes <text>] [--pomodoro] [--json] [--quiet] [--verbose]
dee-timer stop [--json] [--quiet] [--verbose]
dee-timer status [--json] [--quiet] [--verbose]
dee-timer show <id> [--json] [--quiet] [--verbose]
dee-timer list [--status running|stopped|all] [--project <name>] [--limit <n>] [--json] [--quiet] [--verbose]
dee-timer report [--period today|week|month|all] [--project <name>] [--json] [--quiet] [--verbose]
dee-timer delete <id> [--json] [--quiet] [--verbose]
```

Examples:
```bash
dee-timer start "Deep work" --pomodoro --tags focus,writing --json
dee-timer status --json
dee-timer stop --json
dee-timer list --status all --json
dee-timer report --period week --project growth --json
dee-timer show 2 --json
```

## JSON Contract
- Success list:
```json
{"ok": true, "count": 2, "items": [{"project": "growth", "total_sec": 3600, "session_count": 3}]}
```
- Success item:
```json
{"ok": true, "item": {"active": true, "elapsed_sec": 520, "session": {"id": 4, "task": "Deep work", "start_time": "2026-02-26T10:00:00Z", "pomodoro": true}}}
```
- Success action:
```json
{"ok": true, "message": "Session stopped", "id": 4}
```
- Error:
```json
{"ok": false, "error": "An active session already exists", "code": "ACTIVE_SESSION_EXISTS"}
```

## Common Workflows
### Workflow: Run one pomodoro session
```bash
dee-timer start "Write spec" --pomodoro --project docs --json
dee-timer status --json
dee-timer stop --json
```

### Workflow: Weekly project time report
```bash
dee-timer report --period week --json
dee-timer report --period week --project docs --json
```

## Error Handling
- Exit code `0` = success.
- Exit code `1` = error.
- Non-JSON errors are printed to stderr as `error: <message>`.
- JSON errors are printed to stdout.

## Storage
- Data: `~/.local/share/dee-timer/timer.db`
- Config: none