Configuration

File locations

Path	Purpose
.jetsam/	Per-repo config directory (created by init)
.jetsam/config.yaml	Per-repo configuration
.jetsam/plans/	Temporary plan storage (5-minute TTL, auto-cleaned)
~/.config/jetsam/config.yaml	Global user configuration
.mcp.json	MCP server config (created by init --mcp)
.git-worktree-shared	Paths to symlink into new worktrees

Configuration options

Configuration is loaded from YAML files. Per-repo config (.jetsam/config.yaml) overrides global config (~/.config/jetsam/config.yaml).

# .jetsam/config.yaml

# Platform detection: auto | github | gitlab
platform: auto

# Default merge strategy for finish: squash | merge | rebase
merge_strategy: squash

# Ship default behavior: pr | merge
ship_default: pr

# Create PRs as drafts by default
pr_draft: false

# Branch name prefix for start verb
branch_prefix: ""

# Delete branch after merge in finish
delete_on_merge: true

# Automatically push after save: true | false
auto_push: false

# Worktree usage: auto | always | never
worktree: auto

# Commit message strategy: heuristic | prompt | llm
commit_message: heuristic

Option reference

platform

Platform to use for PR/issue operations. Set to auto (default) to detect from the remote URL. Set explicitly if auto-detection fails.

merge_strategy

Default strategy for finish. One of squash (default), merge, or rebase.

ship_default

What ship does by default. pr creates/updates a PR, merge also merges it.

pr_draft

When true, PRs are created as drafts by default.

branch_prefix

Prefix prepended to branch names created by start. For example, feature/ would create branches like feature/42-fix-parser.

delete_on_merge

Whether finish deletes the branch after merging. Default: true.

auto_push

When true, save automatically pushes after committing. Default: false.

worktree

Worktree mode for start. auto (default) uses branches normally. always creates worktrees by default. never disables worktree creation.

commit_message

Strategy for generating commit messages. heuristic (default) builds a message from the staged changes. prompt asks interactively. llm delegates to an LLM. Reserved — not yet implemented.

Platform support

Jetsam auto-detects your platform from the git remote URL:

• GitHub — uses gh CLI

• GitLab — uses glab CLI

The platform CLI must be installed and authenticated. Jetsam calls these tools as subprocesses and parses their output.

Verifying platform setup

# Check if platform is detected
jetsam status
# Look for "platform" in JSON output:
jetsam --json status | python -m json.tool

Worktree shared paths

When using jetsam start --worktree, you often want certain files or directories shared across all worktrees (.env files, node_modules, virtual environments).

Create a .git-worktree-shared file in the repo root:

# Shared across all worktrees
.env
.env.local
node_modules
.venv

When a new worktree is created via jetsam start --worktree, each listed path is symlinked from the main repo into the worktree. This happens automatically — no extra flags needed.

Rules:

• One path per line

• Lines starting with # are comments

• Blank lines are ignored

• Missing source paths are silently skipped

• Existing files/symlinks in the worktree are not overwritten

JSON output

All commands support JSON output via the global --json flag:

jetsam --json status
jetsam --json save -m "fix"
jetsam --json ship --dry-run

This is useful for scripting and for the MCP server interface.