Sort Projects by Usage

What it is

An opt-in projects-sidebar display mode that ranks your projects by how much you've used them lately — the number of sessions you have started in the last 30 days — so the ones you are actively working on rise to the top of the group they are already in. It is a display preference — it never renames, moves, archives, hides, or deletes anything, and turning it off restores your manual drag order exactly.

Default: OFF in the base settings, but ON for two of the four onboarding personas, so you may have it without having chosen it. Check the ⋮ menu if your sidebar order looks unfamiliar.

It can never hide a project. Ranking is all it does. See History below — an earlier version also hid dormant projects, and that had to be removed.

What it does — one pass

Rank within the group you already built. Eligible projects are re-ordered by their recent session count (sessions started in the last 30 days), most-active first, and refill the slots they already occupied. That is the whole design: dividers, section headers, parent groups and pinned rows keep their exact positions, and a project can never jump from one divider into another. If you keep "Work" and "Personal" dividers, each one re-ranks against itself. A project with no recent sessions simply sorts last inside its own group — it stays on screen.

Pass ordering matters and is fixed: the usage sort runs before the Unused / Auto-Tidy split, so Auto-Tidy's id-based membership can never shift underneath it.

Where to find it

Turning it on

Projects sidebar header → the ⋮ overflow menu → Sort by usage. The same menu item turns it back off ("Go back to your manual drag order"). While it is on, the same menu lists the window presets — Last 7 / 30 / 90 days, the active one marked — so you can change how far back "recent" reaches.

Two settings back it:

Key	Default	Meaning
sidebarSortByUsageEnabled	false	Master toggle for the ranking pass.
sidebarUsageWindowDays	30	The "recent" window in days (⋮ menu presets: 7/30/90).

How it behaves

What is eligible

An unpinned, real, plain project. Specifically excluded:

• Pinned projects — pinning is an explicit "keep this here" instruction and outranks the sort.
• Parent groups and their child projects — a group's internal order is its own.
• Virtual / plugin projects (Decks, Flowcharts, Workflows, Agent Tools, and the rest) — they are built-in surfaces, not things you "use often."

Divider membership does NOT disqualify a project. An earlier version of this feature refused to reach into dividers at all; measured against a real 155-project install, 149 of those projects sat inside a divider, leaving 2 eligible rows and making the feature a no-op for anyone who actually organizes their sidebar. The pass partitions by dividerId and ranks within each divider instead.

Drag behaviour while it is on

With the sort on, drag is disabled for group-child rows, because a reordered row's baked-in visibleIndex would point at the wrong drop target. With the sort off, drag behaves exactly as it always has — the disable is gated on the setting, not unconditional. Turn the sort off if you want to rearrange by hand.

Who it is for

Someone with many projects who actively works across a shifting subset. If you have few projects, or have not started sessions recently, turning this on does very little: the ranking has nothing to distinguish, so the order barely moves. Every project still shows.

History — why there is no "Rarely Used" group

Until 2026-08-28 this feature had a second pass that pulled every project with no recent sessions into a collapsed Rarely Used group at the bottom. It was removed after it blanked two users' sidebars.

The flaw was in the signal. The recent-session count is computed from the renderer's live session list, and archived sessions are not in it — they live in a separate list that is only fetched on demand and is empty at startup. So a count of 0 means "nothing live right now", not "never used". Archive your conversations and every project reads as dormant, the demote sweeps them all into the collapsed group, and the sidebar renders nothing but headings and an "Add Hub" button. One reporter hit this with 262 archived sessions against 6 live ones and lost all 11 of her hubs, through restarts and a reboot.

It was reported twice. The first response (2026-08-24) added a "Showing 0 of 11 — Show all" rescue notice over the hiding; the second reporter was on a build that predated even that. The cure was to stop hiding: fixing the count alone would not have been enough, because a perfect archive-aware count still blanks the sidebar of anyone who simply has not started a session in 30 days.

The rule this leaves behind: rank, sort, or badge on a heuristic signal — never gate visibility on one, least of all a signal that is a lower bound rather than a true total. See projects-active-filter-contract.md, sort-by-usage-ranks-it-never-hides.

For agents

Where the code lives

Concern	File
The pure ranking transform	src/renderer/src/features/dashboard/sidebar-usage-sort.ts
Eligibility + pass ordering	src/renderer/src/features/dashboard/sidebar-grouping.ts
Desktop wiring + the ⋮ menu	src/renderer/src/features/dashboard/ProjectsSidebar.tsx
Mobile list	src/renderer/src/features/dashboard/MobileProjectsList.tsx
Tests	tests/unit/features/dashboard/sidebar-usage-sort.test.ts, …/sidebar-grouping.test.ts

Ranking data is each project's count of sessions started in the last 30 days, computed in the front-end from the live session list — the same data that drives the sidebar's status badges — so it needs no extra database call and updates as you work. That count is a lower bound, not a true total: archived sessions are not in the live list, so a project whose conversations you have all archived ranks lower than its real usage deserves. That is acceptable for ordering and is exactly why the count may never drive visibility. The window defaults to 30 days (USAGE_RECENT_WINDOW_DAYS) and is set by the sidebarUsageWindowDays setting — the ⋮ menu offers 7 / 30 / 90-day presets (USAGE_WINDOW_PRESET_DAYS).

Related

• show-only-active-projects.md — the funnel filter in the same header.
• sidebar-items-visibility.md — the sidebar item list, in the same header.
• sidebar-collapse.md — collapsing the sidebar, in the same header.
• projects-sidebar.md — the sidebar these controls live in.