Optimus-claude reset

Removes files installed by /optimus:init and /optimus:permissions from the project. Compares each file against plugin templates and classifies as unmodified, likely generated, or user-modified. Always asks before deleting. Git-tracked files are noted as recoverable. Tests are never touched. Monorepo and multi-repo aware. Use for clean reinstall or to stop using optimus.

install

source · Clone the upstream repo

git clone https://github.com/oprogramadorreal/optimus-claude

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/oprogramadorreal/optimus-claude "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/reset" ~/.claude/skills/oprogramadorreal-optimus-claude-reset && rm -rf "$T"

manifest: skills/reset/SKILL.md

source content

Reset — Remove optimus-generated files

Remove files installed by

/optimus:init

and

/optimus:permissions

from the project. Does NOT uninstall the plugin itself — only removes files from the project's

.claude/

directory (and subproject docs for monorepos).

Safety Rules

These rules are absolute and override all other instructions:

NEVER touch test files, test directories, or test configuration — even if created by
```
/optimus:unit-test
```
NEVER touch files outside
```
.claude/
```
, subproject
```
CLAUDE.md
```
, subproject
```
docs/
```
, and workspace root
```
CLAUDE.md
```
NEVER delete
```
.claude/settings.json
```
without first extracting user-added content (use surgical removal — Step 4)
ALWAYS show the categorized file list and get user confirmation before removing anything

Workflow

Step 1 — Detect project context

Multi-repo workspace detection

Read

$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md

and run the detection algorithm.

Determine project type:

Multi-repo workspace — root has no
```
.git/
```
, 2+ child directories have
```
.git/
```
directories. Each child repo has its own
```
.claude/
```
directory. Workspace root may have a local
```
CLAUDE.md
```
(not version-controlled)
Monorepo — single git repo with multiple subproject directories (e.g.,
```
packages/
```
,
```
apps/
```
). Root has
```
.claude/
```
, subprojects may have their own
```
CLAUDE.md
```
and
```
docs/
```
directories
Single project — standard single repo with
```
.claude/
```
directory

Check for optimus files

For multi-repo workspaces: enumerate all child repos and check each for

.claude/

directories. Also check for a workspace root

CLAUDE.md

. If no child repo has

.claude/

and no workspace root

CLAUDE.md

exists → inform the user "Nothing to reset — no optimus files found" → stop.

For single project / monorepo: check if

.claude/

directory exists. If not → inform the user "Nothing to reset — no optimus files found" → stop.

.claude/.optimus-version

does not exist, warn that the project may not have been initialized by optimus, but proceed with template comparison anyway.

Inventory optimus-managed files

Scan for all files that optimus skills may have created. Only list files that actually exist:

Root

.claude/

directory:

```
.claude/CLAUDE.md
```
```
.claude/.optimus-version
```
```
.claude/settings.json
```
```
.claude/docs/coding-guidelines.md
```
```
.claude/docs/testing.md
```
```
.claude/docs/styling.md
```
```
.claude/docs/architecture.md
```

.claude/docs/skill-writing-guidelines.md

```
.claude/agents/code-simplifier.md
```
(legacy — from previous optimus versions)
```
.claude/agents/test-guardian.md
```
(legacy — from previous optimus versions)
```
.claude/hooks/format-python.py
```
```
.claude/hooks/format-node.js
```
```
.claude/hooks/format-rust.sh
```
```
.claude/hooks/format-go.sh
```
```
.claude/hooks/format-csharp.sh
```
```
.claude/hooks/format-java.sh
```
```
.claude/hooks/format-cpp.sh
```
```
.claude/hooks/format-dart.sh
```
```
.claude/hooks/restrict-paths.sh
```

Monorepo subprojects (scan for these patterns):

```
<subproject>/CLAUDE.md
```
— subproject overview files
```
<subproject>/docs/testing.md
```
— subproject testing docs
```
<subproject>/docs/styling.md
```
— subproject styling docs
```
<subproject>/docs/architecture.md
```
— subproject architecture docs

Multi-repo workspace root:

```
CLAUDE.md
```
at workspace root (local-only file)

Step 2 — Classify each file

For each file found in Step 1, determine two things:

Origin classification — was it generated by optimus, and has it been modified?
Git tracking — is it tracked by git? (recoverable via
```
git checkout
```
if deleted)

Check git tracking by running

git ls-files --error-unmatch <file>

for each file. Note: in multi-repo workspaces, run this from the correct repo directory.

Classification by comparison strategy

Verbatim templates (exact content match):

For these files, read both the project file and the corresponding template from the plugin. If content is identical → classify as

UNMODIFIED

. If different → classify as

MODIFIED

