Get started
Hand Work to an Agent
Spruce is built to treat AI coding agents as real collaborators. In this walkthrough, you'll take the artifact you created earlier and hand it off to a supported agent — a dedicated branch, a dedicated worktree, and a terminal session where the agent does its work.
- Start
Open any artifact and click Start. It's the prominent filled button in the artifact header when there's no branch yet. Spruce:
- Creates a git branch named after the artifact ID (
artifact/SPR-xxxxx) in the linked code repo. - Creates an isolated git worktree for that branch at
<repo>/.worktrees/SPR-xxxxx/. - Opens a sessions panel scoped to that worktree.
From here, you could write code yourself. But let's hand it to an agent.
- Creates a git branch named after the artifact ID (
- Run an agent action
In the Sessions panel, click the + to open the action picker. New projects include four multi-mode agent actions:
- General: the default "do-anything" agent. Opens the agent in the worktree with the artifact's content as context. Use this for ad-hoc work that doesn't fit a specific phase.
- Plan: software-lifecycle action. The agent reads the artifact and proposes an implementation plan as comments on the artifact. Reply to the comments to refine.
- Implement: software-lifecycle action. The agent writes code in the worktree against the agreed plan.
- Review: software-lifecycle action. The agent self-reviews the diff and surfaces issues to address.
If you didn't pick a pack at setup, the action picker is empty until you add an action. See Action Recipes for ready-to-copy launchers, or import a pack from Settings → Import / Export → Import bundle.
Pick Plan to start the loop. Spruce opens a new session inside the worktree, runs the action, and the agent gets to work.
Sessions panel showing Claude Code, Plan, Implement, and Review actions
Actions are defined per project as markdown files in the project's
actions/folder. The four shipped above are starting points; edit them or add your own (e.g. Run dev server, Run tests, project-specific recipes). See Actions and Action Recipes.
Review the agent's work
You review the agent's work two ways: through comments on the artifact, and through diffs in the artifact's tool panel's Git tab (open it from the Git entry in the tab strip on the artifact's header).
Comments: the agent leaves comments via MCP tools, anchored to specific paragraphs, the artifact itself, or specific lines of code. They render with the agent's runtime name (e.g. claude, codex, or gemini) so you can tell agent posts from your own. Reply to a comment to guide the agent; it'll pick up your reply on its next iteration, and if the action is configured for comment forwarding, even mid-session. See Comments.
Artifact editor showing a thread of agent and user comments
Diffs: open the tool panel's Git tab. The Git tab shows uncommitted changes and the branch's commit history inline, with file-tree navigation, inline diffs with syntax highlighting, and blame on each line. You can leave comments on specific lines of code inside the diff view, useful for flagging "this should use the existing helper instead" without losing the context of the change. The artifact-scope Activity tab (and the global Activity page) gives you the same content cross-cut by event timeline; the Code tab is for browsing the worktree's files. See Diffs and Commits and Comments.
Push and open a PR
When you're happy with the work, head into the tool panel's Git tab. Every git affordance lives there in one vertical strip:
- Review the changed files and diffs one last time (Activity tab or View changes → Uncommitted in the Git tab).
- Click Commit in the Git tab.
- Click Push branch.
- Click Create PR to open your git host (GitHub, etc.) with the branch pre-selected.
See The tool panel for the full Git tab anatomy. :::
Related
- Branches and Worktrees — how Start is implemented.
- Actions — how the agent launcher and other project commands are defined.
- Diffs and Commits — reviewing code changes.
- Comments — line-anchored review comments.
- Commenting Back on Agent Work — iterating with the agent.