codeconscience

Discover the unwritten rules in your codebase — and export them for AI assistants.

CodeConscience mines a TypeScript/JavaScript project for implicit conventions (naming, return types, error patterns), architectural constraints (layer boundaries, co-occurrence rules, temporal ordering, guard clauses), and design rationale (extracted from git history) — then converts them into explicit rules consumable by LLM agents.

Zero LLM dependency. All analysis is deterministic: AST/regex parsing, statistics, and pattern mining. Source code never leaves your machine.

Install

npm install -g codeconscience
# or
pnpm add -g codeconscience

Requires Node.js ≥ 18.

Quick start

# Inside any TypeScript/JavaScript project
codeconscience init           # creates .codeconscience/ and indexes the project
codeconscience scan           # discovers conventions, constraints, rationale
codeconscience rules list     # review what was found
codeconscience rules approve <id>   # promote a rule from proposed → active
codeconscience export --format claude-md   # write CLAUDE.md

Commands

| Command | What it does | |---------|--------------| | init | Initialize CodeConscience in the current project | | scan | Index files + run all analyzers | | check | Report violations of active rules (exits with code 1 on errors) | | watch | Watch for file changes and re-check incrementally | | rules list | List discovered rules (filter with --status, --type, --category) | | rules approve <id> | Mark a rule as active | | rules reject <id> | Mark a rule as rejected | | rules deprecate <id> | Mark an active rule as deprecated | | export --format <fmt> | Export rules; <fmt> is one of: yaml, claude-md, cursorrules, copilot, md, dashboard, all | | serve | Start the MCP server (stdio) |

All commands accept -d, --dir <path> to operate on a project other than the current directory.

Export formats

| Format | Output file | Audience | |--------|-------------|----------| | claude-md | CLAUDE.md | Claude Code | | cursorrules | .cursorrules | Cursor IDE | | copilot | .github/copilot-instructions.md | GitHub Copilot | | yaml | PROJECT_CONTRACT.yaml | Tooling / CI | | md | PROJECT_RULES.md | Humans | | dashboard | codeconscience-report.html | Visual report |

MCP server

CodeConscience ships with a Model Context Protocol server. Add it to your Claude Code config:

{
  "mcpServers": {
    "codeconscience": {
      "command": "codeconscience",
      "args": ["serve"]
    }
  }
}

Tools exposed: query_rules, get_conventions, get_rationale, check_violation, suggest_fix.

Programmatic use

If you want to build on top of the analysis engine, install @codeconscience/core directly.

License

Released under the PolyForm Noncommercial License 1.0.0. Free for personal, hobby, research, educational, and non-profit use. Commercial use requires a separate license — open an issue to discuss.