File & directory layout

A reference for what Friday writes, where, and what's safe to delete. Useful when you're debugging odd behavior, backing up state before a clean reinstall, or wiping the slate to start fresh.

Friday's state lives in three places:

• Per user, under ~/.friday/. Settings, session state, checkpoints, and snapshots. Override the location with the FRIDAY_HOME env var. See Environment variables.
• Per user, outside ~/.friday/: cloned plugin marketplaces, under ~/.agents/plugins/. FRIDAY_HOME does not move these.
• Per project, in the repo itself. Project rules (agents.md), and discovery roots for skills, commands, and subagents (.agents/, .claude/).

Sibling worktree directories created by friday --wt live next to the repo, not under ~/.friday/.

Per-user state under ~/.friday/

~/.friday/
├── .user_preferences.yaml                     # global settings (hidden file, YAML)
├── checkpoints/<repo>/                        # resumable session state
│   ├── <timestamp>.json                       # the conversation, plus the label you see in the picker
│   ├── <timestamp>_tasks/                     # tasks saved with that checkpoint
│   └── <timestamp>_threads/<thread_id>.json   # one file per worker thread that had messages
├── workspaces/<session_id>/                   # live session state
│   ├── threads/<thread_id>/worktree/          # per-thread worktree (GIT mode)
│   ├── tasks/                                 # session task store (one *.json per task)
│   └── merge_queue.json                       # persisted merge queue
└── snapshots/<repo>/                          # debug artifacts
    ├── snapshot_<timestamp>.json              # written by /snapshot
    └── sessions_snapshots/<session_id>/       # written automatically, 50 sessions kept

~/.agents/
└── plugins/
    ├── known_marketplaces.json                # registry of installed marketplaces
    └── marketplaces/<name>/                   # cloned plugin marketplaces

Path	What it is	Touch with care	Safe to delete
~/.friday/.user_preferences.yaml	The global settings file (YAML, hidden). Edited by /settings or by hand. Holds working style, agent model, approval mode, MCP instances, and per-project overrides. API keys are NOT stored here; the proxy uses gh auth token.	Yes, you'll lose your preferences.	Only if you want to reset all settings.
~/.friday/checkpoints/<repo>/	Resumable session state per repo: one <timestamp>.json per checkpoint, with sibling _tasks/ and _threads/ directories. /load-checkpoint reads from here and lists only the checkpoints saved on your current branch. Capped at 20 newest per repo.	Older checkpoints rotate out automatically.	Yes. You lose the ability to resume past sessions. Live work is unaffected.
~/.friday/workspaces/<session_id>/	Live state for a running session. Removed at clean shutdown. Stale dirs older than 30 days are pruned at startup.	Don't delete while a session is running.	Yes, when no Friday process is using the session.
~/.friday/workspaces/<session_id>/threads/<thread_id>/worktree/	Per-thread git worktree in GIT mode. Each worker edits here on branch friday/thread/<thread-id>. Cleaned up after merge or session end.	Don't touch while the thread is RUNNING.	Yes, but use git worktree remove so git's metadata stays consistent. See Worktrees.
~/.friday/workspaces/<session_id>/merge_queue.json	The persisted FIFO merge queue. A restart mid-merge reads this back.	Don't edit by hand mid-session.	Yes, when the session is not running. You lose any pending merges.
~/.friday/workspaces/<session_id>/tasks/	Session task store. One <task_id>.json file per task in the current session. Friday writes here as tasks are created and updated.	Don't touch while the session is running.	Yes, when the session is not running.
~/.friday/snapshots/<repo>/	Debug snapshots. Friday writes one before and after compression and at session end, under sessions_snapshots/<session_id>/; the 50 newest sessions are kept. /snapshot writes a loose snapshot_<timestamp>.json alongside them, and those stay until you delete them. For engineering investigation, not for resuming work.	No.	Yes, any time.
~/.agents/plugins/marketplaces/<name>/	Cloned plugin marketplaces managed via /plugin-marketplace. The registry of known marketplaces lives next door at ~/.agents/plugins/known_marketplaces.json.	Re-cloning is cheap.	Yes. Reinstall plugins from /plugin-marketplace after.

Per-project files in the repo

These files are read from your project root (and a few user-global fallbacks). Friday never writes here on its own. You commit what you want shared.

