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:

# Launch Claude sessions with --remote (for remote development).
# Default: false
remote_enabled = false

# Check GitHub for newer versions and auto-update before opening the TUI.
# Default: false
auto_update = false

[notifications]
enabled = true          # Enable voice/sound notifications on task completion
system = true           # Enable macOS system banner notifications
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)

[review_loop]
poll_interval_secs = 120  # Seconds between PR comment checks
# prompt = "Custom prompt"  # Replaces the built-in adversarial review prompt

[sync]
# Automatically run `claustre sync push` when tasks change.
# Requires `claustre sync init` to have been run first.
# Default: false
auto_push = false

[rtk]
# RTK (https://github.com/rtk-ai/rtk) integration.
# When enabled, `claustre configure` checks that `rtk` is installed.
# Default: true
enabled = true

[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"

[claude]
model = "claude-opus-4-6"    # Model passed to `claude --model`
effort = "max"               # Effort passed to `claude --effort` (min/low/medium/high/max)

[theme]
# Custom colours. All fields optional; missing fields keep defaults.
# Supports named colours ("cyan", "red") and "rgb(R,G,B)" syntax.
border_focused = "cyan"
status_working = "green"
status_error = "red"

[permissions]
# Recommended Claude Code permissions for `claustre configure`.
# The wizard compares these against ~/.claude/settings.json and offers to apply missing entries.
allow = [
  "Bash", "Glob(*)", "Grep(*)", "Read(*)", "Edit(*)",
  "MultiEdit(*)", "Write(*)", "NotebookEdit(*)", "TodoWrite(*)", "BashOutput(*)"
]
deny = [
  "Bash(git push*main*)",
  "Bash(git push --force*)",
  "Bash(git push*--force*)"
]
ask = ["Bash(rm:*)"]

Global Settings

Key	Type	Default	Description
`remote_enabled`	bool	`false`	Launch Claude sessions with `--remote` (for remote development environments)
`auto_update`	bool	`false`	Check GitHub releases for newer versions and auto-update before opening the TUI. Downloads the new binary, runs a smoke test (`health-check`), backs up the current binary to `~/.claustre/bin/claustre.prev`, and replaces it. Use `claustre rollback` to revert if needed.

Claude

The [claude] section controls which model and reasoning effort level are passed to claude via --model and --effort flags. These apply globally to all session types (supervised, autonomous, exploration, and review loop).

Key	Type	Default	Description
`model`	string	`"claude-opus-4-6"`	Model identifier passed to `claude --model`
`effort`	string	`"max"`	Reasoning effort level passed to `claude --effort`. Valid values: `"min"`, `"low"`, `"medium"`, `"high"`, `"max"`

Theme

The [theme] section lets you override the default TUI colour palette. All fields are optional — any field you omit keeps its default value. Colours can be named ("cyan", "dark_gray") or "rgb(R,G,B)".

Category	Keys
Borders	`border_focused`, `border_unfocused`
Text	`text_primary`, `text_secondary`, `text_accent`
Task status	`status_draft`, `status_pending`, `status_working`, `status_interrupted`, `status_in_review`, `status_conflict`, `status_ci_failed`, `status_ci_running`, `status_ci_passed`, `status_done`, `status_error`, `status_paused`, `status_waiting`
Accents	`accent_primary`, `accent_secondary`, `accent_tertiary`
Toasts	`toast_info`, `toast_success`, `toast_error`
Usage bars	`usage_low`, `usage_medium`, `usage_high`
Forms	`form_border_task`, `form_border_project`, `form_highlight`, `form_dim`
Tabs	`tab_active`, `tab_inactive`
Misc	`selection_indicator`, `pr_link`, `spinner`, `rate_limit_warning`

Notifications

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

Key	Type	Default	Description
`enabled`	bool	`true`	Whether voice/sound notifications fire on task completion
`system`	bool	`true`	Whether macOS system banner notifications are shown 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.
 Review Loop
 
The [review_loop] section controls the automatic review comment
    handler. When a task has the review loop enabled and transitions to
in_review, claustre spawns a process that polls PR comments and
    implements accepted feedback. See Tasks —
    Review Loop for details on the feature.
    Key  Type  Default  Description  
 
   poll_interval_secs  int  120  Seconds between PR comment checks  
  prompt  string  (built-in)  
Custom prompt for Claude when processing review comments. When
          omitted, uses the built-in prompt that evaluates comments
          adversarially, accepting bug fixes and rejecting nitpicks.
 
 
 
 Sync
 
The [sync] section controls automatic state synchronization. When
    enabled, claustre automatically pushes state to the sync repo whenever tasks are
    created, updated, or change status. This covers changes made via hooks (Stop,
    TaskCompleted, UserPromptSubmit), the CLI (claustre add-task), and
    the TUI (create, edit, delete, mark done). The push runs as a fire-and-forget
    background process, so it never blocks hooks or the TUI.
 
Requires claustre sync init to have been run first. If the sync
    repo isn't initialized, auto-push is silently skipped.
    Key  Type  Default  Description  
 
   auto_push  bool  false  
Automatically run claustre sync push when tasks change.
          Spawned as a background process so it never blocks the caller.
 
 
 
 RTK
 
The [rtk] section controls RTK integration. RTK provides
    enhanced context for Claude Code sessions via a Bash hook system. When
    enabled, claustre configure checks that the rtk
CLI is installed and runs rtk init --global to register
    RTK's hooks in ~/.claude/settings.json. The TUI shows a
    warning if RTK is not installed.
    Key  Type  Default  Description  
 
   enabled  bool  true  
Whether RTK integration is enabled. When true,
claustre configure verifies that rtk is
          installed and prompts the user to install it if missing.
 
 
 
 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.
 Permissions
 
The [permissions] section defines the recommended Claude Code
    permissions that claustre configure checks against your
~/.claude/settings.json. The wizard compares these lists and
    offers to apply any missing entries.
    Key  Type  Description  
 
   allow  array  
Permissions Claude can execute without asking. Default includes
Bash, Glob(*), Grep(*),
Read(*), Edit(*), MultiEdit(*),
Write(*), NotebookEdit(*),
TodoWrite(*), BashOutput(*).
 
  deny  array  
Always-denied permissions. Default blocks force pushes and pushes to
          main/master.
 
  ask  array  
Permissions requiring user confirmation. Default:
Bash(rm:*).
 
 
 
 
Customize these if your workflow needs different defaults. For example, to
    allow Claude to run rm without asking, move it from
ask to allow.
 CLAUDE.md Merge Order
 
When a session worktree is created, claustre merges CLAUDE.md content from
    multiple sources in this order:
   ~/.claustre/claude.md — global instructions
      that apply to every session across all projects
  <repo>/.claustre/claude.md —
      project-specific additions layered on top of the global config
  <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+R  Split right (new shell beside the focused pane)  
  Ctrl+B  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

Key	Type	Default	Description
`poll_interval_secs`	int	`120`	Seconds between PR comment checks
`prompt`	string	(built-in)	Custom prompt for Claude when processing review comments. When omitted, uses the built-in prompt that evaluates comments adversarially, accepting bug fixes and rejecting nitpicks.

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`

Key	Type	Description
`allow`	array	Permissions Claude can execute without asking. Default includes `Bash`, `Glob()`, `Grep()`, `Read()`, `Edit()`, `MultiEdit()`, `Write()`, `NotebookEdit()`, `TodoWrite()`, `BashOutput(*)`.
`deny`	array	Always-denied permissions. Default blocks force pushes and pushes to main/master.
`ask`	array	Permissions requiring user confirmation. Default: `Bash(rm:*)`.

Key	Action
`Ctrl+R`	Split right (new shell beside the focused pane)
`Ctrl+B`	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