Documentation

Getting started, and how everything works

Nagbox recreates Google Inbox's triage model for tasks: one stream that nags by presence, organized with labels and a Lens, with timing that fires and push that reaches your phone. This page is the reference for every part of it, plus the MCP server that lets an agent run your reminders for you.

Getting started

Nagbox runs at app.nagbox.io. From nothing to push on your phone and an agent wired in is about five minutes.

  1. Sign up

    Sign up at app.nagbox.io/signup with an email and password. There is no separate URL or subdomain to remember: everyone works in the same app, at the same address.

  2. Add it to your home screen

    Open app.nagbox.io on your phone and install it as a PWA (on iOS, Share, then Add to Home Screen). It then opens full screen like an app and can receive push with the browser closed. On iOS this step is required before push will work at all.

  3. Turn on push

    In Settings, Notifications, toggle push on for the device. Nagbox runs its own VAPID Web Push, no Firebase and no vendor cloud. Use the "Send test push" button to confirm it lands, then trust it to nag you.

  4. Capture your first nag

    Everything starts as one thing, a nag, added from the capture bar. Give it a title, and optionally a Remind time (when it should nag you), a Due date (the deadline), labels, an icon, and a priority. It lands at the top of the stream and stays there until you act on it.

  5. Organize with labels and a Lens

    Tag items with labels, then build a Lens: a saved view made of an include set, an exclude set, and a name. Pin the Lens you live in to the bar across the top. Your Inbox is itself a Lens, so tuning what it shows is the same move.

  6. Connect an agent

    Mint an access token in Settings, Access tokens, then point any MCP client at the Nagbox server. Now Claude or any agent can capture obligations and triage the stream for you. Full detail is in Agents, API, and MCP below.

    npx -y @nagbox/mcp

The model

Nagbox has one core idea, taken from Google Inbox: a single stream you triage, not a pile of lists you maintain.

One stream Live

Everything you capture lands in one stream, the Inbox, labeled "Nagbox". There is no separate reminders list to remember to reopen. Ordering is by your manual order, with resurfaced items and fresh captures jumping to the top.

Nag by presence Live

An item nags simply by being in the stream. You clear it by acting on it, not by silencing an alarm. When a snoozed item's time comes, the wake engine flips it back to the Inbox, jumps it to the top, pins it for you, and attaches a short chip explaining why it is back.

Capture Live

The four historical item types collapsed into one: a nag. You no longer pick a type when you capture; you just write the thing. A capture can carry a title, body, url, location, labels, icon, priority, a Remind time, a Due date, an assignee, and a recurrence rule.

Top bar Live

Pinned items live behind their own "Pinned" chip in the same lens bar, not a separate screen. The Stream tab carries its own item count. The Stream, Snoozed, and Done bar only appears on stream screens, so it stays out of the way everywhere else.

The verbs

You move the stream with four verbs. None of them deletes anything.

Done Live

Archives the item, never deletes it. If the item repeats, completing it spawns the next occurrence as a snoozed successor that inherits its labels and assignee.

Snooze Live

Sends an item away until a time you choose (it wakes and resurfaces then), or parks it as "someday" with no wake time. You can snooze silently, so it resurfaces without a push. From the Snoozed tab, Edit opens the same short form as everywhere else, title, space, labels, assign, with Remind pre-filled under More options, so one Save can change the nag, the snooze, or both.

Pin Live

Keeps an item up top and safe from Sweep. Pinning is per person and never changes the item's state. There is also a distinct protect state for things you want Sweep to skip without pinning them to the top.

Sweep Live

Clears a whole window of the stream at once, marking everything done except what is pinned or protected. It is a single undoable action. See Sweep and protect.

Back Live

The manual version of resurfacing: pulls an item back into the Inbox at the top, pinned, whenever you want it in front of you again.

Delete Live

Open a nag and tap Delete to remove it for good. The button asks for a second tap within a few seconds so a stray touch cannot delete anything. Deleting a repeating nag stops the repeat, and a deleted parent's sub-nags stay as their own nags.

Timing

Nagbox keeps two independent clocks. The short version: Remind is when it nags. Due is the deadline.

Remind Live

The clock that nags. Set it to later today, this evening, tomorrow, this weekend, someday, or a custom date and time. At that moment the item resurfaces at the top of the stream.

Due Live

An optional deadline, independent of the nag loop. It does not make the item resurface; it just stands, and shows in orange once it is overdue. If you want an item to come find you, set a Remind, not only a Due.

Repeats Live

Daily, weekdays, weekly, or monthly. Repeats are realized by clone on complete: finishing one instance schedules the next, waking it at 7 in the morning in your timezone. That holds through daylight saving changes, since it is anchored to the local wall clock, not a fixed offset. A space carries its owner's timezone, so a repeat inside one wakes on their clock. Completing it tells you when: "Done. Next: Sep 30."

