# Project Optimizer

> Analyze your project's AI readiness and get prioritized recommendations for improving agent instructions.

The project optimizer scans your project and scores how well it's set up for AI coding agents. It checks for missing files, content gaps, code quality issues, setup problems, and cross-file inconsistencies — then gives you prioritized recommendations with one-click fixes.

## Opening the Optimizer

Open it from **gem settings** (click a gem tile in the Crystal Rail, then the "optimize" button) or from the main menu under **Tools > Project Optimizer**.

The optimizer runs fresh every time you open it. Click **re-analyze** to rescan after making changes while the window is still open.

## Layout

The optimizer has two tabs:

- **Analyze** — health score, category breakdown, and prioritized gap list (left pane) alongside your project's agent files with edit/create buttons (right pane)
- **Explore** — directory browser for navigating your project's file tree, viewing agent files, and adding saved files from your library to any directory

## Health Score

The overall health score is a weighted average across four categories:

| Category | Weight | What it measures |
|----------|--------|-----------------|
| **Content** | 3x | Quality and completeness of CLAUDE.md instructions |
| **Files** | 2x | Presence of required agent files and cross-file consistency |
| **Code** | 2x | Source code size and organization |
| **Setup** | 1x | Skills, rules, MCP servers, settings, hooks |

Scores map to three levels: **high** (75+), **medium** (40-74), and **low** (below 40).

## What It Checks

### File Checks

| Check | Severity | What it detects |
|-------|----------|----------------|
| No CLAUDE.md | High | Project has no Claude Code instructions |
| No codex.md | High | Codex is active but has no instructions |
| No AGENTS.md | Medium | Multi-agent project lacks shared instructions |
| No .claudeignore | Medium | Large generated directories (node_modules, .build, dist) visible to agents |
| Subpackage missing CLAUDE.md | Low | Monorepo subpackage has its own build but no agent instructions |

### Content Checks

| Check | Severity | What it detects |
|-------|----------|----------------|
| No Build & Run section | High | Agents can't build or test without knowing the commands |
| Build & Run is a placeholder | High | Section exists but has no real commands |
| No Architecture section | Medium | No project map for agents to navigate by |
| No file size limit stated | Medium | Without a limit, agents create unbounded files |
| CLAUDE.md is very short | Low | Likely a stub — more context improves accuracy |
| CLAUDE.md over 200 lines | Medium | Consider splitting into .claude/rules/ for modularity |
| CLAUDE.md over 400 lines | High | Well past the recommended limit — split into rules |

### Content Quality Checks

| Check | Severity | What it detects |
|-------|----------|----------------|
| No testing commands section | High | Agents need to verify their own work |
| No code conventions or style guide | Medium | Agents guess at naming, formatting, and patterns |
| Stack not mentioned | Low | Manifest file detected but CLAUDE.md doesn't mention the language/framework |
| Build section has no copy-pasteable commands | Medium | Prose-only build instructions — fenced code blocks are more useful |
| Instructions are too vague | Low | Multiple vague phrases like "write clean code" with little actual content |
| No known issues or gotchas section | Low | Without documented pitfalls, agents hit problems by trial and error |
| No verification command | Medium | No verify gate — agents can report success without checking |
| No commit guidelines | Low | Without commit discipline, agents bundle unrelated changes |

### Code Checks

| Check | Severity | What it detects |
|-------|----------|----------------|
| Files over 1000 lines | High | Source files that are far too large for agents to work with effectively |
| Files over 500 lines | Medium | Source files approaching the recommended limit |

### Setup Checks

| Check | Severity | What it detects |
|-------|----------|----------------|
| No Claude skills configured | Low | No .claude/commands/ directory with reusable skills |
| No MCP servers configured | Low | No .mcp.json for extending agent capabilities |
| No .claude/rules/ configured | Low | No modular rule files |
| Few rules in .claude/rules/ | Low | Only 1-3 rules — consider adding more |
| No path-scoped rules | Low | Monorepo detected but rules don't use glob scoping |
| No .claude/settings.json | Low | No project-level permission rules |
| No hooks configured | Low | No hooks to automate lint, type-check, or memory sync |
| No permission rules in settings | Low | No allow/deny rules for tool access |

### Cross-File Checks

| Check | Severity | What it detects |
|-------|----------|----------------|
| Stale paths in CLAUDE.md | Medium | File paths referenced in CLAUDE.md that no longer exist |
| CLAUDE.md and codex.md conflict | Medium | Contradictory naming conventions or file size limits between agent files |
| CLAUDE.md is gitignored | Medium | Team members won't receive project instructions |
| CLAUDE.local.md not gitignored | Medium | Local overrides are being shared via git |
| .claude/settings.local.json not gitignored | Medium | User-specific permissions are being shared |

### Project Type Checks

The optimizer detects your tech stack from manifest files and suggests relevant facets when no project-specific guidance exists:

| Stack | Detected by | Suggestions |
|-------|------------|-------------|
| **Next.js** | next.config.js/ts/mjs | TypeScript setup, accessibility |
| **Node.js** | package.json | Linting configuration, logging |
| **Swift** | Package.swift | Swift tests, concurrency guidance |
| **Python** | pyproject.toml, requirements.txt | Pytest patterns, linting/formatting |
| **Django** | manage.py | Model design, views and serializers |
| **Go** | go.mod | Project structure, error handling patterns |
| **Rust** | Cargo.toml | Clippy lints |

## Export for Agent

Click **copy for agent** to export the current analysis as `optimization-report.md` in your project directory. A prompt is copied to your clipboard that you can paste directly into Claude Code or Codex — the agent will read the report and fix the gaps using real content from your codebase.

## Explore Tab

The explore tab lets you browse your project's directory tree. Each directory shows:

- **Agent instruction files** with colored badges (claude.md, agents.md, codex.md) and edit buttons
- **Subdirectories** with click-to-navigate breadcrumbs
- **"+" buttons** on every directory to add files from your saved library

---
Source: https://crystl.dev/docs/project-optimizer/