Medusa Gaze is a Claude Code skill that takes one task, refines it into locked scope, executes it precisely, and deletes it from your backlog. Tasks don't graduate from Medusa, they get done and crossed out.
Medusa Gaze lives natively inside Claude Code as a /medusa skill. No API keys, no config per project. Install once, invoke from any session.
Type /medusa in any Claude Code session.
- Silently reads
CLAUDE.md,TODOs.md,DESIGN.md,CONTENT.md,WIKI.md, and.medusa/activity-types.md- whatever's present - Asks which task to complete, or finds the highest priority open item
- Interrogates the task - not a checklist, a conversation - until scope is airtight; if the task matches a known activity type, skips to the delta questions only
- Generates the Gaze File and saves it to disk before touching anything
- Executes precisely against the Gaze File; out-of-scope catches go into the Drift Jar
- Deletes the task from
TODOs.mdwhen done, then reviews the Jar, then offers to update the Activity Book
| Mode | How to trigger | What it does |
|---|---|---|
| Lock | Default | Full loop: interrogate → Gaze File → execute |
| Strike | Say strike |
Skip interrogation, straight to Gaze File and execution |
| Open | Say open [filename] |
Load a saved Gaze File, go straight to execution |
Lock is for most tasks. Strike is for tasks that already have airtight specs. Open is for resuming a session across context limits or intentional pauses.
Before execution begins, Medusa writes a contract to .medusa/gaze-YYYY-MM-DD-HHMM-[slug].md:
- Scope - what's in AND what's explicitly out
- Acceptance criteria
- Execution plan
- Risk flags
- Drift Jar - for out-of-scope catches during execution
The Gaze File can be executed immediately or saved for a future session.
While executing, Medusa catches everything interesting that's out of scope? ideas, adjacent improvements, things noticed in passing - and holds them in the Drift Jar without interrupting execution. At the close, every Jar item gets a decision: push to TODOs.md, keep in the Gaze File, or discard. Nothing is silently lost.
Over time, Medusa builds a catalog of recognized task patterns for your project. It lives in .medusa/activity-types.md and is maintained entirely by the Serpent - you never write to it directly.
When a task matches a known type, Medusa skips the questions the archetype already answers and asks only the delta - the one or two things specific to this instance. The Gaze File's Execution Plan is pre-populated with the archetype's standard steps.
At the end of every session, Medusa asks whether the task introduced a pattern worth adding. You say yes or no. New entries are written immediately; existing entries can be updated if a session revealed a gap or new pitfall.
The book only grows when a genuinely new, recurring pattern appears. One-off tasks don't get entries.
Medusa asks for confirmation before any irreversible action: file deletion, destructive git operations, database drops - even if it was planned. She also pauses mid-execution if new information surfaces that materially changes the risk of the current plan (a changed file, a wrong assumption, a missing dependency). Both are one-line stops, not re-interrogations.
Every /medusa session saves a record to .medusa/YYYY-MM-DD-HHMM-slug.md: task, mode, sibling input, and the full Gaze File.
The skill adds .medusa/ to your .gitignore automatically on first run, so session history stays local.
The execution philosophy and Gaze File template live in your home directory. Changes take effect immediately.
| File | Purpose |
|---|---|
~/.claude/medusa/manifesto.md |
Execution philosophy: what "done" means, scoping rules, the Drift Jar rule |
~/.claude/medusa/papyrus.md |
Gaze File template: rename fields, add sections, change structure |
git clone https://github.com/IGPenguin/medusa-gaze.git
cd medusa-gaze
chmod +x install-skill.sh
./install-skill.shThen restart Claude Code.
git pull && ./install-skill.shThen restart Claude Code.
- 🌊 Styx Flow - Turn raw notes into a prioritized backlog (
/styx) - 🔥 Hades Gate - Turn a task into 6 orthogonal implementation paths (
/hades) - ⚔️ Perseus Blade - Virtual studio that challenges your approach with expert voices (
/perseus)