---
title: Tasks (markdown outliner, in development)
---
# Tasks (markdown outliner, in development)

## What it is

> **Status: in development** — gated behind the Labs toggle at **Settings → Lab → Tasks** (`tasksV2Enabled`, default OFF). The feature — its sidebar project, IPC handlers, CLI routes, and the markdown mirror file — is completely inert unless the toggle is on, Omniscio is launched with `AMC_SHOW_TASKS_V2=1`, or the feature is marked `shipped` in the unreleased-feature registry.

> **Naming.** The feature is just **"Tasks"** everywhere a person or an AI reads it. Its
> internal _persisted_ identifiers keep their original byte-stable form for data safety — the
> `tasks_v2` SQLite table, the `tasksV2*` settings keys, the `'tasks-v2'` feature id, the
> IPC/CLI channels, and the `<userData>/tasks-v2.md` mirror file all stay as-is so existing
> saved data keeps resolving (no migration). Those names are code-only and never surface to
> the user. Same split Omniscio uses for KMS, and for "Projects" (the `lists` table) below.

Tasks is the next-generation parallel-task outliner for Omniscio, surfaced as a virtual project in the sidebar (label "Tasks"). It is a keyboard-driven tree of to-do rows where **each row's text is real markdown**: in view mode the row renders the markdown (headings, **bold**, `code`, lists); **single-click (or tap) a row to highlight it** (it just selects/focuses the row) — to start typing, **double-click** it or press **Space** on the highlighted row, and it swaps to a raw-source contenteditable for editing (**Enter** instead adds a new task right below it; on a phone, where there's no keyboard, a tap only highlights and you edit via the focused row's **✏️ Edit button**). Rows nest with **Tab / Shift+Tab** — and **Tab indents only the focused row, leaving its sub-items at their depth** (they re-home to the new parent beside the row rather than descending with it; v1 Tasks keeps the whole-subtree indent). Rows also **reorder three ways** — **drag a row up/down** (long-press the row to grab it on a phone), the **Move up / Move down** rows in a focused row's ⋯ menu, or **Alt+Shift+↑/↓** — duplicate (Ctrl/Cmd+D) or archive (Ctrl/Cmd+Delete — like checking it off), and carry due / snooze / ctx / importance / urgency / estimated-time / tag chips. (Hand-reorder only applies in the manual sort with no filter — under any other sort or an active filter the on-screen order is a view overlay, not the saved order, so dragging and the Move rows are disabled. See [Sort & filter](#sort--filter).) Its **Task details** button (the sliders icon, or `Cmd/Ctrl+;`) opens a pane to edit its **due date, snooze-until, context, importance + urgency dials, scheduled start date, estimated time, and tags** — each field auto-saving as you leave it (no Save button). See [Rich fields & fast capture](#rich-fields--fast-capture) below. Completing a parent cascades "done" through its undone descendants; archiving a row (incl. via Ctrl/Cmd+Delete) files its whole subtree into Archived, restorable — **except a future-snoozed sub-task, which is never swept when you clear its parent: finishing, deleting, or archiving a parent spares each parked sub-task and lifts it to the top level of its project, so it survives and still returns on schedule** (only the parent and its non-snoozed sub-tasks leave). A sub-task snoozed for _later_ is deferred work you chose to keep, so clearing what's above it can't quietly take it with you.

Tasks persist in the `tasks_v2` SQLite table (the source of truth) and mirror out to `<userData>/tasks-v2.md` (atomic write, 500 ms debounce) so local AI agents and humans can read the current task tree as plain markdown.

Tasks are organized into **named "projects"** — each project is its own workspace with shared **master context** (a free-form markdown note pinned above that project's tasks). Every task belongs to exactly one project; the default **Inbox** holds anything not filed elsewhere, and all pre-existing tasks were backfilled into it. See [Projects & master context](#projects--master-context) below.

**By default Tasks shows ONE giant list** that folds every project's tasks into a single editable workspace, with **projects as collapsible top-level nodes** — fold a project down to its header, or **filter the whole view down to one project** (via the header **"Show ▾"** control or the project rail). Add a task (each project header carries a **"+"**), reorder (drag within a project — or drag a task into ANOTHER project, even an empty one), check off, and edit details all happen right here. **Find** (`/`), **bulk-select** (Ctrl/Cmd+A), and **repeating tasks** ("every monday") work everywhere. See [The giant default view](#the-giant-default-view--all-your-tasks-in-one-list) below.

> **"Projects" is a label, not a new thing.** What the UI now calls a "project" is stored and wired as a **"list"** under the hood — the table (`tasks_v2_lists`), the `list_id` column, the IPC channels, the CLI routes, and the `tasks-v2.md` mirror structure are all unchanged. Only the words you see changed (the same approach Omniscio uses for KMS). No migration ran and no task moved.

Tasks is a **separate feature from the original Tasks (v1)** personal outliner (since removed) — different table, store, IPC channels, and mirror file. They shared no state.

**It opens instantly.** Tasks paints whatever it loaded last time the moment you open it and refreshes in the background (stale-while-revalidate, keyed on the store's `hydrated` flag), so the loading skeleton only ever appears on the genuine first-ever load — not on every revisit. On desktop the panel is additionally kept **warm**: mounted-but-hidden once you've opened it, so switching back is an instant display flip rather than a cold rebuild of the outliner plus a refetch (the same keep-warm model KMS uses; the view's code chunk is also preloaded at idle once keep-warm is on). You can opt out under **Settings → Tasks → "Keep Tasks loaded in the background"** (`tasksV2KeepWarmEnabled`, default on, desktop only); turning it off restores the load-fresh-each-time behavior. Mechanism + invariants `loading-skeleton-hydrated` + `panel-keep-warm` live in `.claude/memory/contracts/tasks-v2-contract.md`.

## Where to find it

In development and off by default — turn it on at **Settings → Lab**. Once on, **Tasks** appears as a project in the sidebar.

## How it behaves

### The view at a glance — progressive disclosure

The default view is deliberately quiet: the **project rail** on the left, a **one-line header** titled **"All Projects"**, and **all your tasks grouped under collapsible project headings** — each heading carrying a **"+"** to add a task to that project. Everything else opens **on demand** from the header, so the screen shows the next right thing instead of a wall of always-on cards.

The header (`TaskV2Header.tsx`) carries — the title on the left, the rest right-aligned:

- the **title is itself the "Show ▾" dropdown** (desktop) — click the title to pick what you're looking at: **All Projects** (the giant default view) or any single project (filters the list down to it). It's the header twin of the project rail, and reads **"All Projects"** in the giant default view or the project name when filtered. On mobile the title is the rail switcher instead; the old separate right-side "Show:" pill was merged into the title;
- a **"Right now" pill** — **hidden since 2026-06-22, not on the header today**; it showed the prioritizer's single next-task pick inline and opened the focused "Right now" panel (see [Prioritizing AI](#prioritizing-ai--right-now--the-daily-check-in));
- a **"Due" badge** — appears **only when something is actually due soon** (overdue / today / this week; the count uses the same `isActionableV2` + `dueBucketOf` gate the Due list does, so badge and list never disagree); click for the cross-project due list;
- a **Filter funnel** — opens a popover with sort + importance threshold + tag toggles (a dot marks an active filter); while such a filter (importance/tag — persisted across reloads) hides rows in the All Projects view, each project heading's count reads an honest **"n of m"** (visible-of-total, e.g. `0 of 3`) instead of the bare total, so it can never claim more tasks than the group draws (feedback 6ece04b6, the reporter's "a count that ignores the filter is worse than no count"); and when the filter hides **every** task of an expanded project, that project also shows a subtle **"N hidden by filter — Clear filter"** line where its rows would be, so the group never reads as a silent blank you'd mistake for lost data and one click clears the filter (feedback 439aa646);
- a **keyboard-shortcuts button** (the keyboard icon, **desktop only**) — opens the full shortcut cheat-sheet, the same one the **`?`** key opens, so the keys are discoverable without already knowing them;
- a **Find button (🔍)** — opens the find-as-you-type bar (the same one `/` and Ctrl/Cmd+F open) — see [Find tasks](#find-tasks--or-ctrlf);
- a **"⋯ More" menu** — daily check-in, master context, send-to-inbox, export JSON, **Archived** (the browsable archived-tasks area — see [Archive & universal undo](#archive--universal-undo)), **Customize** (the inline Tasks-settings panel — show checkboxes, checkbox selects, finish without asking, compact rows, hide completed, auto-capitalize, the AI next-task pick, catch follow-ups, evening wrap-up, plus a **"More task settings…"** link into full settings; **also reachable from a bottom-pinned "Customize" entry in the left project rail**, a peer of **Archived**, so the Tasks settings open straight from the sidebar — not only this menu), and the "Suggest breakdowns" toggle;
- **when a SINGLE project is in view**, three project-level quick-action icons — **Launch agent** (starts one agent on the whole project, via the same list-launch prompt), **Snooze all**, and **Set priority** — appear right-aligned too; they're hidden in the giant **All Projects** view (where the per-project rows carry them instead) and Snooze / Set priority disable on an empty project (anchors `tasks-v2-listheader-launch-agent` / `-snooze-all` / `-set-priority`).

Each control opens its detail in a small popover (`TaskV2HeaderDisclosure.tsx`) that is portaled to `document.body` and viewport-clamped (`containToViewport`) so it can never paint off-screen, and closes on Esc or an outside click. In the giant **All Projects** view the per-project controls that only make sense for one project drop away, and the title reads **"All Projects"** (filter to one project and it shows that project's name).

On each task row, the actions are **two primary buttons** (Task details, Launch agent) plus a **"⋯" overflow menu** holding **Add subtask** (creates a child under this row, in its project), **Copy** (copies the task's own text to the clipboard — the discoverable, mobile-reachable copy; the keyboard has none), **Cut** / **Paste here** (the mouse/touch way to move a task — see [Cut & paste a task](#cut--paste-a-task); "Paste here" shows only when something is cut), Context, Break it down, Move to project, and — in the manual sort — **Move up / Move down** (the tap way to reorder, hidden at the very top / bottom of a group so there's never a dead row) (`TaskV2RowActions.tsx`); **on mobile a leading ✏️ Edit button is also shown** (the deliberate edit affordance, since a tap on a mobile row only highlights it). (**Attach a session** is no longer an on-row icon — it now lives on the right-click menu and the `⋯ → Context` flow; see [Context attachments](#context-attachments).) On **desktop the cluster reveals right after the row's text** and **stays hidden until you hover the row** — or tab a button into keyboard focus — then fades in next to the item. It **flows inline with the text**, so on a long row it lands at the **end of the last line, or wraps to the next line** rather than running off the right edge of the panel where it would be cut off; and because hovering only fades the buttons in (their slot is already reserved) the list never jumps as you move the mouse; **on mobile the cluster stays inline** right after the text too (touch has no hover — see the phone note below). While a row is being **edited**, the cluster hides so it never covers the text you're typing. **The moment you start navigating by keyboard, that hover reveal is suppressed** — the action buttons, the archive checkbox's proximity glow, and the row's faint hover-background tint all go quiet, so a cursor left parked over the list doesn't keep a row lit while you're keyboarding; it all comes right back the instant you move the mouse (and keyboard focus still surfaces a control, so nothing is unreachable). The **same cluster appears in the giant default view** — its rows behave exactly like the per-list outliner (see [The giant default view](#the-giant-default-view--all-your-tasks-in-one-list)). **On a phone there is no hover, so the cluster stays on the tapped/focused row and is always visible — and reads tighter**: the icons grow to fill their 44px tap targets and the gap between them closes, so they no longer float far apart in fat buttons; desktop spacing is unchanged. **Right-click anywhere on a row (desktop) opens that same action set as a cursor-positioned menu** — the full list (Task details, Launch agent, Attach a session, the Style row — Star / Bold / Highlight, Add subtask, Insert link, Get link title, Copy, Cut, Paste here, Context, Break it down, Move to project, the manual-sort Move up / Move down, Finish), each shown only when it applies — so you can act on a row without first focusing it and hunting for the ⋯ button; right-clicking a row _while you're editing its text_ falls through to the browser's normal copy/paste menu. **Both editable views** (the giant default view and a single-project outliner) wire it on the row wrapper via `TaskV2RowContextMenu.tsx`, built on the shared `MenuShell` (theming, viewport-clamping, and keyboard nav come for free); the rows live in ONE shared source (`TaskV2RowActionItems.tsx`) that both the ⋯ menu and the right-click menu render, so they can't drift. A row with attachments shows a **clickable** 📎 count chip as a trailing item — on **every** row (the focused/selected one included), **fully visible at rest** and sitting right after the text; the hover buttons reveal just past it and never cover it. **Click the chip to peek at the attachments and open any one** (see [Context attachments](#context-attachments)).

### Pop out into its own window

Tasks can open in its **own desktop window**, so you can keep your tasks on-screen beside other work. Two ways in:

- the **pop-out button** in the Tasks header (the "Open in new window" icon — **desktop only**, since there are no separate windows on mobile/web), or
- **right-click the "Tasks" row** in the sidebar → **Open in new window**.

The popped-out window is the **whole Tasks panel** — same list, projects, keyboard, AI surfaces, and per-task agent chat — and it stays **fully live**: task edits, reorder/move, context attachments, the AI "Right now" / daily check-in / break-it-down, and the per-task agent chat all update in real time, and changes you make in the main window show up in the pop-out (and vice-versa). The window remembers its size and position between opens and follows your light/dark theme; opening it again just focuses the window that's already open. It also wears Omniscio's **own themed title bar** — a slim draggable "Tasks" strip with themed minimize/maximize/close buttons, matching the KMS pop-out — instead of the plain native window frame. The main window keeps its Tasks view too — the two are independent views of the same tasks.

Under the hood this reuses Omniscio's generic project/integration pop-out window (the same mechanism KMS and any project use), so there's no separate Tasks window to maintain. The button is hidden when you're already inside the pop-out window.

### Keyboard: two modes (writing vs command)

Tasks is built to be driven entirely from the keyboard, and it borrows vim's
answer to the "is this key typing text or running a command?" problem: **two modes**.
There's no mode badge — you tell the modes apart by how the focused row looks:
rendered markdown means command mode, a raw-text editor with a caret means writing
mode. The focused row carries a strong **cursor highlight** — a solid accent **left bar**
plus a faint accent tint and a hugging ring — so the row you're on is obvious at a glance
and clearly distinct from a multi-selected row (which has a fill + glow, no bar). Its
**colour reinforces the mode**: a settled command-mode row gets the **accent** bar, while a
row you're actively typing in (writing mode) switches to a distinct **green** ring + faint
green tint, so "I'm editing this one" reads at a glance with no badge (and on a phone, tapping a row just highlights it — no
badge pops up); the outliner's own scroll-container focus outline is deliberately
suppressed (it used to overflow the panel's right edge — the "white rectangle" report).
The highlighted row also **shows its action controls** — the finish checkbox and the row's
buttons (task details · launch agent · ⋯) appear on whichever row you're on, the same ones a
mouse hover reveals, so you can act on the current task without reaching for the mouse. Every
other row stays clean until you hover or point near it, keeping the list uncluttered (desktop
behaviour; on a phone the controls are always shown).
**Opening Tasks puts the keyboard cursor straight on the list** — switching into the
panel focuses it and highlights the first task, so the arrow keys / `w`-`s` / `j`-`k` work
immediately without clicking a row first (desktop only; mobile has no keyboard nav). The
list grabs focus the moment the panel becomes the active view — including when you switch
back into a kept-warm panel and in the pop-out window — and it never steals a focus you
deliberately placed inside the list (contract invariant `focus-on-entry`).
**Clicking (or tapping) anywhere on a row's body highlights it** — the whole row is the
target, not just its text, so a short task with lots of empty space still selects on a
click in that space (the action buttons, snooze chip, inline editor and checkbox keep
their own clicks). A double-click anywhere on the body edits. **Checking off (finishing) the
highlighted task moves the highlight to the next task — staying inside its project**: to the next
task below it in the _same_ project, else the one above it (it was at that project's bottom), else
the first task of the next project (it was that project's last) — so you can clear a list
top-to-bottom without re-selecting each time. **Snoozing the highlighted task moves the highlight
exactly the same way** — finishing and snoozing share ONE selection rule, so the cursor lands in
the same spot either way and a quick finish or snooze never strips your place in the list. Only a
single snooze moves the cursor; a bulk snooze (a whole project, or a multi-selected batch) leaves
it put (contract invariant `I11`).
**As you move the highlight (arrows / `w`-`s` / `j`-`k`), the list scrolls to keep the focused
row in view** — it glides smoothly and keeps ~2 rows of breathing room above/below the cursor,
so the active row never rides off the edge or jams flush against it, and it stays put while the
row is already comfortably in view (no jumpiness as you read). **Moving a row itself follows the
same rule, on every reorder key** — the one-hand keys (`Shift+W`/`Shift+S` to move,
`Shift+A`/`Shift+D` to outdent/indent) AND the arrow-key route (`Alt+Shift+↑/↓` to move,
`Tab`/`Shift+Tab` or `Alt+Shift+←/→` to indent/outdent), a single row or a nudged multi-row block
alike, scroll the list so the row you're moving stays on screen instead of riding off the top —
not just when the cursor steps between rows. The glide drops to an instant jump under
reduce-motion / low-power. This works the same across all three keyboard surfaces — the
per-project outliner, the default "All Projects" view, and the Today plate (contract invariant
`keyboard-nav-scrolloff`).

- **Writing mode** — you're typing the task's text. You land here whenever you create
  a task or open one for editing. Press **Enter** to **finish editing** — it commits the
  text and drops back to command mode (so does **Esc**). Enter never leaves a stray empty
  task behind. **Cmd/Ctrl+Enter** goes one step further — it commits the task _and_ opens a
  fresh row right below in edit mode, so you can type the next one without lifting your hands
  (rapid entry). (**Finish** the task itself — done + archive — is `x` / `e` / the checkbox /
  `Delete`; Cmd/Ctrl+Enter no longer finishes.)
- **Command mode** — the row shows its rendered markdown and single keys _act_ on it
  (they don't type). Press **Space** to drop into writing mode and edit the row; press
  **Enter** to add a **new task right below** and start typing it — so capturing many
  tasks is Enter, type, Enter, type… Need one _above_ instead? **Shift+Enter** adds a
  **new task directly above** the highlighted one — the mirror of Enter. A brand-new or
  empty row opens straight in writing mode, so Space is the key you reach for to _re-edit_
  an existing row.

In command mode, with a task highlighted:

## Related

- [Tasks (markdown outliner, in development) (part 2)](tasks-v2-part-2.md) — the continuation of this page.
- [Tasks (markdown outliner, in development) (part 3)](tasks-v2-part-3.md) — the continuation of this page.
- [Tasks (markdown outliner, in development) (part 4)](tasks-v2-part-4.md) — the continuation of this page.
- [Tasks (markdown outliner, in development) (part 5)](tasks-v2-part-5.md) — the continuation of this page.
- [Tasks (markdown outliner, in development) (part 6)](tasks-v2-part-6.md) — the continuation of this page.
- [Tasks (markdown outliner, in development) (part 7)](tasks-v2-part-7.md) — the continuation of this page.
- [Tasks (markdown outliner, in development) (part 8)](tasks-v2-part-8.md) — the continuation of this page.
- [Tasks (markdown outliner, in development) (part 9)](tasks-v2-part-9.md) — the continuation of this page.
- [Tasks (markdown outliner, in development) (part 10)](tasks-v2-part-10.md) — the continuation of this page.
- [Tasks (markdown outliner, in development) (part 11)](tasks-v2-part-11.md) — the continuation of this page.
- [Tasks (markdown outliner, in development) (part 12)](tasks-v2-part-12.md) — the continuation of this page.

The earlier personal outliner has its own page, kept only as a redirect. Agents started from a task are ordinary sessions, so the page on starting a session applies to them too.