Project file	Template source
`.claude/agents/code-simplifier.md`	`$CLAUDE_PLUGIN_ROOT/agents/code-simplifier.md` (legacy — agents now live at plugin level)
`.claude/agents/test-guardian.md`	`$CLAUDE_PLUGIN_ROOT/agents/test-guardian.md` (legacy — agents now live at plugin level)
`.claude/hooks/format-python.py`	`$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-python.py`
`.claude/hooks/format-node.js`	`$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-node.js`
`.claude/hooks/format-rust.sh`	`$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-rust.sh`
`.claude/hooks/format-go.sh`	`$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-go.sh`
`.claude/hooks/format-csharp.sh`	`$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-csharp.sh`
`.claude/hooks/format-java.sh`	`$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-java.sh`
`.claude/hooks/format-cpp.sh`	`$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-cpp.sh`
`.claude/hooks/format-dart.sh`	`$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-dart.sh`
`.claude/hooks/restrict-paths.sh`	`$CLAUDE_PLUGIN_ROOT/skills/permissions/templates/hooks/restrict-paths.sh`

Near-exact template (coding-guidelines.md):

The template body (everything after line 1) is verbatim — only line 1 has

[PROJECT NAME]

substituted by init. Compare the project file's content from line 2 onward against the template's content from line 2 onward. If identical →

UNMODIFIED

. If different →

MODIFIED

Template:

$CLAUDE_PLUGIN_ROOT/skills/init/templates/docs/coding-guidelines.md

Generated docs (heuristic — content filled in by init):

These files have ALL content filled in by init from project analysis — no template comparison is possible. Use heuristic fingerprinting:

Project file	Template fingerprint (line 1 HTML comment)	Template section headings
`.claude/CLAUDE.md`	`<!-- Keep this file and .claude/docs/ updated when project structure, conventions, or tooling changes -->`	`Conventions` , `Commands` , `Project Structure` , `Before Writing Code` , `Documentation`
`.claude/docs/testing.md`	(no comment — check heading) First line: `# Testing`	`Test Runner` , `Running Tests` , `Test Structure` , `Writing Tests` , `Workflow` , `Coverage`
`.claude/docs/skill-writing-guidelines.md`	(no comment — check heading) First line: `# Skill-writing guidelines for`	`Foundation` , `Writing Style` , `Degrees of Freedom` , `Description Quality (frontmatter)` , `Progressive Disclosure` , `Directory Layout` , `Shared References` , `Workflows and Feedback Loops` , `Common Patterns` , `Evaluation and Iteration` , `Anti-patterns` , `Documentation`
`.claude/docs/styling.md`	(no comment — check heading) First line: `# Styling`	`Stack` , `Conventions` , `File Organization` , `Adding New Components`
`.claude/docs/architecture.md`	(no comment — check heading) First line: `# Architecture`	ANY of these heading sets: (1) code-only: `Overview` , `Directory Map` , `Data Flow` , `Key Patterns` , `Dependencies Between Modules` (2) skill-authoring: `Overview` , `Directory Map` , `Skill Organization` , `Agent Boundaries` , `Reference Hierarchy` , `Orchestration Patterns` (3) hybrid: `Overview` , `Directory Map` , `Code Architecture` , `Skill Architecture`

For CLAUDE.md: check if line 1 matches the template comment. Also check for monorepo variant:

<!-- Keep this file, .claude/docs/, and subproject CLAUDE.md files updated when project structure changes -->

For subproject CLAUDE.md files: check for

<!-- Keep this file and docs/ updated when this subproject's conventions change -->

For workspace root CLAUDE.md: check for

<!-- Local workspace file — not version-controlled. Each repo has its own .claude/CLAUDE.md. -->

For docs (testing.md, skill-writing-guidelines.md, styling.md, architecture.md): check if the

##

section headings match the template's headings in the same order.

If fingerprints match → classify as

LIKELY_GENERATED

. If fingerprints don't match → classify as

MODIFIED

Always safe:

.claude/.optimus-version

— pure version tracking file with no user content → always classify as

UNMODIFIED

Complex (settings.json):

.claude/settings.json

→ classify as

COMPLEX

. This file is handled separately in Step 4 via surgical key removal.

Classification summary

Each file gets one of:

```
UNMODIFIED
```
— exact match with plugin template (safe to remove)
```
LIKELY_GENERATED
```
— has optimus fingerprints, content was filled in by init
```
MODIFIED
```
— differs from template or lacks optimus fingerprints (user customized)
```
COMPLEX
```
— settings.json (surgical removal in Step 4)

Step 3 — Present reset plan and ask user

Present the full categorized file list to the user. For each file, show:

