The Artifact Editor

The artifact editor is where you read, write, and organize an artifact. It renders from the markdown file on disk and writes back as you type.

Layout

The editor has three regions stacked top-to-bottom-and-right:

• Header: title, pinned field chips (status, priority, size, assignee), the lifecycle buttons (Start before there's a branch, Finish at the bottom of the Git tab afterwards), and the tool tabs that open the tool panel.
• Body: a full markdown editor with inline previews, a floating toolbar, slash commands, and source-view toggle.
• Tool panel: the collapsible right pane that the tool tabs open. Closed by default; clicking a tab opens it on the right. Default width 420 px, minimum 280 px; drag the divider to resize. Each tab routes to one of the artifact-scope tools. See The tool tabs below.

The artifact editor with header, body, and the tool panel open on the right

The header

Every artifact opens with a header strip across the top of the editor. The header is the artifact's command surface: title, status, the lifecycle buttons (Start / Finish), and the tool tabs that open the tool panel.

Left to right:

1. Breadcrumb: where you came from (project / view / artifact)
2. Title: click to rename
3. Pinned field chips: status, priority, size, assignee. Click any chip to edit. See Fields and Status.
4. Start button: visible only when the artifact has no branch yet. See Start below.
5. Tool tabs: anchored to the trailing edge. Open the tool panel; clicking the active tab again closes it.

Start

When an artifact has no branch yet, Start appears as a prominent filled button in the header. Click it and Spruce:

1. Creates a branch named after the artifact ID (e.g. artifact/SPR-abc123)
2. Creates a git worktree for that branch at <repo>/.worktrees/SPR-abc123/
3. Opens a terminal session in the worktree

After that, the button disappears and the Git tab takes over the same surface area in the tool tabs. That's where the rest of the git affordances live now, including Finish at the bottom.

The keyboard shortcut for Start works whether or not the button is visible. See Keyboard Shortcuts.

Finish

Once the artifact has a branch, Finish is the closing counterpart to Start. It lives at the bottom of the Git tab in the tool panel (in red), so it's always one click away while you're working on the artifact, but doesn't compete for attention in the header itself.

Clicking Finish removes the worktree and (if clean) deletes the branch. See Finish for the details and Git for everything else in the Git tab.

The tool tabs

Up to five tabs are available, in this order. Each opens the tool panel on the right and routes to one of Spruce's tools — scoped to the open artifact rather than project-wide.

Clicking a tab opens the tool panel; clicking the active tab again closes it.

Tab badges

Some tabs decorate their label:

• Git: +N −N total diff stats when there are uncommitted changes; just the icon and label otherwise.
• Sessions: a colored play-icon badge replaces the plain icon when sessions exist (teal for running, orange-pulse for awaiting input). The session count is appended after the label.

The tool tabs subscribe to the artifact's git status, so badges update live without a manual refresh.

State and persistence

The tool panel remembers its state per artifact:

• Open/closed: persists across sessions, per project.
• Active tab: persists across sessions.
• Width: drag the divider; the chosen width persists.
• Per-artifact context: which tab you had open, scroll position, the active session, the open file in Code. Click an artifact chip in the focus bar and you drop right back into where you left off — that's what makes the panel work for context-switching between in-flight work.

If you reopen Spruce on an artifact whose snapshot has the Git tab selected but the branch no longer exists, the Code tab content shows a friendly stub instead of breaking; the Git tab itself is hidden until Start is run again.

Embedded vs. global

The tool panel is the embedded half of Spruce's tool model: same content as the global Tools section, but scope-locked to the open artifact. Each tool has a pair of shortcuts:

• ⌘⇧<key>: toggle this panel and switch to the tool's tab.
• ⌘⌥<key>: navigate to the matching global page from anywhere.

Sessions uses single-modifier ⌘J for the tab (VSCode-style exception). Git is artifact-scope only; its toggle is ⌘⇧V and there's no global page.

Each tool's canonical page in §4 Tools covers both surfaces and any differences between them.

Writing

The body supports the full GitHub-flavored markdown spectrum: headings, paragraphs, lists, tables, blockquotes, inline and fenced code blocks, images, and Mermaid diagrams in fenced blocks tagged ```mermaid.

Three input affordances make this fast:

Slash commands

Type / on a new line to open the slash menu. Actions are grouped by category:

• Turn into: Paragraph, Heading 1-3, callouts.
• Format: Bold, Italic, Inline code.
• Insert: Code block, bullet/numbered list, checklist, link, image, table, Mermaid diagram.
• Tasks: checklist item, due-date stamp.
• AI: agent-assist prompts (when an agent action is configured).
• Link Artifacts: drop in a chip for another artifact in the project.

Pick from the menu with arrow keys + Enter, or keep typing to fuzzy-search. Esc dismisses without inserting anything.

Slash command menu

Floating toolbar

Selecting text pops a small inline toolbar with bold / italic / inline code / link, plus a "Turn into" picker for converting the selection to a heading, list item, or other block type. The toolbar is just the visual entry-point for the same actions the slash menu exposes.

Floating editor menu

In-app link schemes

Inside the Spruce app, you can write links using two custom schemes that render as clickable chips:

• Artifact chips: reference another artifact in the same project. Markdown form: [SPR-abc123](artifact://SPR-abc123). Renders as a clickable chip with the target's title and color.
• Code chips: reference a specific file in a linked code repo. Markdown form: [file.ts](code://src/file.ts). Use the full path from the repo root.

These only resolve inside Spruce; in exported markdown, treat them as plain text. For generic portable links, use inline code: `SPR-abc123`, `src/file.ts`.

The breadcrumb-bar menu

The breadcrumb at the top of the editor has a (...) menu on the right with utilities that don't fit elsewhere:

• Copy artifact ID: clicks copy the ID (e.g. SPR-abc123).
• Copy Spruce link: a buildwithspruce.com/open/... URL teammates can click to jump straight to this artifact in their Spruce.
• Copy branch name (when the artifact has a branch): artifact/SPR-abc123.
• Copy worktree path (when a worktree exists): the absolute path on disk.
• Attach File: open a file picker to attach a file to the artifact.
• Find: open the in-editor find bar.
• Source: toggle Source view (described below).
• Show Resolved Comments (⌘⇧/): toggle resolved-comment visibility in the body's gutter.
• Duplicate: copy the artifact (frontmatter + body) into a new artifact.

Artifact menu options

Source view

The editor renders rich-text by default, with inline previews of images, code, and Mermaid diagrams. To see and edit the raw markdown, open the (...) menu in the breadcrumb bar (above) and toggle Source. Switching modes keeps the cursor position.

Source mode is useful for hand-editing frontmatter, syntax-precise edits, or copying chunks out as plain markdown.

Relationships and metadata

Relationship fields (e.g. a task's feature, a feature's tasks) and metadata (ID, timestamps, author) render inside the body, not in a separate panel. Click a relationship chip to navigate to the linked artifact; the breadcrumb tracks where you came from so you can back out cleanly.

Attachments

Drag a file onto the editor (or paste from clipboard) to attach it. Images render inline; other files appear as download links. Attachments live in the project's resources/ folder and travel with the project through git.

Reveal an attachment in your system file browser from the attachment row, useful when you want to open a file in another app.

Auto-save

There's no save button. The editor writes changes to disk as you type; the sync menu in the sidebar header surfaces pending project changes.

Related

• Code, Activity, Comments, Sessions, Git: the five tools the tool tabs open.
• Fields, Status, and Priority — the chips in the header.
• Artifact Relationships — the relationship fields inside the body.
• Branches and Worktrees — what Start does.
• Keyboard Shortcuts — paired tool shortcuts and ⌘⇧W for Start.