Documentation / Your first session

Your first session

Mulpex is a wrapper around the claude CLI. The reason it exists is the keyboard layer: running Claude inside iTerm2 or zsh means the shell intercepts Ctrl-keys and readline shortcuts that Claude wants for itself. Mulpex owns the keyboard, so those shortcuts behave the way Claude expects.

1. Add a project

Hit ⌘O (or use the File menu) and pick a directory. If the folder isn't a git repo, Mulpex offers to initialize one for you — Claude sessions live in git worktrees, so the directory has to be tracked.

2. Spawn a Claude tab

Select the project in the sidebar, then press ⌘T. Mulpex creates a new git worktree at <project>/.mulpex/worktrees/<id>/ on a fresh branch named mulpex/<id>, then launches claude inside that worktree. The tab is the Claude session; type at it the same way you would in Terminal.

Each worktree is fully isolated — Claude sees only its own branch, so two parallel tabs working on different features can't step on each other's file edits.

3. Send your work back to main

When you're done, press ⌘⇧S to close the worktree. Mulpex walks you through a pre-deploy review: you see the diff, can ask Claude follow-up questions, and choose whether to merge into the main branch or discard the worktree. Closing the tab while there's unmerged work doesn't delete it — the instance goes dormant and can be revived from the sidebar.

What's next

• Try a loose instance with ⌘⇧T for one-off diagnostics that don't need a branch.
• Attach a runbook via ⌘P to give Claude durable context for recurring work.
• Skim the keyboard shortcuts.