Project Configuration

strayfiles.toml

Place a strayfiles.toml file at the root of any folder or repository to configure how strayfiles indexes that location.

Basic Example

version = 1

[settings]
explicit_only = false
roots = ["./notes", "./docs"]
exclude = ["node_modules/**", ".git/**"]

Full Reference

# Config version (always 1 for now)
version = 1

[settings]
# Only index files with strayfiles.enabled = true
explicit_only = false

# Folders to index (relative to this config file)
roots = [
  "./notes",
  "./docs",
  "./projects/*/CLAUDE.md"
]

# Directories where all files are auto-tracked (no frontmatter needed)
tracked_directories = [
  "./auto-notes"
]

# Glob patterns to exclude
exclude = [
  "node_modules/**",
  ".git/**",
  "**/dist/**",
  "**/*.draft.md"
]

# File extensions to index (default: md, mdx)
extensions = ["md", "mdx", "markdown"]

[sync]
# Auto-commit changes (requires git)
git_auto_commit = false

# Commit message template
commit_message = "strayfiles: auto-save"

# Remote to push to (optional)
git_remote = "origin"

# Workspace definitions (see Workspaces docs for full details)
[workspaces.work]
include = ["docs/**", "projects/**"]

[workspaces.personal]
include = ["notes/**", "journal/**"]

# Tag definitions (see Tags docs for full details)
[tags]
pinned = ["important", "review"]

For the complete field-by-field specification, see the TOML Reference. For workspace configuration details, see Workspaces. For tag configuration, see Tags.

Settings Explained

explicit_only

Controls whether strayfiles indexes all Markdown files or only those explicitly opted in.

[settings]
explicit_only = false  # Index all Markdown files (default)
explicit_only = true   # Only index files with strayfiles.enabled = true

When to use explicit_only = true:

• Large codebases with lots of Markdown you don’t want indexed
• When you want precise control over what appears in strayfiles
• Repos with generated documentation you want to exclude

roots

Specify which folders to scan. Paths are relative to the config file.

[settings]
roots = [
  ".",           # Current folder
  "./notes",     # Subfolder
  "../shared",   # Parent folder
  "~/Documents/notes"  # Absolute path (expanded)
]

Glob patterns work too:

[settings]
roots = [
  "./projects/*/docs",      # All project docs
  "./clients/**/notes.md",  # Nested client notes
]

tracked_directories

Directories where all matching files are automatically tracked without modification.

[settings]
tracked_directories = [
  "./notes",
  "./projects/docs"
]

Key differences from roots:

Feature	roots	tracked_directories
Discovery	Files found and indexed	Files found and indexed
Tracking	Requires frontmatter or HTML comment	Automatic (path-based)
File modification	UUID can be injected	Files never modified
Rename handling	UUID survives moves	Tracking lost if moved

When to use tracked_directories:

• You want to track all files in a folder without modifying them
• Files that should never have frontmatter added (e.g., existing docs)
• Quick setup — no need to inject metadata into each file

Example: Track all notes without modification

[settings]
roots = ["./docs"]                    # Indexed only (discovery)
tracked_directories = ["./notes"]     # All files auto-tracked
exclude = ["**/drafts/**"]            # Still respects exclusions
extensions = ["md"]                   # Only track .md files

Files in tracked_directories are tracked by path. If you rename or move a file, tracking is lost (like TOML-based file tracking). For rename-proof tracking, use frontmatter or HTML comment injection instead.

exclude

Glob patterns for files and folders to skip:

[settings]
exclude = [
  # Common excludes
  "node_modules/**",
  ".git/**",
  "**/dist/**",

  # Draft files
  "**/*.draft.md",
  "**/WIP-*",

  # Specific folders
  "archive/**",
  "vendor/**"
]

Multiple Configs

You can have multiple strayfiles.toml files in different locations. Each config controls indexing for its folder tree.

There are two levels of configuration:

• User-level: ~/.strayfiles/strayfiles.toml — applies globally across all your projects. Use this for personal defaults, global exclusions, or workspaces that span multiple repos.
• Project-level: strayfiles.toml at the root of any folder or repository — applies only to that folder tree.

~/
├── .strayfiles/
│   └── strayfiles.toml      # User-level config (global defaults)
├── notes/
│   └── strayfiles.toml      # Config for personal notes
├── work/
│   └── strayfiles.toml      # Config for work projects
└── dev/
    └── project-a/
        └── strayfiles.toml  # Project-specific config

Settings don’t inherit — each config is independent. Project-level configs do not merge with the user-level config.

Environment Variables

Use environment variables in paths:

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

Note: Environment variable expansion (${VAR}) only works in roots and tracked_directories. Other fields like exclude, extensions, and commit_message do not support variable expansion — values are used as-is.