The .spruce Directory

Every Spruce project is a folder in your OS application-data directory. It's plain text end-to-end. You can inspect it with your OS file explorer, edit it with any text editor, and version it with git.

The folder isn't literally named .spruce on disk; that name is a historical label. Each project lives in a UUID-named directory under com.spruce.app/projects/. We still call it "the .spruce directory" in docs because that's how most users refer to the folder's contents.

Where it lives

The path is platform-determined and not configurable.

What's inside

.
├── .git/             Project git repo, syncs to the project remote
├── .gitignore
├── project.yaml      Shared project config (name, remotes, base branch, focus bar filter)
├── workspace.yaml    Machine-local config (linked code repo paths, worktree storage)
├── artifacts/        One subfolder per template (feature/, task/, bug/, chore/, memo/)
├── templates/        Artifact type definitions
├── views/            Saved views (filter / grouping configs for the artifact canvas)
├── actions/          Project-defined agent and shell commands
├── comments/         Comment threads (local SQLite; not committed)
├── workflows/        Event-triggered automations (feature-flagged)
├── users/            User profiles referenced by assignee fields
└── resources/        Attached files (images, etc.)

Editing files by hand

Spruce watches the project folder and reloads when files change, so external edits (text-editor tweaks, scripts, git pull, git rebase, cherry-pick) work fine. The app updates on its next watch tick.

A few caveats worth knowing:

• Don't break the schema. Editing an artifact's frontmatter to use a field that isn't in its template will be flagged as invalid until you fix it.
• Don't move files between template folders. A feature/SPR-abc.md belongs under artifacts/feature/ because the directory determines its type. Moving it to artifacts/task/ will confuse Spruce.
• Auto-save is in the app. If you edit a file in another editor while Spruce has the same artifact open, Spruce's last write wins. Save / close in the other editor before switching back to Spruce.

For everything else (bulk renames, scripted updates, sed-style fixes) go ahead. The on-disk format is the source of truth.

Related

• Per-Project Settings — project config editing inside the app.
• The Sidebar / sync menu — how the project gets committed and pushed.
• Spruce Directory File Layout — deeper file-by-file reference.