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"
]

# 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"

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
]

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.

~/
├── 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.

Environment Variables

Use environment variables in paths:

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