Get started with Medusa

Medusa is a desktop application currently available for macOS. Windows and Linux support is coming soon.

Tasks let you run Claude Code agents autonomously on isolated git branches. No hook setup required—just create a task and start the agent.

Creating a task

How it works

When you start an agent, Medusa:

• Creates a git worktree (isolated branch) in your project
• Spawns a Claude Code instance in that worktree
• Streams output so you can monitor progress
• Keeps the branch isolated from your main code

Reviewing and merging

When the agent finishes (or you pause it), click "Send to Review". Claude Code will commit the changes with a descriptive message, and you can:

Running multiple agents

You can run multiple tasks in parallel. Each gets its own git worktree, so they won't conflict with each other. Great for working on multiple features simultaneously.

Medusa automatically configures the Claude Code hook on first launch. Just open Medusa and you're ready to go.

How it works

Verify setup status

Open Medusa and navigate to Settings. The Hook Configuration section shows the status of each component.

curl -o ~/.claude/hooks/medusa-plan-review.sh \
  https://raw.githubusercontent.com/benodiwal/medusa/main/hooks/medusa-plan-review.sh
chmod +x ~/.claude/hooks/medusa-plan-review.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/medusa-plan-review.sh",
            "timeout": 86400
          }
        ]
      }
    ]
  }
}

Once the hook is configured, Medusa will automatically intercept Claude Code plans. Here's what happens:

Approving or requesting changes

After reviewing the plan, you have two options:

Annotations let you give Claude precise feedback on specific parts of a plan. Select any text and choose an annotation type from the toolbar.

Global comments

Use global comments for feedback that applies to the entire plan rather than specific text. This is useful for high-level direction like "focus on performance" or "keep the existing API structure".

Plans and tasks live together in one unified kanban board. See what's pending, what agents are running, and what's ready for review—all at a glance.

Click any plan card to open it for review. Plans are automatically moved between columns as you interact with them.

When you request changes and Claude revises the plan, Medusa shows you exactly what changed. The diff view highlights additions, deletions, and modifications.

Build a knowledge base of your implementation decisions. Export any approved plan to your Obsidian vault with one click.

Setting up Obsidian export

1. Open Medusa Settings
2. Navigate to the Obsidian section
3. Set your vault path (the folder where your Obsidian vault lives)
4. Optionally configure a subfolder for plans

Exporting a plan

After approving a plan, click the "Save to Obsidian" button. The plan will be saved as a markdown file with metadata including the date, session, and any annotations you made.

Collaborate with your team by sharing plans for review. Share URLs contain the entire plan compressed in the URL—no backend required, works entirely client-side.

How sharing works

Collaborative annotations

When viewing a shared plan, you'll see annotations from the original reviewer. Their annotations are read-only, but you can add your own comments, deletions, and replacements. Each reviewer's annotations are tracked separately.

Customize Medusa to fit your workflow. Access settings from the gear icon in the main interface.