Managing AI Context Files

The Killer Use Case

If you use AI coding assistants, you probably have context files scattered across dozens of repositories - CLAUDE.md, AGENTS.md, README.md, and more. Strayfiles brings them all together.

The Problem

~/projects/
├── app-frontend/CLAUDE.md
├── app-backend/CLAUDE.md
├── shared-libs/CLAUDE.md
├── infra/CLAUDE.md
├── docs/CLAUDE.md
└── ... 20 more repos

Each repo has its own context file. Finding, editing, and keeping them consistent is painful.

The Solution

Create a workspace that auto-collects all your AI context files:

# ~/.strayfiles/strayfiles.toml

version = 1

[settings]
roots = ["~/projects"]
exclude = ["node_modules/**", ".git/**", "target/**"]

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

What You Get

1. Single view of all context files - See every CLAUDE.md in one place
2. No file moving - Files stay in their repos
3. Quick edits - Update any file from Strayfiles
4. Cross-device sync - Same view on all machines
5. Search across all - Find that prompt you wrote months ago
6. Aliases for disambiguation - Set display names like “Frontend CLAUDE” to tell them apart

Setting Up

Step 1: Create config

Create ~/.strayfiles/strayfiles.toml with the workspace above.

Step 2: Point to your projects

Add your projects directory to roots:

[settings]
roots = ["~/projects", "~/work", "~/oss"]

Step 3: Launch Strayfiles

Open Strayfiles and select the “claude-code” workspace. All matching files appear.

Patterns to Include

Common AI context file patterns:

[workspaces.ai-context]
include = [
  "**/CLAUDE.md",           # Claude Code
  "**/.cursorrules",        # Cursor
  "**/AGENTS.md",           # Multi-agent setups
  "**/cursor.rules",        # Cursor (alt name)
  "**/AI_CONTEXT.md",       # Generic
  "**/llm-context/**/*.md"  # Context directories
]

Organizing by Project Type

Create multiple workspaces for different contexts:

[workspaces.frontend-context]
description = "Frontend project AI context"
include = ["**/frontend/**/CLAUDE.md", "**/web/**/CLAUDE.md"]

[workspaces.backend-context]
description = "Backend project AI context"
include = ["**/backend/**/CLAUDE.md", "**/api/**/CLAUDE.md"]

[workspaces.infra-context]
description = "Infrastructure AI context"
include = ["**/infra/**/CLAUDE.md", "**/deploy/**/CLAUDE.md"]

Syncing Across Machines

Your AI context files are in Git repos, so they sync via Git. But your Strayfiles config can sync via:

Option 1: Git (recommended) Keep ~/.strayfiles/ as a Git repo.

Option 2: Symlink Symlink ~/.strayfiles/ to a synced folder.

Option 3: Stray Cloud Use Strayfiles Pro for encrypted Stray Cloud sync.

Best Practices

Keep files in repos: Don’t move CLAUDE.md files out of their repos. Strayfiles indexes them in place.

Use consistent patterns: Stick to CLAUDE.md (or your preferred name) across all repos for easy globbing.

Version your context files: Since they’re in Git repos, you get version history automatically.

Update via Strayfiles: Edit in Strayfiles, then commit/push in your terminal or Git client.

Example Workflow

1. Open Strayfiles
2. Select “claude-code” workspace
3. See all your AI context files
4. Edit the one you need
5. Changes saved to the original file in your repo
6. Commit and push when ready

Tips

Use aliases to distinguish files: When you have many files with the same name, set aliases to tell them apart:

---
strayfiles:
  enabled: true
  alias: "Frontend App CLAUDE"
---

Strayfiles displays: Frontend App CLAUDE (CLAUDE.md) with the original filename dimmed.

Use HTML comments to avoid visible metadata: If you don’t want frontmatter showing in your CLAUDE.md files, use HTML comments instead:

<!-- strayfiles: {"enabled": true, "alias": "Frontend App CLAUDE"} -->

# Project Context
...

The comment is invisible when rendered, keeping your context files clean.

Quick navigation: Use search within the workspace to find specific context files.

Preview content: See file contents without leaving the file list.

Bulk updates: When you change a pattern (like adding a new section to all context files), you can see all affected files in one view.

Track new repos: When you create a new project with a CLAUDE.md, it automatically appears in your workspace.

---

Mirror Your Context Everywhere

Instead of maintaining separate AI context files for each project, use file mirrors to sync from a single source.

Best practice: Create a dedicated source file like context.md (not CLAUDE.md itself) and mirror it to all your projects. The strayfiles metadata is automatically stripped from targets, keeping them clean.

~/dotfiles/context.md (source with frontmatter)
         ↓ mirrors to (clean, no metadata)
~/project-a/CLAUDE.md
~/project-a/AGENTS.md
~/project-b/.cursor/rules
~/project-c/.github/copilot-instructions.md

Setup:

1. Create ~/dotfiles/context.md with your AI instructions
2. Add strayfiles frontmatter to track it
3. Open Settings → Mirrors → Manage Mirrors
4. Add targets for each project
5. Press S to sync all

Now when you update your context, one sync updates every project with clean, metadata-free files.

See File Mirrors for full documentation.