Workspaces

Virtual Workspaces

Workspaces let you organize notes without moving files. A note can belong to multiple workspaces, and workspaces can span multiple folders.

Defining Workspaces

Define workspaces in your strayfiles.toml:

version = 1

[settings]
roots = ["./notes", "./projects"]

[workspaces.work]
description = "Work-related notes"
include = ["projects/**"]

[workspaces.personal]
description = "Personal notes and ideas"
include = ["notes/personal/**"]

[workspaces.claude-code]
description = "Claude Code context files"
include = ["**/CLAUDE.md", "**/claude/**"]

Workspace Configuration

Each workspace supports these options:

[workspaces.example]
# Human-readable description
description = "Example workspace"

# Glob patterns to auto-include
include = [
  "docs/**",
  "notes/work/**"
]

# Glob patterns to exclude (overrides include)
exclude = [
  "**/*.draft.md"
]

# Color for UI (hex or named)
color = "#3B82F6"

# Icon (emoji or icon name)
icon = "📁"

Assigning Notes to Workspaces

Method 1: Auto-assignment via patterns

Notes matching workspace include patterns are automatically assigned:

[workspaces.ai-tools]
include = [
  "**/CLAUDE.md",
  "**/cursor/**",
  "**/copilot/**"
]

Method 2: Frontmatter assignment

Explicitly assign notes in their frontmatter:

---
title: Project Setup Guide
strayfiles:
  enabled: true
  workspaces: ["work", "documentation"]
---

Method 3: In-app assignment

Assign workspaces via the note actions menu in the strayfiles UI.

Workspace Examples

AI Coding Tools

[workspaces.claude-code]
description = "Claude Code context files"
include = ["**/CLAUDE.md"]
icon = "🤖"

[workspaces.cursor]
description = "Cursor IDE rules"
include = ["**/.cursorrules", "**/cursor/**"]
icon = "⚡"

Project Organization

[workspaces.active]
description = "Currently active projects"
include = ["projects/active/**"]
color = "#22C55E"

[workspaces.archive]
description = "Archived projects"
include = ["projects/archive/**"]
color = "#6B7280"

Content Types

[workspaces.blog]
description = "Blog posts and drafts"
include = ["content/blog/**", "drafts/**"]
exclude = ["**/*.draft.md"]

[workspaces.docs]
description = "Documentation"
include = ["**/README.md", "**/docs/**"]

Filtering by Workspace

Use the filter dialog in the TUI to narrow your note list by workspace. Open it from the notebook view to select one or more workspaces, and the note tree updates to show only matching notes.

Naming Rules

• Max length: 100 characters
• Allowed characters: alphanumeric characters, hyphens, underscores, and spaces
• Case-insensitive uniqueness: “Work” and “work” are considered the same workspace — you cannot have both
• Description limit: max 500 characters
• Deleting a workspace removes all note-workspace associations for that workspace. Notes themselves are never deleted.

Tips

• Notes can belong to multiple workspaces
• Workspace membership is non-destructive — files never move
• Use descriptive names and icons for easy scanning
• Color-code by project or priority