Floatee
smart_toy

menu_book Floatee documentation

Floatee is a centralized store of todos, ideas and notes, agent-first. It replaces the scattered TODOs.md files in your repos with a web app and a REST API your coding agent can drive. This guide walks through the concepts and day-to-day usage. For the API reference, head to the Integration guide.

rocket_launch Quick start

  1. Sign in with GitHub or Codeberg from the login page.
  2. A default workspace is created automatically. Create a project from the sidebar.
  3. Capture with the quick-add field: Fix the slider @alarum +bug !todo.
  4. Open the project to organize in List or Kanban, drag between statuses, snooze what's not now.
  5. Wire your agent: open Project → Settings → Set up your agent and follow the steps.

folder Workspaces & projects

  • Workspace — a group, typically a team or your personal stuff. Shareable by invitation; every member sees everything.
  • Project — a topic within a workspace (one per repo is a good rule). Carries its own slug, used by quick-add @slug and passed to the agent API as ?project=<slug>.
  • Items without a project land in the workspace inbox.

check_circle Items: types & statuses

Every item is a todo, an idea, or a note. Only todos have a status (pending → in_progress → done, plus blocked and wontfix), and only todos are processed by the agent's /next. Promote an idea to a todo in one click — it keeps its id, tags and history.

The body is markdown. GFM checklists - [ ] become interactive, and a 3/7 progress badge shows on the card.

Images (screenshots, mockups) can be pasted, dropped or attached 📎 right into the body — a Pro feature. They render inline, and your agents can fetch them over the API with their token.

bolt Lightning capture

The quick-add field is everywhere (header on desktop, the FAB on mobile). Inline tokens are parsed wherever they appear and previewed as chips:

  • @slug — target project (default: inbox).
  • =assignee — assign to a teammate or an agent (=me for yourself; one keystroke, autocompletes). They get a push notification.
  • +tag — add a tag (multiple allowed).
  • !todo / !idea / !note — force the type (default todo).
  • %1w / %1m / %3m — snooze immediately.
  • #142 — reference another ticket (autocompletes by id or title; renders as a link).

Markdown works right in the field (styled live, no toolbar): **bold**, *italic*, `code`, ~~strike~~, lists (- , 1. ) and todos ([ ] / [x], shown as a checkbox).

Paste, drop or attach 📎 an image right from the quick-add or any editor — screenshots go straight onto a ticket (Pro).

  • / — jump to the quick-add field from anywhere.
  • Ctrl/⌘+Enter — add the item.
  • Ctrl/⌘+B / I / ⇧X — bold / italic / strikethrough the selection.
  • Ctrl/⌘+⇧. — turn the line into a todo ([ ]).
  • Enter — new line; inside a list/todo it continues it (empty item exits).
  • ↑ ↓ then Enter/Tab — navigate & accept token suggestions.
  • Esc — clear the field (or dismiss suggestions).

On Android, share text/links straight into Floatee via the Web Share Target. Offline captures queue and sync when you're back.

bedtime Snooze

Items float at rest on the water and come back when called. Snooze for 1 week, 1 month, 3 months or a custom date. A sleeping item leaves your lists (a collapsed "Sleeping" section keeps it in reach) and wakes on its date — back to the top of the list, with a soft "woke up" dot. No cron, no notification.

smart_toy Agents

Create an account token under Settings → Your agent (the same token works in every repo — the project is passed per request), drop a .floatee file at your repo root, and paste the AGENTS.md block. Your agent can then fetch the next todo, comment, and mark it done with a resolution note. Full reference in the Integration guide.

The helper kits (the floatee CLI for Node, Python or shell) self-update: when a newer kit ships, the next command transparently refreshes the CLI and your /todo commands — your custom instructions are kept. Opt out with auto_update=off in .floatee (then floatee selfupdate applies on demand). The curl build, having no executable, only flags when an update is available.

search Search & history

Nothing dies. Full-text search (Ctrl/Cmd+K) covers titles, bodies, resolution notes, tags and comments — including done, wontfix and deleted items. That's the whole point: ask "did we already handle something like this?" and actually get an answer.

shield Account & security

Your account can link several OAuth providers (GitHub, Codeberg); Floatee never lets you unlink your last identity. Deleting your account is final and removes everything you own in a single transaction.

help More