<project-root>/
├── agents.md                                  # project rules (current convention)
├── .fridayrules                               # legacy fallback for project rules
├── .agents/                                   # discovery root (skills/commands/agents/plugins)
│   ├── skills/
│   ├── commands/
│   ├── agents/
│   └── plugins/
└── .claude/                                   # Claude-compatible discovery root (same kinds)
    ├── skills/
    ├── commands/
    ├── agents/
    └── plugins/

Path	What it is
<project>/agents.md	Project rules, inlined into every Friday session's system prompt in this repo. Plays the role CLAUDE.md plays in Claude Code, but Friday only reads files named agents.md (or .fridayrules as a fallback); it does NOT read CLAUDE.md. Generated or updated with /agentsmd. See agents.md & project rules.
<project>/.fridayrules	Legacy fallback for project rules. Friday reads this only when agents.md is absent. New projects should use agents.md.
<project>/.agents/	Project-level discovery root for skills, commands, subagents, and plugins. Friday does NOT read agents.md from inside this directory; project rules live at the repo root.
<project>/.claude/	Claude-compatible discovery root. Friday reads skills/, commands/, agents/, and plugins/ from here as a fallback to .agents/, so projects already configured for Claude Code keep working.

Hook config is a fifth kind under the same discovery roots: <project>/.agents/hooks/hooks.json for one repo, ~/.agents/hooks/hooks.json for every project, with .claude/hooks/hooks.json read as a fallback in both. Unlike skills and commands, hook files do not override each other — every one that exists contributes. Friday asks before running a project's hooks the first time. See Hooks.

User-global fallbacks for skills, commands, and subagents live at ~/.agents/ and ~/.claude/. Resolution is first-found-wins: project .agents/, then project .claude/, then ~/.agents/, then ~/.claude/, then plugins.

User-global project rules live at ~/.agents/agents.md. Friday inlines them on every session in addition to the project's own agents.md. There is no Claude-style fallback: Friday does NOT read ~/.claude/CLAUDE.md.

Per-thread worktrees

Inside a session, every thread in GIT mode runs in its own git worktree on branch friday/thread/<thread-id> at ~/.friday/workspaces/<session_id>/threads/<thread_id>/worktree/. Threads can't see each other's changes or your uncommitted work. The merge queue cherry-picks finished thread branches back onto your current branch. See Worktrees for the full mechanism.

You don't manage these directly. They're created when a thread spawns and removed when the thread merges or the session exits cleanly.

--wt worktrees

friday --wt creates a sibling worktree next to your repo:

~/projects/
├── my-app/                                    # your original checkout
└── my-app.worktree.20241024-143000/           # the --wt worktree (auto-removed at exit)

This is a different mechanism from per-thread worktrees. The --wt worktree is the working directory for the whole session; per-thread worktrees nest inside it. See Parallelize work with worktrees for the recipe and Worktrees for the flag reference.

Uncommitted edits at exit are auto-committed with WIP: auto-commit from worktree cleanup and the worktree directory is removed. The branch stays in your git history.

Cleanup: getting back to a clean slate

• Wipe everything Friday-related. rm -rf ~/.friday/ ~/.agents/plugins/. You lose settings, checkpoints, snapshots, the merge queue of any in-flight session, and cloned plugin marketplaces. Project files in your repos are untouched. (API keys are not stored anywhere by Friday; auth is via gh auth token.)
• Keep settings, drop state. Remove ~/.friday/workspaces/, ~/.friday/snapshots/, and ~/.friday/checkpoints/. Keep .user_preferences.yaml and ~/.agents/plugins/.
• Drop just the debug artifacts. Remove ~/.friday/snapshots/. Safe at any time.
• Drop one stale session. Remove ~/.friday/workspaces/<session_id>/ after confirming no Friday process is attached to it. Stale dirs older than 30 days clean up automatically at startup.
• Reset plugins. Remove ~/.agents/plugins/ and re-add from /plugin-marketplace.
• Uninstall the binary. brew uninstall friday. State under ~/.friday/ stays put unless you also remove it manually. See Installation.

Read next

• Environment variables: FRIDAY_HOME and the rest.
• agents.md & project rules: what to put in agents.md.
• Worktrees: the per-thread and --wt worktree mechanisms.
• Settings: what's in .user_preferences.yaml and how to edit it.
• Installation: install and uninstall.