---
title: Tags — Browse Sessions by Tag
---
# Tags — Browse Sessions by Tag

## What it is

> **Library page** — describes what users see and how to use it. Self-contained so an outside AI (with no repo access) can read this and answer "what is the Tags view and how do I use it?"

The **Tags** virtual project is a sidebar entry that lets you browse every Claude Code session by the tag attached to it. It follows the standard three-pane project layout: the leftmost project sidebar (where you click **Tags** to enter), a tag-list sidebar in the middle column at the same width as a normal project's session sidebar, and the main panel on the right showing every session carrying the tag you select, grouped by project. The tag list shows both **library** tags (curated entries you create in Settings → Tags) and **free-form** tags (short strings you typed onto a session in the picker).

It is the **read** companion to two existing tag features:

- **[session-tags.md](session-tags.md)** is where you _apply_ a tag to a single session (the **T** picker / overflow menu).
- **[tag-manager.md](tag-manager.md)** is where you _curate_ the library of tags (Settings → Tags — name, color, scope, description).

The Tags view is primarily a faceted browse surface — pick a tag on the left, see every session that carries it on the right. It also exposes a **+ New tag** affordance in the sidebar header (described under "Tag sidebar" below) so you don't have to hop into Settings → Tags to add a library tag while you're already browsing here. Applying a tag to a session still happens through the **T** picker on an open session, and rename / delete still happen through the right-click menu (also described below).

### What it shows

### Tag sidebar (middle column — same width as a project's session sidebar, default ~268 px, resizable)

A header row at the top shows a **TAGS** label on the left and a small **+** icon-button on the right. Clicking the + opens the same **Add tag** dialog as Settings → Tags (`mode="create"`) — name, optional description, color, and scope (Global / Specific projects). Saving creates the library row and emits the `tags:changed` push, so the new tag immediately appears in the **Library** section below without a manual refresh. The + button is keyboard-accessible (focus ring, `aria-label="New tag"`) and is visible on every viewport including mobile.

Below the header row, a search input filters both sections in place by lowercased substring match.

Below the search box, two collapsible sections:

- **Library** — every active library tag visible to you, sorted by most-recently-applied first. Each row shows the tag's color dot (or a default surface dot if the tag has no color), the tag name, and a count badge (number of sessions carrying that tag). Click to select.
- **Free-form** — every distinct free-form tag string in use across your sessions, sorted by most-recently-used first. Same row shape — default gray dot, name, count badge — minus library-only data. The free-form list is **deduped against library**: if a free-form tag's lowercased name matches a library tag's, the free-form row is suppressed (the library entry already covers it). Click to select.

Selected row gets the standard accent highlight (`bg-accent/20`); hover gets a softer accent tint. While the library catalog is still loading on first paint, three skeleton rows render in place of the Library section. With the search box filled and no matches in either section, an empty state replaces the list.

The sidebar is resizable via the same drag handle as any project's session sidebar — your width preference persists across launches.

#### PRD Stack section (bottom of the sidebar)

Below the tag list, the same **PRD Stack** strip that appears in every project's sidebar shows up here too — one row per active PRDStack attention item, each with a title, subtitle, and (on mobile only) an X to dismiss. Clicking a row jumps you into the PRDStack project just like the strip in any regular project's sidebar. If there are no PRDStack attention items, the strip is hidden.

### Main panel — sessions for the selected tag

Initially shows a centered "Select a tag" empty state.

Once you pick a tag, the main panel fetches its session list (a single IPC call for library tags; an in-memory filter for free-form) and renders every matching session, **grouped by project**. Each group has a heading row showing the **project icon** next to the **project name**, then the sessions for that project in most-recently-active order. Groups themselves are ordered by the most-recently-active session inside them, so the project that has been active most recently sits at the top.

Each session row shows the session title, its status dot (running / paused / ended / etc.), the project's color bar, and the last-activity timestamp. Click a row to jump straight into that session — Tags hands you off to the SessionPanel the same way the global search does.

If the selected tag has no sessions, an "Nothing is tagged with this yet" empty state shows. If the IPC fetch fails for a library tag, an inline error with a **Retry** button appears.

## Where to find it

1. Open Omniscio.
2. In the project sidebar, scroll to the Omniscio group (the section under the "Omniscio" divider).
3. Click **Tags** (pink Tag icon, between **Stats** and **Settings**).

The Tags panel opens just like any other project — the project sidebar stays put on the far left, the tag-list sidebar replaces the session list in the middle column, and the right side shows the sessions for whichever tag you select.

## How it behaves

### How to use it

### Pick a tag → see its sessions

1. Open the Tags virtual project.
2. (Optional) type into the search box to narrow either section.
3. Click a row in **Library** or **Free-form**. The main panel swaps to that tag's session list.
4. Click any session row to open the session.

### Right-click a tag for actions

Right-click a row to open a small context menu next to the cursor:

- **Library tag** → **Rename** (opens the same Tag Edit dialog as Settings → Tags, focused on the name field), **Change color…** (opens the same dialog but focused on the color picker section), and **Delete** (confirm dialog reads `This removes the tag from N session(s). Free-form tag chips with the same name remain unaffected.`).
- **Free-form tag** → **Delete** only. The confirm dialog reads `This removes the tag chip from every session that has it. Library tags are unaffected.` Confirming scrubs the string from every `sessions.tags` array that holds it (the existing `session:delete-tag-globally` path).

