autonag

A recurring-task tracker with a persistent alarm. Timers count down; when one expires, the alarm rings on any device you have open to the alarm page. It doesn't stop until you mark the task done, snooze it, or silence it. Recurring tasks reschedule automatically.

autonag.com — open app

Install

npm install -g autonag

First-time setup

Point the CLI at your server and register this device:

autonag --server https://your-server.example register mydevice

Your token is saved to ~/.config/autonag/client.json5. The device starts in PENDING state — an admin must approve it on the server before you can use it. Check your status:

autonag status

Getting an instance

Timers live in an instance. Create one:

autonag instances request home

Once approved, set it as your default:

autonag instances list
autonag instances select <id>

To join an instance someone else owns, ask them to run autonag instances invite, then join with the code they share:

autonag instances join <code>

Adding timers

One-shot reminder due in 2 days:

autonag timers add "Doctor follow-up" 2d

Recurring task every 7 days at 9 AM:

autonag timers add "Weekly review" 7d --days 7 --anchor 09:00

The first argument is the initial expiry. --days makes it recurring; --anchor sets the time of day; --tz overrides the timezone.

Checking timers

autonag timers list

ID          Name                      Remaining         Recur
------------------------------------------------------------
a1b2c3d4…   Doctor follow-up          in 1d 23h
e5f6a7b8…   Weekly review             in 6d 23h         ↻

The ↻ symbol marks recurring timers.

Completing a timer

autonag timers complete e5f6 pass

For a recurring timer this schedules the next occurrence:

Timer "Weekly review" recurred — next: 4/24/2026, 9:00:00 AM

For a one-shot timer it removes it. Reason can be pass, fail, or any custom string.

Snoozing and silencing

Push a timer's deadline out:

autonag timers snooze e5f6 3d

Silence the alarm temporarily (default 30 min):

autonag shush
autonag shush 2h
autonag unshush

Notes and history

Attach a description to a timer:

autonag timers describe e5f6 "Prep the agenda first"

Add timestamped comments:

autonag comments add e5f6 "Done, flagged for follow-up"

See completion history for a recurring timer:

autonag timers history e5f6

Event log

Every action is recorded and replayable:

autonag events list
autonag events skip <event-id>   # undo: recompute state as if this event never happened

SDK usage

The package also exports a typed API client for use in scripts and agents:

import { createApiClient } from "autonag";

const api = createApiClient("https://your-server.example", token);

const state = await api.getState(instanceId, token);
const { timer } = await api.addTimer(instanceId, token, "Take medication", Date.now() + 8 * 3600_000);
await api.completeTimer(instanceId, token, timer.id, "done");

All types (Timer, InstanceState, StoredEvent, etc.) are exported from the package root.

Full reference

autonag --help
autonag tutorial