jetsam

Git workflow accelerator for humans and agents.

Jetsam wraps common multi-step git workflows into single, plannable commands. Every action generates a preview plan before executing, making it safe for interactive use and ideal for AI agent integration via MCP.

[Documentation](https://jetsam-mcp.readthedocs.io) | [PyPI](https://pypi.org/project/jetsam-mcp/) | [GitHub](https://github.com/teaguesterling/jetsam)

Installation

pip install jetsam-mcp
# or
uv pip install jetsam-mcp

Quick start

# Initialize in a repo
jetsam init

# Check status
jetsam status

# Stage + commit
jetsam save -m "fix parser bug"

# Full pipeline: stage → commit → push → PR
jetsam ship -m "add dark mode"

# Tag and release
jetsam release v0.1.0 --title "First release"

Every command shows a plan and asks for confirmation before executing. Use --dry-run to preview without executing, or --execute to skip the prompt.

Verb reference

Common flags

All workflow verbs (save, sync, ship, switch, start, finish, tidy, release) support:

• --dry-run — show plan without executing
• --execute — execute without prompting
• --json (global) — output as JSON

Key verb options

save [-m MESSAGE] [--include GLOB] [--exclude GLOB] [FILES...]

ship [-m MESSAGE] [--to BRANCH] [--no-pr] [--merge] [--include GLOB] [--exclude GLOB] [FILES...]

sync [--strategy rebase|merge]

switch BRANCH [-c/--create]

start TARGET [-w/--worktree] [--base BRANCH] [--prefix PREFIX]

finish [--strategy squash|merge|rebase] [--no-delete]

release TAG [--title TITLE] [--notes NOTES] [--draft]

MCP integration

Jetsam includes a built-in MCP server for agent integration:

# Full agent setup: MCP config + routing instructions + warning hooks
jetsam init --mcp --agents claude --hooks claude

# Or just the MCP server config
jetsam init --mcp

This creates .mcp.json for automatic MCP discovery, CLAUDE.md with a routing table that teaches agents to use jetsam tools instead of raw git/gh, and warning hooks that alert agents when they bypass jetsam.

The MCP tools mirror CLI verbs with a plan → confirm flow:

1. Call a workflow tool (e.g. save, ship, release) — returns a plan
2. Optionally call modify_plan to adjust the plan
3. Call confirm to execute, or cancel to discard

Additional MCP tools for PR interaction: pr_comment, pr_review, pr_comments, issue_close.

Shell aliases

Install short aliases for common operations:

jetsam init --aliases

This adds the following aliases to your shell config:

Worktree support

Jetsam supports git worktrees for parallel development:

# Start work in a new worktree
jetsam start my-feature --worktree

# Finish and clean up the worktree
jetsam finish

Shared paths

Create a .git-worktree-shared file in the repo root to automatically symlink paths into new worktrees (one path per line):

.env
node_modules
.venv

Lines starting with # are ignored.

Configuration

Jetsam stores its configuration in .jetsam/ at the repo root:

Platform support

Jetsam auto-detects GitHub and GitLab from remote URLs:

• GitHub — uses gh CLI
• GitLab — uses glab CLI

Git pass-through: any unrecognized command is forwarded to git, so jetsam log --oneline works exactly like git log --oneline.

License

MIT