Get started
How Spruce Thinks
Spruce's model is built on a few small ideas. Get these and everything else falls into place.
Two roots: Spruce project + code repos
Spruce separates planning from code.
- A Spruce project is a versioned folder that holds your plan: artifacts, templates, views, actions, and config. It lives in your OS application-data directory and is itself a git repository, so you can push it to a remote and your team shares the same state.
- A code repository is where your source code lives. You link code repos to a Spruce project. A project can have zero, one, or many linked repos.
The two stay on disk as separate git repositories with separate remotes. Spruce's UI weaves them together, but they sync independently.
Everything is a file
Your plan is plain text on disk, inside your Spruce project folder. Artifacts are markdown files. Templates are markdown files. Saved views are markdown files. Actions are markdown files. You can grep them, git diff them, or open them in any editor. When you push the Spruce project, your teammates see the same state after a pull — git is the sync layer.
Artifacts are the unit of work
An artifact is a structured markdown document: frontmatter fields (status, priority, assignee, relationships) plus a markdown body. Every feature, task, bug, chore, or memo is an artifact. They're created, edited, and linked inside Spruce, but on disk they're just files under artifacts/ in your Spruce project.
Spruce ships with five built-in artifact types:
| Type | Use for |
|---|---|
feature | A unit of user-facing work, with optional child tasks and bugs |
task | A concrete unit of implementation work |
bug | A defect, regression, or unexpected behavior |
chore | Internal work with no direct user impact (build upgrades, OE, dependency bumps) |
memo | A top-level container for grouping related features, written thinking, epics, PRFAQs |
See Artifact Types for the full breakdown.
Templates are your schema
Each artifact type has a template that defines its fields, valid values, and UI behaviour. Templates are also files, stored in templates/ inside your Spruce project, so your team's schema is versioned with the rest of your plan. Edit a template to change how every artifact of that type behaves. See Editing Built-in Templates.
Worktrees connect artifacts to code
When you're ready to implement an artifact, click Start. Spruce creates a git branch in the linked code repo named after the artifact's ID (e.g. artifact/SPR-xxxxx) and a dedicated worktree: an isolated checkout at a path keyed off the same ID (e.g. <repo>/.worktrees/SPR-xxxxx/). You can create terminal sessions inside that worktree and work on multiple artifacts in parallel without branches interfering. See Branches and Worktrees.
Artifact header with the Start button highlighted
Agents are real collaborators
Spruce treats AI coding agents as first-class participants. You configure an action (a project-defined terminal command) that launches an agent (Claude Code, Codex, or any CLI agent) inside an artifact's worktree. The agent reads the artifact, writes code, and comments back through Spruce's MCP tools.
Comments show whoever authored them: your name on user comments, the agent's runtime name (e.g. claude or codex) on agent comments. Replies on an open thread can also be forwarded into a running agent session so the agent picks up your feedback mid-loop. See Comments and Agents & Actions.
The shape of a session
A typical loop in Spruce starts by sketching the work in an artifact, then drives it through three agent phases (plan, implement, review), reviewing the output between each:
- Sketch the work
Create or open an artifact, write a short description, set fields, link related work.
- Start
Click Start. Spruce creates a branch and worktree, both keyed to the artifact ID.
- Plan
Run the Plan action. The agent reads the artifact and proposes an implementation plan as comments on the artifact. Review the plan, reply with corrections, iterate until you're happy.
- Implement
Run the Implement action. The agent writes code in the worktree against the agreed plan. Review the diffs in the tool panel's Git tab; leave line comments where you want changes.
- Review
Run the Review action. The agent self-reviews the diff and surfaces issues. Address what's worth addressing, push back on what isn't.
- Ship
Push the code branch, open a PR, move the artifact to Done.
- Sync
Sync the Spruce project so your team sees the status change.
The plan / implement / review actions ship as defaults; you can edit them or add your own. See Action Recipes.
Split view: an artifact on the left, a worktree terminal running an agent on the right
Related
- Artifact Types — the built-in types in detail.
- Branches and Worktrees — how Start Working works.
- Actions — how agents get launched.
- The .spruce Directory — what's inside a Spruce project folder.