---
title: Sort Projects by Usage
---
# 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](../../.claude/memory/contracts/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

The other projects-sidebar display choices — the funnel filter, the sidebar item list, and collapsing the sidebar — all live in the same header and each has its own page.