Inside an item

Sub-steps Live

Drag a nag onto another to nest it as a sub, one level deep. The parent shows how many subs are left, and dragging one back out un-nests it. Reordering by drag works the same as it always has, on top-level nags and subs alike.

Icon Live

Give an item an icon from a curated set (home, cart, car, plane, and more) so a glance down the stream tells you what each thing is. Icons are named glyphs, not emoji, so they look the same on every device.

Priority Live

Normal, High, or Urgent, shown as a colored left edge on the row: amber for High, red for Urgent.

Links Live

A nag's url field has always shown as a small chip on the row, one tap to open it without expanding the nag. Now any http link written into the title or the notes gets the same chip, and is tappable right there in the text too, opening in a new tab.

Drag to reorder Live

Grab an item's grip and set your own order. The manual order sticks; resurfacing and fresh captures still jump to the top.

Labels and Lens

Labels Live

Create, color, and rename labels. Colors are assigned automatically from a fixed palette; renaming a label rewrites every reference to it. The rule that makes labels safe to use freely: labels organize, they never authorize. Applying or removing a label can never expose an item to someone, or hide it from someone. Who can see an item is decided entirely separately (see Spaces and offline).

Lens Live

A Lens is a saved view built from labels: an include set that matches all of its labels, an optional match-any set that matches any one of them, and an exclude set. Give it a name and pin it, and it appears in the quickbar across the top. Drag lenses into the order you want in the Lenses tab, and the pinned quickbar follows that order. Tap a label on a nag to add it to the filter bar; tapping the chip in the bar flips it between include and exclude. Search finds matching lenses first, so an unpinned lens is one search away. The X clears it, and "Save as lens" turns the combination into a named Lens, or updates the one you started from. On the Nagbox view, Save as lens also updates your own Nagbox lens, and any member of a shared space can update their own while creating named lenses stays admin-only.

Worth knowing: your Inbox is itself a Lens, so tuning what it shows uses the same builder as any other view. A Lens only ever narrows what you already see, it can never widen your visibility. Its own include and exclude sets are set per space, so what nags you in Family stays separate from Personal or work. And once a space has more than one member, any lens in it shows the whole board, every member's matching nags with the owner's name on each row; the Nagbox lens is the exception, staying narrowed to what is assigned to you. Named lenses belong to the space itself: in a space with more than one member, only an admin creates one; every member sees it by name and can pin it to their own bar, but only an admin can edit or delete it. Your own Nagbox lens keeps its include and exclude sets personal to you regardless. More on that in Spaces and offline.

Hide or protect, never delete Live

Hiding an item is an exclude clause on a Lens: the item stays live, just out of that view. Protecting keeps an item, or a whole Lens, out of Sweep. Neither is a delete. The only way things leave the stream is Done, which archives them.

Sweep and protect

Sweep marks done every unpinned, unprotected item in a time window, scoped to the Lens you are currently in. An empty Lens sweeps the whole Inbox window. The whole sweep is one action with one Undo.

What survives a Sweep

  • Anything pinned, by anyone.
  • Anything carrying the protect flag (the third pin state).
  • Anything under a Lens you have marked protected, for example a "Someday" or "Gift ideas" view you want kept safe from bulk clears.

You can turn on "Ask me to confirm before Sweep" in Settings. The confirm tells you exactly what will be swept and what will stay, and every sweep is undoable right after.

Spaces and offline

Spaces Live

A space is a shared stream with its own members, nags, labels, and lenses. Personal is the space only you can see. Create a space from the space list, invite people by their Nagbox username, and they accept from a card in their own stream. Once a space has more than one member, any lens in it shows the whole board, every member's matching nags with the owner's name on each row; the Nagbox lens is the exception, staying narrowed to what is assigned to you (see Labels and Lens). Assign a nag to any member: the Assign control sits on the short capture and edit form next to Space and Labels once a space has more than one person in it. The assignee gets a push, and when they mark it done you get one back. Press and hold a nag to select it, tap others to add them to the selection, then apply labels to all of them at once or assign them all to one person; multi-select works inside a space only. Labels and lenses belong to the space you made them in. There is no moving a nag between spaces; capture it where it belongs. Leaving a space or removing a member removes their view of it; nothing is deleted.

Everything Live

One view across every space you belong to, each item marked with where it lives.

Offline Live

Open a space with no signal and it still loads. Capture, Done, Snooze, and Back queue on the device and replay the moment you are back online.

Push notifications

Push is first party: standard VAPID Web Push, run entirely by us, with no Firebase or vendor cloud in the path. Web Push is the first-party channel. ntfy is an optional second channel you bring your own topic to, and it delivers alongside Web Push rather than instead of it. Nagbox never emails you.

