Getting started¶

Installation¶

Install from PyPI:

pip install jetsam

Or with uv:

uv pip install jetsam

Requirements¶

Python 3.10+
git
gh CLI (for GitHub operations) or glab CLI (for GitLab)

Initialize¶

Run init in any git repository:

cd your-repo
jetsam init

This creates the .jetsam/ directory for plan storage and detects your platform (GitHub or GitLab) from the remote URL.

MCP server setup¶

To use jetsam with Claude Code or other MCP-aware agents:

jetsam init --mcp

This adds the jetsam MCP server entry to .mcp.json in your repo root. If the file already exists, jetsam merges its entry without overwriting other servers.

The generated config:

{
  "mcpServers": {
    "jetsam": {
      "command": "jetsam",
      "args": ["serve"],
      "type": "stdio"
    }
  }
}

Shell aliases¶

Install short aliases for faster access:

jetsam init --aliases

This appends aliases to your shell config (~/.bashrc, ~/.zshrc, or ~/.config/fish/conf.d/jetsam.fish):

Alias	Command
`jt`	`jetsam`
`jts`	`jetsam status`
`jtv`	`jetsam save`
`jty`	`jetsam sync`
`jth`	`jetsam ship`
`jtp`	`jetsam ship --pr`
`jtw`	`jetsam switch`
`jtl`	`jetsam log`
`jtd`	`jetsam diff`

The aliases are guarded by a marker comment, so running init --aliases again is safe — it won’t duplicate them.

Agent instruction files¶

Generate a routing table that teaches AI agents to use jetsam instead of raw git/gh commands:

jetsam init --agents claude

This creates (or updates) CLAUDE.md with a table mapping git/gh commands to jetsam MCP tools. Use gemini for GEMINI.md, agents for AGENTS.md, or pass a custom path. Re-running is safe — content between  and  markers is replaced without touching other content.

Warning hooks¶

Generate Claude Code hooks that warn when agents use raw git/gh through Bash:

jetsam init --hooks claude

This creates .claude/hooks/jetsam-warn.sh and adds a PreToolUse hook to .claude/settings.json. The hook warns but does not block — agents can still use raw commands when needed.

Combining flags¶

All init flags are independent and can be combined:

jetsam init --mcp --agents claude --hooks claude --aliases

First workflow¶

A typical development cycle:

# Check where you are
jetsam status

# Start work on a feature
jetsam start fix-parser

# Make changes, then save (stage + commit)
jetsam save -m "fix parser edge case"

# Ship it (push + open PR)
jetsam ship

# When the PR is approved, finish (merge + cleanup)
jetsam finish

The plan-confirm pattern¶

Every mutating command follows the same pattern:

Build state — jetsam snapshots the repo (branch, dirty files, ahead/behind, PR status)
Generate plan — based on the state and your intent, jetsam creates a step-by-step plan
Show plan — you see exactly what will happen before anything changes
Confirm — you approve or abort
Execute — steps run sequentially; execution stops on first failure

$ jetsam ship -m "add feature"

  Ship: add feature
  ──────────────────────────────
  Stage: src/feature.py, tests/test_feature.py (2 files)
  Commit: "add feature"
  Push: origin/feature-branch
  PR: Create → main

  [c]onfirm / [a]bort: c

  ✓ Staged 2 files
  ✓ Committed: add feature (a1b2c3d)
  ✓ Pushed to origin/feature-branch
  ✓ PR #42 created: https://github.com/user/repo/pull/42

Skipping confirmation¶

For scripts or when you’re confident:

# Execute immediately
jetsam save -m "quick fix" --execute

# Preview only (no execution)
jetsam ship -m "feature" --dry-run

# JSON output (also skips interactive prompt)
jetsam --json ship -m "feature"

Entry points¶

Jetsam installs two CLI entry points:

jetsam — full name
jt — short alias

Both are identical. Use whichever you prefer.

Git pass-through¶

Any command jetsam doesn’t recognize is forwarded to git:

jetsam rebase -i HEAD~3    # → git rebase -i HEAD~3
jetsam stash list          # → git stash list
jetsam cherry-pick abc123  # → git cherry-pick abc123

This means you never need to switch between jetsam and git — use jetsam for everything and it handles the routing.