Local Folders

Bookmark folders on your machine for quick access and documentation

Local folders are bookmarks to directories on your machine. They provide a named reference that appears in your sources list, with optional documentation via guide.md.

No special setup required. Local folders use the same Read, Write, Glob, and Grep tools that work on any path. The value is organization and documentation.

When to Use Local Folders

Need	Solution
Work in a single project directory	Use Working Directory
Bookmark multiple folders	Use Local Folders
Document folder contents and conventions	Use Local Folders with guide.md

Configuration

Create a source folder with a config.json:

{
  "type": "local",
  "name": "My Notes",
  "slug": "my-notes",
  "enabled": true,
  "provider": "local",
  "local": {
    "path": "/Users/me/Documents/Notes"
  }
}

Fields

Field	Description
type	Must be "local"
name	Display name in sources list
slug	URL-safe identifier (used as folder name)
enabled	Whether the source is active
provider	Service identifier, use "local"
local.path	Absolute path to the folder

Optional: Format Hint

You can add a format hint to help your agent understand the folder contents:

{
  "type": "local",
  "name": "Obsidian Vault",
  "slug": "my-vault",
  "provider": "obsidian",
  "local": {
    "path": "/Users/me/Documents/ObsidianVault",
    "format": "obsidian"
  }
}

Adding a Local Folder

The easiest way is to ask your agent:

“Add my Desktop folder as a source”

Or create manually:

1. Create the source folder:

   ~/.craft-agent/workspaces/{workspace-id}/sources/my-folder/
   

2. Add config.json with the configuration above

3. Optionally add guide.md with context about the folder

guide.md Example

The guide helps your agent understand what’s in the folder and how to use it:

# Desktop

Temporary files and downloads. Check here for recent screenshots and exports.

## Contents
- Screenshots from CMD+Shift+4
- Downloaded PDFs and documents
- Temporary exports from apps

## Conventions
- Screenshots go in /Screenshots subfolder
- Delete files older than 1 week
- Don't commit anything from here to git

Explore Mode Permissions

By default, local folders work in Explore mode with the standard read-only bash commands (ls, cat, head, tail, etc.).

To customize, add permissions.json:

{
  "allowedBashPatterns": [
    { "pattern": "^ls\\s", "comment": "List contents" },
    { "pattern": "^tree\\s", "comment": "Show directory tree" }
  ]
}

Local Folders vs Working Directory

Choose the right approach for your use case:

Working Directory

Your active project. Set once per session. Full tool access for coding, building, and testing.

Use for: The project you’re currently working on

Local Folders

Bookmarks to folders you reference occasionally. Named sources with documentation.

Use for: Notes, downloads, reference materials

Rule of thumb: Use Working Directory for coding. Use Local Folders for everything else.