claustre claustre

Configuration

Claustre uses a layered configuration system. Settings live in ~/.claustre/ (global) and <repo>/.claustre/ (per-project). When a session launches, claustre merges global config, project config, and the repository's own CLAUDE.md into the worktree so Claude has full context.

Directory Structure

Global configuration lives in your home directory under ~/.claustre/: 

~/.claustre/
  config.toml          # App settings
  claude.md            # Global CLAUDE.md (merged into all worktrees)
  hooks/               # Global hooks (copied to worktrees)
  claustre.db          # SQLite database
  worktrees/           # Session worktrees
  tmp/                 # Session progress files

Project-specific configuration lives in a .claustre/ directory at the root of each registered repository: 

<your-repo>/.claustre/
  claude.md            # Project-specific CLAUDE.md additions
  hooks/               # Project hooks (override global by filename)

config.toml

The main configuration file is ~/.claustre/config.toml. Below is a full reference with all available options: 

[notifications]
enabled = true          # Enable notifications on task completion
command = "say"         # Notification command (default: macOS "say")
template = "completed {task}"  # Message template ({task} = task title)
voice = "Samantha"      # macOS voice (optional)
rate = 200              # Words per minute (optional)

[layout]
# Starting pane arrangement for session tabs.
# Each leaf is "shell" or "claude" (exactly one "claude" required).
# When absent, defaults to horizontal 50/50 shell | claude.
type = "split"
direction = "horizontal"
ratio = 50
first = "shell"
second = "claude"

Notifications

The [notifications] section controls how you get notified when tasks complete. On macOS, the default uses the say command for spoken notifications.

Key Type Default Description
enabled bool true Whether notifications fire on task completion
command string "say" The shell command to run for notifications
template string "completed {task}" Message template. {task} is replaced with the task title
voice string - macOS voice name (optional, passed to say)
rate int - Words per minute (optional, passed to say)

The notification is fire-and-forget: the command is spawned without waiting for it to finish. If it fails, a warning is logged but nothing is surfaced to the user.

Layout

The [layout] section defines the starting pane arrangement for session tabs. The layout is a tree structure that supports nested splits.

Key Type Description
type string "split", "shell", or "claude". Splits contain two children; the others are leaf panes
direction string "horizontal" (side-by-side) or "vertical" (stacked). Only for split nodes
ratio int Percentage of space given to the first child (0-100). Only for split nodes
first string or table Left/top child. Can be a leaf string ("shell", "claude") or a nested split table
second string or table Right/bottom child. Same format as first

Every layout must contain exactly one "claude" leaf. You can have as many "shell" leaves as you want. When the [layout] section is absent, claustre defaults to a horizontal 50/50 split with a shell on the left and Claude on the right.

CLAUDE.md Merge Order

When a session worktree is created, claustre merges CLAUDE.md content from multiple sources in this order:

  1. ~/.claustre/claude.md — global instructions that apply to every session across all projects
  2. <repo>/.claustre/claude.md — project-specific additions layered on top of the global config
  3. <repo>/CLAUDE.md — the repository's own CLAUDE.md, included last

This means global instructions (coding standards, preferred tools, general conventions) apply everywhere. Project-specific additions (framework details, architecture notes, repo-specific patterns) are layered on. The repository's own CLAUDE.md is included last so it can reference or build on the earlier context.

Hooks

Claustre uses Claude Code hooks to keep session state in sync. Hook scripts are inherited from global and project-level directories:

  • Global hooks from ~/.claustre/hooks/ are copied into the worktree first
  • Project hooks from <repo>/.claustre/hooks/ override global hooks with the same filename
  • All hooks are made executable after copying
Important: Hooks are registered in .claude/settings.local.json, not .claude/settings.json. This is because Claude Code only executes hooks from ~/.claude/settings.json (global) and .claude/settings.local.json (project-local). Hooks defined in .claude/settings.json at the project level are silently ignored. Claustre handles this automatically when setting up a session.

Claude Code snapshots hook configuration at session startup. Changes to settings files after a session launches will not take effect until the next Claude Code session.

Layout Configuration

The default layout is a horizontal 50/50 split with a shell on the left and Claude on the right. You can customize this with nested splits to create more complex arrangements.

For example, this configuration creates two shells stacked vertically on the left and Claude on the right: 

[layout]
type = "split"
direction = "horizontal"
ratio = 50

[layout.first]
type = "split"
direction = "vertical"
ratio = 50
first = "shell"
second = "shell"

[layout.second]
type = "claude"

This produces a layout like: 

+------------------+------------------+
|                  |                  |
|     shell        |                  |
|                  |                  |
+------------------+     claude      |
|                  |                  |
|     shell        |                  |
|                  |                  |
+------------------+------------------+

You can also dynamically split panes at runtime using keybindings in a session tab:

Key Action
Ctrl+B Split right (new shell beside the focused pane)
Ctrl+N Split down (new shell below the focused pane)
Ctrl+W Close the focused pane (cannot close the Claude pane or the last pane)
Ctrl+H Focus the previous pane
Ctrl+L Focus the next pane