Get started
Open Your First Project
The Spruce home screen has two paths to a working project:
- Create or Import: start a new Spruce project (linking code repos along the way) or clone an existing Spruce project from a git remote.
- Open: point Spruce at a Spruce project folder you've cloned manually outside the wizard, or re-open one you've previously opened.
If you already have a project from your team to clone, Create or Import → Import is the path. If you're starting fresh, Create or Import → New is the one. Both walk you through a multi-step wizard.
Creating a new project
Click Create or Import, pick New, and you'll go through four steps:
- Project
Name the project, pick a color badge, and choose an alias (the 1–3 letter prefix on artifact IDs like
ABC-x9z3qa). Every new project is seeded from the base bundle: the five built-in artifact templates (feature, task, bug, chore, memo), three built-in views (Kanban, Active work, Prioritization), and the four agent actions (Plan / Implement / Review / a generic do anything) with every supported agent mode (Claude Code / Codex / Kiro / OpenCode / Gemini) pre-configured.There's also an Include tutorial artifacts checkbox on this step. Leave it on (the default for first-time users) and Spruce seeds the project with five short walkthrough tasks — Welcome, Create your first artifact, Find your work with views, Hand work to an agent, Sync your changes — plus the screenshots they reference. Once you've done the tour, mark them Done or delete them like any other artifact. Uncheck it on subsequent projects to skip the seed entirely; your choice is remembered for next time.
- Project Remote
Set up the remote where the Spruce project's git repo will be pushed. You can attach an existing remote, create a new one (Spruce can create a GitHub repo if you connected GitHub in the welcome wizard), or skip and add a remote later.
- Code Repositories
Link the code repos you want to work against. You can:
- Browse your repos: pick from the GitHub repos Spruce sees via your connected account.
- Clone from URL: paste a git URL and Spruce clones it locally.
- Add a local path: point Spruce at a repo you've already cloned.
- Skip: leave the project plan-only for now; link repos later.
- Review
Confirm the configuration. Spruce creates the project folder in your application-data directory, initializes the git repo, configures the remote, and clones / links any code repos you picked.
Project wizard with the stepper at the top showing Project / Project Remote / Code Repositories / Review
Importing an existing project
If your team already has a Spruce project hosted on git, Create or Import → Import is the three-step path:
- Import
Paste the Spruce project's git URL. Spruce clones the project into your application-data directory.
- Code Repos
The project's
project.yamlknows which code repos it links to; Spruce shows the list and offers to clone any that aren't already on your machine. - Review
Confirm and finish. Spruce opens the project at the view set as
defaultViewinproject.yaml.
The import flow doesn't seed anything from the base bundle and doesn't offer the tutorial-artifacts toggle; you inherit whatever templates, views, actions, and artifacts are already in the project (since they're committed to its git repo).
Plan-only projects
If you don't link any code repos in the wizard, Spruce is still fully usable as a planning tool. The Code page and worktree features stay hidden, but artifacts, comments, views, templates, and agents all work. You can link a code repo later from Settings → Code repositories.
Where the project lives on disk
You don't choose where Spruce project data lives; it's stored in the standard OS application-data location, keyed by a project UUID:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/com.spruce.app/projects/<uuid>/ |
| Linux | ~/.config/com.spruce.app/projects/<uuid>/ (or $XDG_CONFIG_HOME) |
| Windows | %APPDATA%\com.spruce.app\projects\<uuid>\ |
This keeps project data out of your code repos and portable across machines via the project's git remote. See The .spruce Directory for what's inside.
Syncing
The Spruce project is a git repo. Use the sync menu in the sidebar header to commit and push your project changes. Code repos sync through their normal git workflow; Spruce's sync menu is scoped to the Spruce project.
Sync menu in the sidebar header showing pending changes and Commit / Push controls
Linking more repos later
If you want to link additional code repos after the wizard, or change which repos are linked, head to Settings → Code repositories. See Per-Project Settings.
After your first project: the sidebar dropdown
Once a project is open, the everyday path to spin up another one isn't the home screen. It's the project switcher in the sidebar header. Click the project chip to drop down a list of all your projects, with New Project… and Import Project… at the bottom that re-open the same wizard you just walked through.
Two clicks from anywhere in the app, no need to navigate back to the home screen.
Related
- The .spruce Directory — what's inside a Spruce project.
- Per-Project Settings — linking repos, base branches, and more.
- The Sidebar — where the sync menu and project switcher live.