TOML Configuration Reference

Complete strayfiles.toml Reference

This reference covers every configuration option available in strayfiles.toml.

File Location

Strayfiles looks for configuration in this order:

Current directory: ./strayfiles.toml
Walking up: ../strayfiles.toml, ../../strayfiles.toml, …
User config: ~/.strayfiles/strayfiles.toml

Basic Structure

version = 1

[settings]
# Indexing settings

[sync]
# Git sync settings

[workspaces.name]
# Workspace definitions

[tags.name]
# Tag definitions

Version

version = 1

Always 1 for current format. Required field.

[settings]

Controls which files are indexed and how.

settings.explicit_only

[settings]
explicit_only = false

Value	Behavior
`false` (default)	Index all Markdown files in roots
`true`	Only index files with `strayfiles.enabled: true`

settings.roots

[settings]
roots = ["./notes", "./docs", "~/Documents/notes"]

Directories to scan for Markdown files. Supports:

Relative paths: ./notes
Absolute paths: /Users/me/notes
Home expansion: ~/Documents
Environment variables: ${HOME}/notes, ${PROJECTS_DIR}
Glob patterns: **/CLAUDE.md, projects/*/docs

settings.exclude

[settings]
exclude = [
  "node_modules/**",
  ".git/**",
  "**/dist/**",
  "**/*.draft.md"
]

Glob patterns to exclude from indexing. Common excludes:

Pattern	Excludes
`node_modules/**`	Node.js dependencies
`.git/**`	Git internals
`target/**`	Rust build output
`/dist/`	Build output directories
`/.next/`	Next.js build
`/archive/`	Archived content
`*/.draft.md`	Draft files

settings.extensions

[settings]
extensions = ["md", "mdx", "markdown"]

File extensions to index. Default: ["md", "mdx"]

[sync]

Git-based sync configuration.

sync.git_auto_commit

[sync]
git_auto_commit = true

Enable automatic Git commits on save. Default: false

sync.commit_message

[sync]
commit_message = "strayfiles: auto-save"

Commit message for auto-commits. Default: "strayfiles: auto-save"

sync.git_remote

[sync]
git_remote = "origin"

Git remote to push to. Default: "origin"

[workspaces.name]

Define virtual workspaces for organizing notes.

Full Workspace Example

[workspaces.work]
description = "Work-related notes"
include = ["projects/**", "work/**"]
exclude = ["**/archive/**", "**/old/**"]
color = "#3B82F6"
icon = "📁"

workspace.description

[workspaces.work]
description = "Work-related notes and documentation"

Human-readable description. Shown in UI.

workspace.include

[workspaces.work]
include = ["projects/**", "**/work/**"]

Glob patterns for auto-assignment. Files matching any pattern are assigned to this workspace.

workspace.exclude

[workspaces.work]
exclude = ["**/archive/**", "**/drafts/**"]

Glob patterns to exclude. Overrides include matches.

workspace.color

[workspaces.work]
color = "#3B82F6"

Hex color for UI display. Examples:

#EF4444 - Red
#F59E0B - Amber
#10B981 - Green
#3B82F6 - Blue
#8B5CF6 - Purple

workspace.icon

[workspaces.work]
icon = "📁"

Icon for UI display. Can be emoji or icon name.

[tags.name]

Define tags with auto-assignment patterns.

Full Tag Example

[tags.urgent]
description = "High priority items"
include = ["**/urgent/**", "**/critical/**"]
exclude = ["**/resolved/**"]
color = "#EF4444"
icon = "alert"

tag.description

[tags.urgent]
description = "Items requiring immediate attention"

Human-readable description.

tag.include

[tags.api]
include = ["**/api/**", "**/endpoints/**"]

Glob patterns for auto-tagging.

tag.exclude

[tags.api]
exclude = ["**/api/deprecated/**"]

Glob patterns to exclude from auto-tagging.

tag.color

[tags.urgent]
color = "#EF4444"

Hex color for UI display.

tag.icon

[tags.urgent]
icon = "alert"

Icon for UI display.

Environment Variables

Use ${VAR} syntax for environment variables:

[settings]
roots = [
  "${HOME}/notes",
  "${PROJECTS_DIR}/docs",
  "${WORK_DIR}/documentation"
]

Also supports ~/ for home directory:

[settings]
roots = ["~/Documents/notes"]

Complete Example

version = 1

[settings]
explicit_only = false
roots = [
  "./notes",
  "./docs",
  "~/Documents/strayfiles"
]
exclude = [
  "node_modules/**",
  ".git/**",
  "**/dist/**",
  "**/target/**",
  "**/*.draft.md"
]
extensions = ["md", "mdx"]

[sync]
git_auto_commit = false
commit_message = "docs: update via strayfiles"
git_remote = "origin"

[workspaces.work]
description = "Work projects and documentation"
include = ["projects/**", "work/**"]
exclude = ["**/archive/**"]
color = "#3B82F6"
icon = "📁"

[workspaces.personal]
description = "Personal notes and ideas"
include = ["personal/**", "ideas/**"]
color = "#8B5CF6"
icon = "💡"

[workspaces.claude-code]
description = "AI coding assistant context"
include = ["**/CLAUDE.md", "**/claude/**"]
color = "#F59E0B"
icon = "🤖"

[tags.urgent]
description = "High priority"
include = ["**/urgent/**"]
color = "#EF4444"
icon = "alert"

[tags.reference]
description = "Reference documentation"
include = ["**/reference/**", "**/docs/**"]
exclude = ["**/drafts/**"]
color = "#10B981"
icon = "book"

[tags.draft]
description = "Work in progress"
include = ["**/*.draft.md", "**/drafts/**"]
color = "#6B7280"
icon = "edit"

Config Discovery

Strayfiles walks up the directory tree looking for strayfiles.toml:

/Users/me/projects/app/docs/
    ↓ not found
/Users/me/projects/app/
    ↓ not found
/Users/me/projects/
    ↓ found! strayfiles.toml

This allows project-specific configs that apply to subdirectories.

Multiple Configs

You can have multiple config files:

Project config: ./strayfiles.toml in each project
User config: ~/.strayfiles/strayfiles.toml for global settings

Project config takes precedence when both exist.

Precedence with In-File Metadata

In-file metadata (frontmatter or HTML comments) takes precedence over TOML auto-assignment:

Explicit workspaces in frontmatter override TOML include patterns
File-level enabled: false excludes the file regardless of TOML settings
TOML patterns only apply when no explicit in-file value exists

See Metadata Precedence for the complete precedence hierarchy.