---
title: "Folder Context Files"
description: "Automatic per-folder CLAUDE.md files that provide directory-level context to Claude"
---
## Overview
claude-recall automatically generates `CLAUDE.md` files in your project folders to provide Claude with directory-level context. These files contain a summary of recent activity in each folder, helping Claude understand what work has been done and where.
<Info>
This feature is **disabled by default**. Enable it via settings if you want automatic folder-level context generation.
</Info>
## How It Works
When you work with Claude Code in a project, claude-recall tracks which files are read and modified. After each observation is saved, it automatically:
1. Identifies unique folder paths from touched files
2. Queries recent observations relevant to each folder
3. Generates a formatted timeline of activity
4. Writes it to `CLAUDE.md` in that folder (inside `<claude-recall-context>` tags)
### What Gets Generated
Each folder's `CLAUDE.md` contains a "Recent Activity" section showing:
- Observation IDs for reference
- Timestamps of when work occurred
- Type indicators (bug fixes, features, discoveries, etc.)
- Brief titles describing the work
- Estimated token counts
```markdown
<claude-recall-context>
# Recent Activity
<!-- This section is auto-generated by claude-recall. Edit content outside the tags. -->
### Jan 4, 2026
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #1234 | 4:30 PM | 🔵 | Implemented user authentication | ~250 |
| #1235 | " | 🔴 | Fixed login redirect bug | ~180 |
</claude-recall-context>
```
### User Content Preservation
The auto-generated content is wrapped in `<claude-recall-context>` tags. **Any content you write outside these tags is preserved** when the file is regenerated. This means you can:
- Add your own documentation above or below the generated section
- Write folder-specific instructions for Claude
- Include architectural notes or conventions
```markdown
# Authentication Module
This folder contains all authentication-related code.
Follow the established patterns for new auth providers.
<claude-recall-context>
... auto-generated content ...
</claude-recall-context>
## Manual Notes
- OAuth providers go in /providers/
- Session handling uses Redis
```
### Project Root Exclusion
The **project root** (folders containing a `.git` directory) is **excluded** from auto-generation. This is intentional:
- Root `CLAUDE.md` files typically contain project-wide instructions you've written manually
- Auto-generating at the root could overwrite important project documentation
- Subfolders are where folder-level context is most useful
<Note>
Git submodules (which have a `.git` *file* instead of directory) are correctly detected and **not** excluded, so they receive auto-generated context.
</Note>
## Configuration
### Enabling the Feature
To enable folder CLAUDE.md generation, edit your settings file:
**1. Open `~/.claude-recall/settings.json`**
**2. Add or update this setting:**
```json
{
"CLAUDE_RECALL_FOLDER_CLAUDEMD_ENABLED": "true"
}
```
**3. Save the file** - changes take effect immediately (no restart needed)
| Value | Behavior |
|-------|----------|
| `"false"` (default) | Folder CLAUDE.md generation disabled |
| `"true"` | Auto-generate folder CLAUDE.md files |
<Tip>
If the settings file doesn't exist, create it with just the settings you want to change. claude-recall will use defaults for any missing settings.
</Tip>
## Cleanup Mode
The regenerate script includes a `--clean` mode for removing auto-generated content:
```bash
# Preview what would be cleaned (dry run)
bun scripts/regenerate-claude-md.ts --clean --dry-run
# Actually clean files
bun scripts/regenerate-claude-md.ts --clean
```
**What cleanup does:**
1. Finds all `CLAUDE.md` files recursively
2. Strips `<claude-recall-context>...</claude-recall-context>` sections
3. **Deletes** files that become empty after stripping
4. **Preserves** files that have user content outside the tags
This is useful for:
- Preparing a branch for PR (removing generated files)
- Resetting folder context to start fresh
- Removing context before sharing code
## Git Integration
### Should You Commit These Files?
This is **your choice** based on your workflow. Here are the trade-offs:
<Tabs>
<Tab title="Commit Them">
**Pros:**
- Team members see folder-level context and recent activity
- New contributors can understand what happened where
- Code reviewers get additional context about changes
- Historical record of work patterns in the repo
**Cons:**
- Adds files to your repository
- Files change frequently during development
- May create noise in diffs and commit history
- Different team members may generate different content
</Tab>
<Tab title="Gitignore Them">
**Pros:**
- Clean repository without generated files
- No commit noise from auto-generated content
- Each developer has their own local context
- Simpler git history
**Cons:**
- Team doesn't share folder context
- Context is lost when switching machines
- New team members don't benefit from existing context
</Tab>
</Tabs>
### Gitignore Pattern
To exclude folder CLAUDE.md files from git:
```gitignore
# Ignore auto-generated folder context files
**/CLAUDE.md
# But keep the root CLAUDE.md if you want
!CLAUDE.md
```
Or to ignore all CLAUDE.md files everywhere:
```gitignore
**/CLAUDE.md
```
### Recommended Workflows
**For Solo Developers:**
- Keep them local (gitignore) for personal context
- Or commit them if you work across multiple machines
**For Teams:**
- Discuss with your team which approach works best
- Consider committing them if onboarding is frequent
- Use `--clean` before PRs if you prefer clean diffs
**Before Merging PRs:**
```bash
# Clean up generated files before merge
bun scripts/regenerate-claude-md.ts --clean
git add -A
git commit -m "chore: clean up generated CLAUDE.md files"
```
## Regenerating Context
To manually regenerate all folder CLAUDE.md files from the database:
```bash
# Preview what would be regenerated
bun scripts/regenerate-claude-md.ts --dry-run
# Regenerate all folders
bun scripts/regenerate-claude-md.ts
# Regenerate for a specific project only
bun scripts/regenerate-claude-md.ts --project=my-project
```
This is useful after:
- Importing observations from another machine
- Database recovery
- Wanting to refresh all folder context
## Worktree Support
**New in v9.0**: claude-recall now supports git worktrees with unified context.
When you're working in a git worktree, context is automatically gathered from both:
- The parent repository (where the worktree was created)
- The worktree directory itself
This means observations about shared code are visible regardless of which worktree you're in, giving you a complete picture of recent activity across all related directories.
### How It Works
1. When generating context, claude-recall detects if your project is a worktree
2. It identifies the parent repository automatically
3. Timeline queries include both locations
4. Results are interleaved chronologically
<Note>
No configuration needed - worktree detection is automatic. If you're not using worktrees, this feature has no effect.
</Note>
## Technical Details
### File Format
Generated content uses a consistent markdown table format:
| Column | Description |
|--------|-------------|
| ID | Observation ID (e.g., `#1234`) or session ID (`#S123`) |
| Time | 12-hour format with AM/PM, ditto marks (`"`) for repeated times |
| T | Type emoji indicator |
| Title | Brief description of the observation |
| Read | Estimated token count (e.g., `~250`) |
### Type Indicators
| Emoji | Type |
|-------|------|
| 🔴 | Bug fix |
| 🟣 | Feature |
| 🔄 | Refactor |
| ✅ | Change |
| 🔵 | Discovery |
| ⚖️ | Decision |
| 🎯 | Session |
| 💬 | Prompt |
### Atomic Writes
Files are written atomically using a temp file + rename pattern. This prevents partial writes if the process is interrupted.
### Performance
- Updates happen asynchronously (fire-and-forget)
- Failures are logged but don't block the main workflow
- Only folders with actual file activity are updated
- Deduplication prevents redundant updates for the same folder
