Views

A view is a named configuration — filters, group-by, sort, layout, and visible fields — applied to your project's artifacts. When you open Spruce, you land on a view. Pick a different one from the sidebar and the canvas reshapes itself.

There's no separate "all artifacts" page in Spruce. Every list of work is a view. Built-in views, the views your team has saved, and the By type rows in the sidebar all share the same canvas (toolbar, board / list / grouped layouts); only the configuration differs.

A view open on the artifact canvas with the toolbar above and the artifacts below

Built-in views

New Spruce projects ship with a handful of useful views out of the box:

• Active work: features and tasks with status Todo, In Progress, or In Review, grouped by assignee.
• Kanban: all work items grouped by status.
• Prioritization: backlog items grouped by priority for grooming.

You can edit or delete any of them. They're not special; they're just views that happened to ship with the project. Edit a built-in view's configuration the same way you'd edit one of your own.

By-type views

The By type section of the sidebar adds one row per template defined in your project (Features, Tasks, Bugs, Chores, Memos, and any custom types). Each row is a built-in view locked to that template, so you can't accidentally drift into another type.

By-type views are the same canvas as a saved view, with three practical differences:

• The template filter is always applied. The view is locked to one template; you can't widen it. Other filters (status, assignee, priority, custom fields) all still work.
• No Save button. A by-type view isn't a file on disk, so there's nothing to save (or rename, or delete). Your changes only live in localStorage.
• Filter / sort / visible-fields persist locally. Changes you make to a by-type view persist in your browser's localStorage, scoped per (project, template). They don't travel with the project repo.

If you want a configuration that travels with the project and your team, save it as a regular view in the Views section instead.

Defaults

When you first open a by-type view, Spruce shows:

• Visible fields: every field in the template's schema marked with hints: ["pinned"]. Falls back to just the template type if none are pinned.
• Sort: most recently modified, descending.
• Group by: none.

The view canvas

Every view renders on the same canvas:

• Toolbar at the top, with filter chips, group-by, sort, visible fields, and the layout picker (board / list / grouped).
• Body: the artifacts laid out per the chosen layout.
• Selection toolbar: appears when one or more artifacts are selected, for bulk edits.

The toolbar's trailing end carries the Save button (when you have unsaved changes) and a (...) menu with Rename and Delete for the open view.

Filter, group, and sort

The four toolbar controls (Filter, Group by, Sort, Visible fields) turn a flat list of artifacts into exactly the shape you want: a kanban board, a priority-ranked list, a per-assignee breakdown, anything.

View canvas with multiple filters applied and a search term

Filter bar

The filter bar accepts:

• Text search: matches artifact titles.
• Template filter: restrict to one or more artifact types (features, tasks, bugs, chores, memos). On a By type view, this filter is locked.
• Field filters: any field on the matching artifacts (status, priority, size, assignee, custom fields).

Filters AND-combine; every filter you add narrows the result. Remove a filter chip to widen the view.

Group-by

Pick any field from the Group by dropdown to break the list into sections. Common picks:

• Status: kanban-style columns.
• Assignee: per-person breakdown.
• Priority: what matters most at the top.
• Template type: separate features, tasks, and memos.

Sort

Pick a field and direction in the Sort dropdown. Sort interacts with group-by: within each group, artifacts are ordered by the sort field.

Visible fields

Use the Visible fields menu to choose which fields appear on each artifact card. Hide clutter; show the one metric that matters for the view.

Show / hide empty groups

Toggles in the toolbar let you show or hide:

• Empty groups: groups with no artifacts.
• The "no value" group: artifacts where the group-by field is unset.

Useful for either a full-picture review or a compact focus view.

The artifact mini chip

Every artifact card or table row in a view has a mini chip on the trailing edge that surfaces live status: a colored badge when there are uncommitted changes on the artifact's branch, and a session-count badge when terminal sessions are running. Hover the chip and the same menu the focus bar chips show pops open: Git section (Start / smart action / View changes / Git submenu / Commits), Sessions section, and Finish at the bottom.

It's the fastest way to act on an artifact's git or sessions without opening it. See The chip menu for the full breakdown.

View card with the trailing-edge mini chip hovered open, showing the same artifact menu as the focus bar

Creating a custom view

1. From any view (or a fresh search), set up the filters, group-by, sort, layout, and visible fields you want.

2. Click Save at the trailing end of the toolbar. The popover gives you two options:

   • Update "<current view name>": overwrite the view you're on with the new configuration. (The button shows the actual view name in quotes, e.g. Update "Active work".)
   • Save as New View: type a name in the input below the or divider, optionally pick an icon, and confirm. Use this when you want to keep the original around.

Modal to update an existing view or save as a new one. 3. The view appears in the Views section of the sidebar.

To start a fresh search without a saved view backing it, click the + button at the top of the Views section in the sidebar.

Renaming or deleting a view

When a saved view is open, the (...) menu at the right end of the toolbar holds Rename and Delete. There's no sidebar context menu; these operations only live in the toolbar of the view they apply to.

Where views live on disk

Each view is a markdown file in your Spruce project's views/ folder. The filename is the view's name; the frontmatter captures the filter / options config:

---
searchQuery:
  template: task
  customFields:
    status:
      type: in
      values:
        - Todo
        - In Progress
        - In Review
    priority:
      type: in
      values:
        - High
        - Critical
searchOptions:
  groupBy: assignee
  sortBy:
    field: priority
    direction: desc
  visibleFields:
    - status
    - priority
    - size
    - templateType
  showEmptyGroups: true
  showNoValueGroup: true
display:
  icon: bolt
---
# My active work

High-priority tasks I'm currently driving.

Each block does one thing:

• searchQuery: the what. template narrows by artifact type; customFields filters on any field defined in the template (status, priority, assignee, etc.) using type: in (one of N values), type: equals, type: not, etc.
• searchOptions: the shape. Group-by, sort, which fields show on each card, and the empty-group / no-value-group toggles.
• display: cosmetic. Icon shown next to the view in the sidebar.

Because views are just files, they're versioned with the rest of the project. Share a useful view by committing and pushing.

The default view

One view per project is the default (the one that loads when you open the project). The default is captured in project.yaml as the defaultView field (the view's filename without the .md):

# project.yaml
name: My Project
defaultView: Active work

Edit project.yaml directly (or via Per-Project Settings) to change the default. Bundles set this automatically when a new project is bootstrapped from a template.

Saved views vs. by-type views, at a glance

Use a saved view when the configuration matters enough to share or revisit across machines. Use a by-type view when you want a quick personal lens on one type.

Related

• The Sidebar — where views live in the nav.
• The Focus Bar — a pinned subset of work across pages.
• Per-Project Settings — setting the default view.