| 1 | # agent-time-ledger |
| 2 | |
| 3 | [](https://github.com/ZionBoggan/agent-time-ledger/actions/workflows/test.yml) |
| 4 | |
| 5 |  |
| 6 | |
| 7 | `agent-time-ledger` is a small local-first tool that helps LLM agents stop guessing how much time has passed. |
| 8 | |
| 9 | Basic current-time tools already exist. The useful gap is elapsed time: an agent may say "10 minutes passed" because the conversation looks short, even when 2 hours actually passed while commands, CI jobs, renders, or external services were running. `atl` measures from the runtime clock and stores local marks, sessions, stale checks, and reports. |
| 10 | |
| 11 | The binary name is `atl`. |
| 12 | |
| 13 | ## Scope |
| 14 | |
| 15 | - One local CLI binary. |
| 16 | - No cloud service. |
| 17 | - No telemetry. |
| 18 | - No prompt capture. |
| 19 | - No SaaS dashboard. |
| 20 | - No token or cost tracking. |
| 21 | - No natural-language date parsing. |
| 22 | - No general observability platform. |
| 23 | |
| 24 | State is stored under `~/.agent-time-ledger` by default: |
| 25 | |
| 26 | - `state.json` |
| 27 | - `events.jsonl` |
| 28 | - `config.toml` |
| 29 | |
| 30 | For tests or isolated runs, set `ATL_HOME=/path/to/dir`. |
| 31 | |
| 32 | ## Install |
| 33 | |
| 34 | ```bash |
| 35 | go install github.com/zionboggan/agent-time-ledger/cmd/atl@latest |
| 36 | ``` |
| 37 | |
| 38 | From a local checkout: |
| 39 | |
| 40 | ```bash |
| 41 | go build -o atl ./cmd/atl |
| 42 | ``` |
| 43 | |
| 44 | ## CLI |
| 45 | |
| 46 | ```bash |
| 47 | atl now |
| 48 | atl now --json |
| 49 | atl now --tz America/Chicago --json |
| 50 | |
| 51 | atl session start --name build |
| 52 | atl session status |
| 53 | atl session status --json |
| 54 | atl session end |
| 55 | |
| 56 | atl mark start ci |
| 57 | atl mark check ci |
| 58 | atl mark check ci --json |
| 59 | atl mark list |
| 60 | atl mark delete ci |
| 61 | |
| 62 | atl stale --timestamp 2026-06-19T06:30:00Z --ttl 30m |
| 63 | atl stale --timestamp 2026-06-19T06:30:00Z --ttl 30m --json |
| 64 | atl stale --mark ci --ttl 2h |
| 65 | |
| 66 | atl report today |
| 67 | atl report --json |
| 68 | |
| 69 | atl serve-mcp |
| 70 | ``` |
| 71 | |
| 72 | `atl now` returns both a timezone-aware timestamp and a UTC timestamp. By default it uses the host timezone, or `ATL_TIMEZONE` if set. Pass `--tz <iana-timezone>` for an explicit zone such as `America/Chicago`, `America/New_York`, or `UTC`. |
| 73 | |
| 74 | JSON responses include a `confidence` value. For v0.1, persisted elapsed calculations use wall-clock timestamps, so elapsed responses report `wall_clock_fallback`. Current host time reports `host_clock`. |
| 75 | |
| 76 | ## MCP Tools |
| 77 | |
| 78 | `atl serve-mcp` runs a stdio MCP server exposing local-only tools: |
| 79 | |
| 80 | - `time_now` |
| 81 | - `session_status` |
| 82 | - `mark_start` |
| 83 | - `mark_elapsed` |
| 84 | - `mark_list` |
| 85 | - `mark_delete` |
| 86 | - `stale_check` |
| 87 | - `ledger_event` |
| 88 | - `ledger_report` |
| 89 | |
| 90 | The `time_now` MCP tool accepts an optional `timezone` argument. The MCP server only reads and writes local `atl` state. It does not run shell commands, read arbitrary files, access the network, or sync to a cloud service. |
| 91 | |
| 92 | ## Verification |
| 93 | |
| 94 |  |
| 95 | |
| 96 | Tests and repeatable checks are documented in [docs/verification.md](docs/verification.md). Pull requests run `go test ./...` and `go vet ./...` in GitHub Actions. |
| 97 | |
| 98 | ## Agent Rule Block |
| 99 | |
| 100 | ```text |
| 101 | Use agent-time-ledger tools for time-sensitive claims. |
| 102 | |
| 103 | Do not estimate elapsed time from conversation text. |
| 104 | Before saying how long something took, call session_status or mark_elapsed. |
| 105 | Before answering what time it is for a person, call time_now with their IANA timezone when known. |
| 106 | Before relying on previous external observations, call stale_check. |
| 107 | When starting a long-running task, call mark_start with a descriptive name. |
| 108 | ``` |