The file path
Its classification (UNMODIFIED / LIKELY_GENERATED / MODIFIED)
Whether it is git-tracked (if yes, note: "recoverable via
```
git checkout
```
")

Group by classification. Example format:

## Unmodified (exact match with plugin template)
- .claude/agents/code-simplifier.md (git-tracked)
- .claude/hooks/format-node.js (git-tracked)
- .claude/.optimus-version (git-tracked)

## Likely generated by optimus
- .claude/CLAUDE.md (git-tracked)
- .claude/docs/testing.md (git-tracked)

## Modified by user
- .claude/docs/coding-guidelines.md (git-tracked) — user added custom rules

## settings.json
- .claude/settings.json — will remove optimus entries, preserve user config

For multi-repo workspaces, group files by repo (e.g.,

### repo-name/

Then ask the user using AskUserQuestion:

Header: "Reset"
Question: "Review the files above. Which should be removed?"
Options:
1. "Remove all" (Recommended) — remove all optimus files (UNMODIFIED + LIKELY_GENERATED + MODIFIED). Safe when git-tracked
2. "Keep modified" — remove UNMODIFIED + LIKELY_GENERATED, keep MODIFIED files
3. "Unmodified only" — remove only UNMODIFIED (most conservative)
4. "Abort" — cancel reset, do not remove anything

If user selects "Abort" → inform the user that no files were removed → stop.

Step 4 — Clean settings.json (surgical removal)

.claude/settings.json

exists, do NOT delete it outright. Surgically remove optimus-contributed entries:

Read the current
```
.claude/settings.json
```

Read the init template:

$CLAUDE_PLUGIN_ROOT/skills/init/templates/settings.json

Read the permissions template:

$CLAUDE_PLUGIN_ROOT/skills/permissions/templates/settings.json

Remove PostToolUse hooks from init: In

hooks.PostToolUse

, remove any entry whose

hooks

array contains commands referencing

.claude/hooks/format-

(init's formatter hooks). If the

PostToolUse

array becomes empty after removal, remove the

PostToolUse

key.

Remove PreToolUse hooks from permissions: In

hooks.PreToolUse

, remove any entry whose

hooks

array contains commands referencing

.claude/hooks/restrict-paths.sh

(permissions hook). If the

PreToolUse

array becomes empty after removal, remove the

PreToolUse

key.

Remove permissions entries from permissions: Compare

permissions.allow

against the permissions template's

permissions.allow

list. Remove entries that match. Also remove any

mcp__*

entries — but only if a

.mcp.json

file exists in the relevant project root (for multi-repo workspaces, check each child repo's root independently; for single projects and monorepos, check the project root). If no

.mcp.json

exists, leave

mcp__*

entries untouched (they may have been manually added by the user). If

permissions.allow

becomes empty, remove the key.

Compare

permissions.deny

against the permissions template's

permissions.deny

list. Remove entries that match. If

permissions.deny

becomes empty, remove the key.

permissions

object becomes empty, remove it. If

hooks

object becomes empty, remove it.

Final check: If the entire JSON object is empty (

{}

), delete the file entirely. Otherwise, write the cleaned JSON back with proper formatting (2-space indentation).

Step 5 — Execute removals

Based on the user's choice from Step 3:

Delete the selected files (using
```
rm
```
for each file)
Clean
```
settings.json
```
per Step 4 (always — regardless of user's choice, since surgical removal preserves user content)

Multi-repo workspace handling:

Process each child repo independently
Delete workspace root
```
CLAUDE.md
```
if it was classified and selected for removal

Monorepo handling:

Process root
```
.claude/
```
directory (same as single project)
Delete subproject
```
CLAUDE.md
```
files that were classified and selected for removal
Delete subproject
```
docs/
```
files (testing.md, styling.md, architecture.md) that were classified and selected for removal

Step 6 — Clean empty directories

After file removal, check these directories and remove any that are now empty:

```
.claude/hooks/
```
```
.claude/agents/
```
```
.claude/docs/
```
```
.claude/
```
(only if completely empty — no files or subdirectories remain)

For monorepos: also check subproject

docs/

directories.

For multi-repo workspaces: check each repo's

.claude/hooks/

.claude/agents/

.claude/docs/

, and

.claude/

directories.

Step 7 — Report results

Present a summary to the user:

Files removed — count and list
Files kept — count and list with reason (user-modified, user chose to keep, etc.)
settings.json — entries removed, or file deleted, or "no changes needed"
Directories cleaned — empty directories that were removed

Step 8 — Next step

Recommend the next step based on intent:

To reinstall optimus project files →
```
/optimus:init
```
(and
```
/optimus:permissions
```
for safety guardrails)
To uninstall the plugin itself →
```
/plugin uninstall optimus@optimus-claude
```
(Claude Code command, not an optimus skill)

Tell the user: Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.