The menu closes on Escape, on outside-click, on right-click, and after any item is chosen. There is no rename or color edit for free-form tags — free-form is a string, not an entity; the workflow for "rename a free-form tag" is to delete it globally and re-tag with the new string, and free-form chips derive their color from a deterministic hash of the name (see [session-tags.md](session-tags.md)).

**Rename and Change color…** open the same dialog (`TagEditDialog`); the difference is which control gets initial focus. Pick **Rename** when you want to retype the name immediately; pick **Change color…** when you want to scroll straight to the swatch grid. Saving applies the same `tags:update` IPC; the Tags view re-renders both the sidebar row's color dot and any chip strip showing that tag.

### Remove a tag from a single session (right pane × button)

For library tags only, each session row in the right pane carries a small **×** button on the trailing edge. Hover or focus the row to see it on desktop; on mobile it is always visible. Click × to **remove that tag from just this session** — the row disappears immediately (optimistic remove), an IPC call to `tags:unapply` runs in the background, and a toast surfaces `Removed "<tagname>" from "<sessionname>"` with an **Undo** action. Pressing Undo re-applies the same library tag (`tags:apply`); the row pops back into the list when the next push refresh fires.

The middle of the row is still a click target — clicking the row body opens the session like before. The × button stops click propagation, so removing the tag never accidentally navigates to the session. While the IPC roundtrip is in flight the × is disabled so a frantic double-click can't queue duplicate unapply requests. If the IPC fails, the optimistic removal rolls back (the row reappears in place) and the toast surfaces the error message verbatim.

Free-form tags do **not** show the × in the right pane — to clear a free-form tag from a session, open the session, press **T**, and click × on the chip in the picker (the existing flow). This asymmetry is intentional: library applications live in the `session_tags` join table and have a precise unapply IPC; free-form tags live as JSON strings on the session row and editing them goes through the picker so the user sees the chip strip update in context.

### Mobile drill-in

On a phone-width viewport, only one pane shows at a time, the same way every other sidebar virtual project behaves. The tag list takes the full width by default. Tapping a tag drills in: the list disappears, the sessions pane takes over the full width, and a **`<`** back chevron sits in the header. Tapping the chevron returns to the tag list (the previously-selected tag stays selected — that's a global preference, not a per-mobile-page reset). There is no right-click context menu on mobile.

### State persistence

Your **selected tag** and your **search query** persist to `localStorage` under the key `amc.tags-view.state` (Zustand persist envelope). Reopening Tags later restores both — the main panel fetches the previously-selected tag's sessions automatically. Selection is also shared live across the sidebar reader and the main-panel reader, so opening Tags in two surfaces (e.g. mobile + desktop window) keeps the selection in sync.

### Live refresh on tag changes

If the library catalog or any session's tags change while Tags is open — you applied a new tag from another window, deleted a library tag in Settings, an automation modified a session — the main panel re-renders automatically. Two push events drive this: `tags:changed` (any library mutation) and `tags:session-tags-changed` (any per-session apply / unapply). The Tags view listens for both and bumps an internal `refreshKey` so the sessions pane refetches.

You do not need to manually reload.

### Differences from session-tags and tag-manager

| Feature                  | What you do here                                                                                                                                 | Library page                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
| Apply a tag to a session | Open a session, press **T**, type or pick. The Tags view does **not** apply tags.                                                                | [session-tags.md](session-tags.md) |
| Create a library tag     | Either Settings → Tags → **+ New tag**, or the **+** button in the Tags sidebar header (this view). Both open the same **Add tag** dialog.       | [tag-manager.md](tag-manager.md)   |
| Edit a library tag       | Right-click a library row in this view and pick **Rename**, or click the pencil icon in Settings → Tags. Both open the same **Edit tag** dialog. | [tag-manager.md](tag-manager.md)   |
| Browse sessions by tag   | The Tags view (this page).                                                                                                                       | _this page_                        |

The dedupe rule (library wins on lowercased name match) is the same as the SessionPanel header chip strip — see [tag-manager.md](tag-manager.md) "Renderer dedupe rule".

### Out of scope (v1)

- **No multi-tag intersect.** You can only select one tag at a time. There is no "show me sessions that carry both `urgent` and `feature`" filter.
- **No bulk operations.** Sessions in the right pane are read-only rows — no Shift+J/K multi-select, no bulk archive / pause / snooze. To bulk-act on tagged sessions, jump back to the project sidebar and use the existing [bulk-select-sidebar.md](bulk-select-sidebar.md) workflow.
- **No CLI control endpoints.** The localhost CLI server exposes no `/tags-view/*` routes — the same v1 limitation as the rest of the tag system.

## Related

- [session-tags.md](session-tags.md) — applying tags via the **T** picker
- [tag-manager.md](tag-manager.md) — the library, scope rules, and the IPC contract
- [stats.md](stats.md) — the other "browse" virtual project in the Omniscio group
- [bulk-select-sidebar.md](bulk-select-sidebar.md) — Shift+J/K multi-select for batch operations on tagged sessions (run from the project sidebar, not Tags)