Clean Room

Clean Room

Clean Room is an agent workflow for turning authorized source analysis into clean behavioral specs, clean implementation plans, and clean destination code. When no indexable source code is available, it can use authorized screenshots/images as contaminated fallback evidence for behavior specs.

It is a POC based on ideas from malus.sh. It is an engineering risk-reduction workflow, not legal advice, and it does not create a legal safe harbor.

What This Is / Does

Use this package when you need documented separation between source-reading work and clean implementation work.

It installs:

• Clean-room skills for Codex, Claude Code, and other agent runtime layouts.
• Role-agent prompts for contaminated analysis, clean planning, clean implementation, and final polish.
• JSON schemas and examples for durable workflow artifacts.
• Hook guardrails that help keep source material out of clean artifacts.
• A small CLI for runtime installation, bootstrap folders, preflight contracts, canonical artifact templating and validation, hook smoke tests, and the bounded inner clean-room runner.

The workflow creates clean behavioral spec packages and clean implementation outputs. It does not generate replacement code directly from source.

Core boundary:

• Contaminated roles may read authorized source or fallback visual evidence and write contaminated artifacts.
• Source-denied roles may read only clean artifacts, implementation roots, schemas, and approved public/reference roots.
• Clean implementation code is written only under the clean implementation root.
• Raw source, raw screenshots, source or visual paths, private identifiers, raw diffs, copied comments, copied UI text, and source-shaped pseudocode must not cross into clean handoff artifacts.

For the full boundary model, see docs/ARCHITECTURE.md. For CLI and troubleshooting details, see docs/REFERENCE.md.

Install

Requires Node.js >=22.

Recommended path:

npm install -g clean-room-skill
clean-room-skill

The first command installs the CLI. The second command starts the interactive installer for runtime files, skills, agents, and hooks.

For a direct global runtime install, pass the runtime flag:

clean-room-skill --claude --global --yes
clean-room-skill --codex --global --yes
clean-room-skill --opencode --global --yes
clean-room-skill --all --global --yes

If you do not want the CLI installed globally, run the same installer once through npx:

npx clean-room-skill@latest --claude --global --yes
npx clean-room-skill@latest --codex --global --yes
npx clean-room-skill@latest --all --global --yes

Those npx commands install the selected runtime files globally. You do not need to keep running npx to use the installed Claude Code, Pi, Codex, or other runtime entry points.

For edge cases such as ccsilo variants or modified Claude directories, add --config-dir <path-to-claude-config-root> to target that Claude config root explicitly. If Claude is launched through a wrapper, set CLEAN_ROOM_CLAUDE_EXECUTABLE=/absolute/path/to/wrapper; the installer runs that exact executable and rejects relative, cwd-local, and node_modules/.bin paths.

Claude global installs use Claude's plugin system for skills and agents, so entry points are namespaced as /clean-room:init, /clean-room:preflight, and /clean-room. The installer still manages hook files and migrates older standalone Claude skill copies out of the config root on reinstall or update.

Hook modes:

• --hooks=safe: default. Hooks are installed but enforce only during clean-room role sessions with the required environment.
• --hooks=strict: fail-closed hook mode for dedicated Codex, Claude, or OpenCode clean-room homes.
• --hooks=copy-only or --no-hooks: copy hook files without registering runtime hook config.

Verified runtimes are Codex, Claude Code, and OpenCode. OpenCode support uses native skills, commands, and a generated local plugin bridge for hook enforcement. Other runtime layouts are installed on a best-effort basis. See docs/REFERENCE.md for the full support table and install roots.

Marketplace install is also supported.

Codex:

codex plugin marketplace add https://github.com/whit3rabbit/clean-room-skill.git

Claude Code:

/plugin marketplace add https://github.com/whit3rabbit/clean-room-skill.git
/plugin install clean-room@clean-room-skill

Pi:

pi install npm:clean-room-skill@latest
npx clean-room-skill@latest --pi --global --yes