Skip to main content
Spruce

Spruce

Docs

Discord

Reference

The .spruce Directory File Layout

This page is a precise, file-by-file reference for what lives inside a Spruce project directory. For a higher-level overview, see The .spruce Directory.

Project root

<app-data>/com.spruce.app/projects/<project-uuid>/
├── .git/                  Standard git repo for the Spruce project
├── .gitignore             Excludes workspace.yaml, sqlite dbs, and caches
├── .gitattributes         Normalizes line endings, marks binary files
├── project.yaml           Shared project config (pushed)
├── workspace.yaml         Machine-local config (not pushed)
├── spruce.db              SQLite: comments, queues, caches (not pushed)
├── artifacts/
├── templates/
├── views/
├── actions/
├── comments/
├── workflows/
├── users/
└── resources/

project.yaml

Shared project config. Pushed with the project so teammates inherit settings.

yaml

name: My project
badge: "#06b6d4"
baseBranch: main
defaultView: Active work
focusBarFilter:
  conditions:
    - type: hasBranch
    - type: fieldFilter
      field: assignee
      filter:
        type: in
        values: []
        includeCurrentUser: true
codeRepositories:
  - id: core-app
    name: Core App
    remote: git@github.com:org/core-app.git

workspace.yaml

Machine-local config. Not pushed.

yaml

codeRepositories:
  - id: core-app
    localPath: /Users/alice/src/core-app
worktreeStoragePath: /Users/alice/src/worktrees

artifacts/

One subfolder per template type. Each artifact is a markdown file named <id>.md.

artifacts/
├── feature/
│   ├── SPR-abc123.md
│   └── SPR-def456.md
├── task/
│   └── SPR-ghi789.md
├── bug/
├── chore/
└── memo/

templates/

One markdown file per template. Filename is the type identifier; feature.md defines the feature type.

views/

One markdown file per saved view. Filename is the view display name.

actions/

One markdown file per project-defined action. Filename is the action name. Each file's frontmatter defines one or more modes — an argv invocation for an agent CLI (e.g. claude, codex, gemini, kiro-cli, opencode) or a shell command. The active mode is picked at run time, defaulting to the project's default agent. See Actions for the on-disk shape.

comments/

Comment thread files mirroring SQLite state for git diff/merge compatibility. Primary storage is spruce.db; these files are regenerated on change. One file per anchor (artifact or code line).

workflows/

Event-triggered automation definitions (feature-flagged). One file per workflow.

users/

User profiles referenced by assignee / user fields. One file per user.

resources/

Attached files (images, PDFs, etc.) referenced from artifact bodies.

spruce.db

SQLite database for comments and mutable state. Not pushed (excluded via .gitignore). Regenerated from the comments/ files on a fresh clone.

Reference

Spruce CLI

Reference

Glossary