Enabling it

Settings, Notifications, toggle the device on. That registers a service worker and subscribes this device. A "Send test push" button confirms delivery.

Quiet hours

Every account has a quiet window, 10 pm to 7 am local by default, editable in Settings, Notifications. A nag whose wake falls inside it still resurfaces in your stream right on time; only the push holds off, landing the moment the window ends.

ntfy

ntfy is an open notification protocol with a free app for Android and iOS: you pick a topic name, the app subscribes to it, and anything published to that topic lands on your phone. Nagbox can mirror every notification to a topic of yours, on our server at ntfy.nagbox.io or on any ntfy server you run yourself.

Set it up in Settings, Notifications: paste the server, the topic, and an access token for it, then Send test. Quiet hours apply to ntfy exactly as they do to Web Push, and every notification carries an Open button and a Done button that completes the nag without leaving the notification.

iOS: a browser tab cannot receive Web Push. You must add Nagbox to your Home Screen first (install the PWA), then enable notifications from the installed app. This needs iOS 16.4 or newer.

Agents, API, and MCP

Everything the app does is available to scripts and agents over the same REST API, and there is a Model Context Protocol server that wraps it so an assistant can work your nags directly.

Access tokens

Create a token in Settings, Access tokens. It is shown in full exactly once, at creation, then listed only by name, last four characters, and last used, with a Revoke button. Treat it like a password: it acts as you in every space you belong to, and a token can never mint or revoke other tokens.

REST API

Every space has the same API at /api/spaces/{space}/...: the stream and search, item create and edit, the verbs (done, snooze, pin, back), sweep and undo, the snoozed and done views, labels, saved Lens views, and members. /api/everything/... reads across every space you belong to. Push subscriptions, the profile, and import stay account level. Authenticate with Authorization: Bearer nbx_...; a token acts as you in every space you belong to. Errors come back as {"error": "..."}; a 401 means a bad or revoked token.

The MCP server

Nagbox ships a Model Context Protocol server, @nagbox/mcp. Point Claude Desktop, Claude Code, or any MCP-capable agent at it and it acts as you in every space you belong to, over your token, never seeing your password or session. The tools take a space argument that defaults to Personal; nagbox_spaces lists yours and nagbox_everything reads across all of them. It speaks MCP over stdio, so your agent launches it: no global install and no daemon to run.

npx -y @nagbox/mcp

Claude Desktop config

In Claude Desktop, Settings, Developer, Edit Config, add the block below and restart. Set NAGBOX_TOKEN to a token you minted in Settings, Access tokens.

claude_desktop_config.json
{
  "mcpServers": {
    "nagbox": {
      "command": "npx",
      "args": ["-y", "@nagbox/mcp"],
      "env": {
        "NAGBOX_URL": "https://app.nagbox.io",
        "NAGBOX_TOKEN": "nbx_your_token_here"
      }
    }
  }
}

The 17 tools

Each tool returns a concise text summary that carries item ids, so an agent can chain one call into the next.

ToolWhat it doesKey params
nagbox_captureCreate a task or reminder, optionally snoozed on creation.title (required), type, body, url, location, space, labels, priority, snooze
nagbox_listList the stream, the snoozed queue, or the done archive.view, space, label, pinned_only, limit
nagbox_getFull detail for one item.id, space
nagbox_doneMark done; recurring items spawn the next occurrence.id, space
nagbox_snoozeSnooze until a time, or park as someday.id, space, kind, until, label, silent
nagbox_pinPin or unpin for yourself; never changes state.id, space, pinned
nagbox_backBring an item back to the top of the Inbox, pinned.id, space
nagbox_sweepMark done every unpinned item in a time window.space, from_ts, to_ts
nagbox_editEdit title, body, url, location, labels, or priority.id, space, plus any field
nagbox_spacesList the spaces you belong to.none
nagbox_everythingRead the stream across every space you belong to, each item marked with its space.label, pinned_only, limit
nagbox_labelsList labels with counts.space
nagbox_searchFull text search across your items, title and body.query (required), space, limit
nagbox_next_nagThe top unanswered nag, with the answers it accepts.none
nagbox_more_nagsDeal more nags, capped at 2 a day and 2 open at once, then list what is waiting.none
nagbox_answer_nagAnswer a nag, validated against its kind.id, answer
nagbox_profileShow the interest profile built from answered nags.none

Hosting and your data

The app Live

Nagbox runs at app.nagbox.io: one app, ready in minutes, no setup beyond signing up. We run the servers, keep them patched, and back them up. It sells convenience, never features held back for a higher tier.

Import Live

Import accepts JSON or iCalendar (.ics), including Apple Reminders exports, with a preview, and re-importing the same file is safe.