clean-code-codex

Clean Code Codex

A composable, multi-language, TDD-first clean code enforcement system for AI agents.

Version: 1.1.2 | Languages: TypeScript · Python · Go · Rust · JavaScript

---

Installation

Claude Code

# Install directly from this repo
claude --plugin-dir /path/to/clean-code-codex

# Or clone and install
git clone https://github.com/mikecubed/clean-code-codex.git
claude --plugin-dir ./clean-code-codex

GitHub Copilot CLI

GitHub Copilot uses agent files in .github/agents/ and coding instructions in .github/copilot-instructions.md. Install in three steps:

Step 1 — Clone the plugin

git clone https://github.com/mikecubed/clean-code-codex.git

Step 2 — Copy the agent and skills to your project

# Agent definition (makes the agent available in Copilot Chat / CLI)
mkdir -p .github/agents
cp /path/to/clean-code-codex/agents/clean-code-codex.agent.md .github/agents/

# Skills (required for the agent to function)
cp -r /path/to/clean-code-codex/skills ./skills
cp -r /path/to/clean-code-codex/commands ./commands
cp -r /path/to/clean-code-codex/hooks ./hooks
cp -r /path/to/clean-code-codex/gh-hooks ./gh-hooks

Step 3 — Generate coding instructions (optional but recommended)

Populates .github/copilot-instructions.md with the top-priority rules so Copilot applies them in every response — without any explicit invocation.

bash /path/to/clean-code-codex/scripts/generate-instructions.sh

The agent is now available as @clean-code-codex in GitHub Copilot Chat and activates automatically on write, review, refactor, and test operations.

Set up enforcement hooks (recommended):

Hooks fire automatically at write/edit/bash time for real-time rule enforcement.

# Copy the Copilot CLI hook configuration to your project
mkdir -p .github/hooks
cp /path/to/clean-code-codex/gh-hooks/hooks.json .github/hooks/hooks.json

# Make hook scripts executable
chmod +x /path/to/clean-code-codex/hooks/scripts/*.sh

Update the script paths in .github/hooks/hooks.json to absolute paths pointing to the copied hooks/scripts/ directory.

Note: Without hooks, the agent still enforces all 65 rules on demand — hooks add real-time blocking/warning at the point of action. See docs/hooks.md for full hook details and per-CLI configuration.

Skill path (other agent runtimes)

cp -r . ~/.agent/skills/clean-code-codex

The conductor skill (skills/conductor/SKILL.md) is the sole entry point. All other sub-skills are loaded on demand.

---

Quick Start

Via slash command (Claude Code):

/codex                          # Auto-detect language + full review
/codex src/                     # Scope to src/ directory
/codex --fix                    # Auto-remediate WARN violations
/codex src/ --scope "**/*.ts"   # TypeScript files in src/ only
/codex --deep --history         # Exhaustive scan + git history analysis
/codex --scaffold-tests         # Generate test skeletons on TDD-1 blocks
/codex --diff-only              # Review only changed files (git diff HEAD)
/codex --explain NAME-1         # Print NAME-1 explanation and exit
/codex --explain                # Add explanations to all violations
/codex --refresh                # Re-detect language/framework/layers

Auto-activation: The conductor also activates automatically when you write, review, refactor, or test code — no explicit invocation required.

CLI arguments (all optional; defaults are safe):

/codex [path] [--scope <glob>] [--fix] [--write] [--history] [--deep] [--scaffold-tests] [--diff-only] [--explain [RULE-ID]] [--refresh]

Argument	Default	Description
path	repo root	Limit scope to a file or directory
--scope <glob>	repo root	Restrict all operations to matching paths
--fix	off	Permit auto-remediation edits for WARN violations
--write	off	Permit scaffold/write operations (TDD-gated)
--history	off	Include git history analysis (needed for SEC-1/SEC-6)
--deep	off	Enable slower exhaustive scans
--scaffold-tests	off	Generate test skeletons on TDD-1 blocks
--diff-only	off	Review only changed files (git diff HEAD)
--explain [RULE-ID]	off	Print explanation for a specific rule, or add explanations to all violations
--refresh	off	Re-detect language/framework/layers (clears .codex/config.json cache)

Safety defaults:

• Without --fix: zero file modifications, regardless of violations found
• Without --scope or path: agent asks for scope when repo has > 50 tracked files
• Destructive actions require both --fix AND explicit user confirmation

---

Check Reference