openmole

OpenMole — AI-driven Refactoring

Version 0.8.2 · CLI: openmole init · openmole update

npm 官方包名 / npm package name: openmole
安装：npm install -g openmole · CLI 命令已更名 openmole

English · 中文

---

English

npm official package name: openmole — install with npm install -g openmole. The CLI command is openmole.

OpenMole is a refactoring methodology and agent plugin framework driven by code bad smells. Rules live in phase skills; project artifacts live under openmole/changes/<change-name>/.

Commands & Skills

Command (IDE slash / protocol)	Skill	Phase
/mole-explore · mole:explore	openmole-explore	Create/continue change; identify bad smells
/mole-plan · mole:plan	openmole-plan	Task breakdown
/mole-verify · mole:verify	openmole-verify	Verify coverage
/mole-apply · mole:apply	openmole-apply	Execute refactoring
/mole-archive · mole:archive	openmole-archive	Archive change

Main outputs per phase: badsmells.md, tasks.md, analysis.md, and code changes.

Workspace

openmole/
├── config.yaml              # current_change · installed_ides · init_version · init_at
└── changes/
    ├── <change-name>/
    │   ├── badsmells.md
    │   ├── tasks.md
    │   └── analysis.md
    └── archive/

Workflow

mole:explore → review badsmells → mole:plan → review tasks → mole:verify → mole:apply → user confirm → mole:archive

Package layout

openmole/                         # npm package root
├── bin/openmole.js               # CLI entry
├── cli/                     # init · update · IDE adapters
├── skills/                  # phase skills (openmole-*)
├── commands/                # IDE commands (mole-*.md)
├── .cursor-plugin/          # Cursor manifest
├── .claude-plugin/          # Claude Code manifest
├── .codex/                  # Codex install guide
├── gemini-extension.json    # Gemini CLI extension
├── .opencode/plugins/openmole.js # OpenCode plugin (zero npm deps at runtime)
└── templates/               # config / gitignore templates

Tech stack

• Skills / Commands: Markdown + YAML frontmatter
• Plugin harnesses: Cursor, OpenCode, Claude Code, Codex, Gemini CLI, Kiro, Qoder
• CLI: Node.js ESM + @clack/prompts (CLI only; plugin runtime has no third-party npm deps)
• License: MIT

Installation

npm registry (recommended)

npm install -g openmole
cd /path/to/your-project
openmole init              # welcome screen → interactive IDE selection

Clone + link (development)

git clone https://github.com/agiledon/openmole.git
cd openmole && npm install && npm link

cd /path/to/your-project
openmole init

Install CLI from GitHub

npm install -g github:agiledon/openmole
cd /path/to/your-project
openmole init

Package name on npm is openmole (the openmole name is taken). The CLI command is openmole.

After upgrading OpenMole, run openmole update in the target project to refresh IDE configs.

openmole init options

Flag	Description
--ides cursor,opencode,...	Non-interactive IDE list
--all	Configure all 7 IDEs
--none	Workspace only (openmole/)
--force	Overwrite existing workspace / IDE config
--global	OpenCode user config (~/.config/opencode/)
--dry-run	Print plan only

openmole init will:

1. Create openmole/config.yaml, openmole/changes/, openmole/changes/archive/
2. Install skills/commands per selected IDE (see table)
3. Merge gitignore snippet into .gitignore (machine-local symlinks)

IDE	Install model
Cursor	Project .cursor/skills/ + .cursor/commands/; user symlink ~/.cursor/plugins/local/openmole
OpenCode	Project opencode.json → .opencode/plugins/openmole.js (--global → user config)
Claude Code	Project .claude/skills/ + .claude/commands/; user symlink ~/.claude/plugins/local/openmole
Codex	Project .codex/skills/ (skills only, Codex does not expose slash commands)
Gemini CLI	Project .gemini/skills/, .gemini/commands/, .gemini/extensions/openmole symlink
Kiro	Project .kiro/skills/, .kiro/commands/
Qoder	Project .qoder/skills/, .qoder/commands/

Extend mode: If openmole/config.yaml exists, workspace is preserved; only IDEs missing from installed_ides are configured.

openmole update

Re-install IDE configs listed in openmole/config.yaml installed_ides (use after upgrading OpenMole):

openmole update
openmole update /path/to/project
openmole update --dry-run