{"id":49744479,"url":"https://github.com/scanaislop/aislop","last_synced_at":"2026-05-30T02:01:51.633Z","repository":{"id":343615139,"uuid":"1174449920","full_name":"scanaislop/aislop","owner":"scanaislop","description":"Catch the slop AI coding agents leave in your code. 40+ rules, 7 languages, sub-second, deterministic, no LLM. MIT.","archived":false,"fork":false,"pushed_at":"2026-05-28T00:27:24.000Z","size":2501,"stargazers_count":21,"open_issues_count":0,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T01:21:52.694Z","etag":null,"topics":["ai","ai-slop","ai-slop-detection","astro","cli","code-quality","code-review","developer-tools","devops","github-actions","linter","pre-commit","quality-gate","static-analysis","tools","typescript"],"latest_commit_sha":null,"homepage":"https://scanaislop.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scanaislop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-06T13:05:19.000Z","updated_at":"2026-05-28T00:15:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/scanaislop/aislop","commit_stats":null,"previous_names":["heavykenny/aislop","scanaislop/aislop"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/scanaislop/aislop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scanaislop%2Faislop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scanaislop%2Faislop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scanaislop%2Faislop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scanaislop%2Faislop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scanaislop","download_url":"https://codeload.github.com/scanaislop/aislop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scanaislop%2Faislop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33677261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-slop","ai-slop-detection","astro","cli","code-quality","code-review","developer-tools","devops","github-actions","linter","pre-commit","quality-gate","static-analysis","tools","typescript"],"created_at":"2026-05-10T01:28:49.477Z","updated_at":"2026-05-30T02:01:51.628Z","avatar_url":"https://github.com/scanaislop.png","language":"TypeScript","funding_links":[],"categories":["Starter Stacks"],"sub_categories":["Code / PR / Team Governance"],"readme":"# aislop\n\n**Catch the slop AI coding agents leave in your code.**\n\n[![npm version](https://img.shields.io/npm/v/aislop.svg)](https://www.npmjs.com/package/aislop)\n[![npm downloads](https://img.shields.io/npm/dm/aislop.svg)](https://www.npmjs.com/package/aislop)\n[![CI](https://github.com/scanaislop/aislop/actions/workflows/ci.yml/badge.svg)](https://github.com/scanaislop/aislop/actions/workflows/ci.yml)\n[![aislop score](https://badges.scanaislop.com/score/scanaislop/aislop.svg)](https://scanaislop.com/scanaislop/aislop)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Node \u003e= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)\n\nThe patterns Claude Code, Cursor, Codex, and OpenCode leave behind: narrative comments above self-explanatory code, swallowed exceptions, `as any` casts, hallucinated imports, duplicated helpers, dead code, todo stubs, oversized functions. Tests pass. Lint passes. The code rots anyway.\n\naislop catches them. 40+ rules across 7 languages (TS/JS, Python, Go, Rust, Ruby, PHP, Java). Scores every change 0–100. Sub-second. Deterministic — no LLM in the runtime path, same code in, same score out. MIT-licensed, free CLI.\n\n## Quick start\n\n```bash\nnpx aislop scan\n```\n\nNo install needed. Works on any project. Get your score in seconds.\n\n```bash\nnpx aislop fix                   # auto-fix issues\nnpx aislop fix -f                # aggressive fixes (deps, unused files)\nnpx aislop ci                    # CI mode (JSON + gate)\nnpx aislop hook install --claude # per-edit hook\n```\n\n**Public badge**: Show your score on your README\n\n```markdown\n[![aislop](https://badges.scanaislop.com/score/\u003cowner\u003e/\u003crepo\u003e.svg)](https://scanaislop.com)\n```\n\nRun `npx aislop badge` to auto-generate. Free at [scanaislop.com](https://scanaislop.com).\n\n## See it in action\n\n### Scan\n\n![aislop scan demo](assets/scan.gif)\n\n---\n\n## Installation\n\n```bash\n# Run without installing\nnpx aislop scan\n\n# npm\nnpm install --save-dev aislop\n\n# yarn\nyarn add --dev aislop\n\n# pnpm\npnpm add -D aislop\n\n# Global\nnpm install -g aislop\n```\n\nAlso available as [`@scanaislop/aislop`](docs/installation.md) on GitHub Packages.\n\n---\n\n## Usage\n\n### Scan\n\n```bash\nnpx aislop scan           # current directory\nnpx aislop scan ./src     # specific directory\nnpx aislop scan --changes # changed files from HEAD\nnpx aislop scan --staged  # staged files only\nnpx aislop scan --json    # JSON output\nnpx aislop scan --sarif   # SARIF 2.1.0 output (GitHub code scanning)\n```\n\n**Exclude files**: `node_modules`, `.git`, `dist`, `build`, `coverage` excluded by default. Add more in `.aislop/config.yml`:\n\n```yaml\nexclude:\n  - \"**/*.test.ts\"\n  - src/generated\n```\n\nOr via CLI: `npx aislop scan --exclude \"**/*.test.ts,dist\"`\n\n**Per-rule severity**: Override the severity of any rule by id, or turn it off:\n\n```yaml\n# .aislop/config.yml\nrules:\n  ai-slop/narrative-comment: warning   # error | warning | off\n  ai-slop/trivial-comment: \"off\"       # drop this rule entirely\n  security/hardcoded-secret: error\n```\n\n`off` drops matching diagnostics; `error`/`warning` rewrites severity before scoring and reporting. Absent map keeps default behavior.\n\n**Extend config**: Project config can extend a parent:\n\n```yaml\n# .aislop/config.yml\nextends: ../../.aislop/base.yml\nci:\n  failBelow: 80             # override specific keys\n```\n\n**Editor validation**: Point your editor at the JSON Schema in [`schema/aislop.config.schema.json`](schema/aislop.config.schema.json) for autocomplete and validation of `.aislop/config.yml`. Regenerate it from the source config schema with `pnpm gen:schema`.\n\n### Fix\n\nAuto-fix what's mechanical (formatters, unused imports, dead code). For issues that need context, hand off to your agent with full diagnostic info.\n\n```bash\nnpx aislop fix                 # safe auto-fixes\nnpx aislop fix -f              # aggressive: deps, unused files\n```\n\n### Hand off to agent\n\nWhen auto-fix can't solve it, pass the remaining issues to your coding agent with full context:\n\n```bash\nnpx aislop fix --claude        # Claude Code\nnpx aislop fix --cursor        # Cursor (copies to clipboard)\nnpx aislop fix --gemini        # Gemini CLI\nnpx aislop fix --codex         # Codex CLI\n# Also: --windsurf, --amp, --aider, --goose, --pi, --crush, --opencode, --warp, --kimi, --antigravity, --deep-agents, --vscode\nnpx aislop fix --prompt        # print prompt (agent-agnostic)\n```\n\n### Install hook\n\nRuns after every agent edit. Feedback flows back immediately.\n\n```bash\nnpx aislop hook install --claude           # Claude Code\nnpx aislop hook install --cursor           # Cursor\nnpx aislop hook install --gemini           # Gemini CLI\nnpx aislop hook install --pi               # pi\nnpx aislop hook install                    # all supported agents\nnpx aislop hook install claude cursor      # specific agents\n```\n\n**Runtime adapters** (scan + feedback): `claude`, `cursor`, `gemini`, `pi`.  \n**Rules-only** (agent reads rules): `codex`, `windsurf`, `cline`, `kilocode`, `antigravity`, `copilot`.\n\n**Quality-gate mode**: Blocks if score regresses below baseline.\n\n```bash\nnpx aislop hook install --claude --quality-gate\nnpx aislop hook baseline                    # re-capture baseline\nnpx aislop hook status                      # list installed\nnpx aislop hook uninstall --claude          # remove\n```\n\nDocs: [`/docs/hooks`](https://scanaislop.com/docs/hooks)\n\n### MCP server\n\nExpose aislop as MCP tools for Claude Desktop, Cursor, Codex:\n\n```jsonc\n// ~/.cursor/mcp.json or Claude Desktop config\n{\n  \"mcpServers\": {\n    \"aislop\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"aislop-mcp\"]\n    }\n  }\n}\n```\n\n**Tools**: `aislop_scan`, `aislop_fix`, `aislop_why`, `aislop_baseline`\n\n### CI\n\n```bash\nnpx aislop ci                  # JSON output, exits 1 if score \u003c threshold\n```\n\n### Other commands\n\n```bash\nnpx aislop init                # create .aislop/config.yml\nnpx aislop init --strict       # enterprise-grade gate: all engines, typecheck, failBelow 85\nnpx aislop rules               # list rules\nnpx aislop badge               # print badge URL\nnpx aislop trend               # show score history over time\nnpx aislop                     # interactive menu\n```\n\n**Score history**: a normal (full-project, interactive) `scan` appends a compact record to `.aislop/history.jsonl` (timestamp, score, error/warning counts, file count, CLI version). `aislop trend` reads it and prints a table plus an ASCII sparkline of recent scores. History is a local side effect only: it is never written for `--json`/`--sarif` output, in CI, or when `AISLOP_NO_HISTORY=1` is set, so machine output stays clean.\n\nDocs: [commands](docs/commands.md)\n\n---\n\n## CI integration\n\n### Pre-commit\n\nRun directly on staged files:\n\n```bash\nnpx aislop scan --staged\n```\n\nOr wire it into the [pre-commit](https://pre-commit.com) framework via the bundled hook:\n\n```yaml\n# .pre-commit-config.yaml\nrepos:\n  - repo: https://github.com/scanaislop/aislop\n    rev: v0.9.4\n    hooks:\n      - id: aislop\n```\n\n### GitHub Actions\n\nRun `npx aislop init` and accept the workflow prompt, or add manually:\n\n```yaml\n- uses: actions/checkout@v4\n- uses: actions/setup-node@v4\n  with:\n    node-version: 20\n- run: npx aislop@latest ci .\n```\n\n**Composite action**:\n\n```yaml\n- uses: actions/checkout@v4\n- uses: scanaislop/aislop@v0.8\n```\n\n**GitHub code scanning (SARIF)**: emit a SARIF 2.1.0 report and upload it so findings appear in the Security tab:\n\n```yaml\n- run: npx aislop@latest scan . --sarif \u003e aislop.sarif\n- uses: github/codeql-action/upload-sarif@v3\n  with:\n    sarif_file: aislop.sarif\n```\n\n### Quality gate\n\nSet minimum score in `.aislop/config.yml`:\n\n```yaml\nci:\n  failBelow: 70\n```\n\n`aislop ci` exits 1 when score \u003c threshold. Docs: [CI/CD](docs/ci.md)\n\n---\n\n## For teams\n\n[scanaislop](https://scanaislop.com) is the hosted platform for teams:\n\n- PR gates with score thresholds\n- Standards hierarchy (org → team → project)\n- Dashboards and agent attribution\n- Visual rules manager\n\nSame engines, same scores. CLI is MIT-licensed. [Learn more →](https://scanaislop.com)\n\n---\n\n## Why aislop\n\nAI coding tools generate code that compiles and passes tests but ships with patterns no engineer would write. `aislop` gives you one score, one gate, and auto-fixes what it can.\n\n- **One score**: 0-100, enforced in CI. Weighted so sloppy patterns hit harder than style noise.\n- **Auto-fix first**: Clears formatters, unused imports, dead code mechanically. Hands off the rest to your agent with full context.\n- **Deterministic**: Regex + AST + standard tooling. No LLMs, no API calls. Same code in, same score out.\n- **Zero-config start**: `npx aislop scan` works on any repo. Add `.aislop/config.yml` to tune.\n\n## What it catches\n\nSix deterministic engines run in parallel:\n\n| Engine | What it checks | How |\n|---|---|---|\n| **Formatting** | Code style consistency | Biome, ruff, gofmt, cargo fmt, rubocop, php-cs-fixer |\n| **Linting** | Language-specific issues | oxlint, ruff, golangci-lint, clippy, expo-doctor |\n| **Code Quality** | Complexity and dead code | Function/file size limits, deep nesting, unused files/deps (knip), AST-based unused-declaration removal |\n| **AI Slop** | AI-authored code patterns | Narrative comments, trivial comments, dead patterns, unused imports, `as any`, `console.log` leftovers, TODO stubs, generic names |\n| **Security** | Vulnerabilities and risky code | eval, innerHTML, SQL/shell injection, dependency audits (npm/pip/cargo/govulncheck) |\n| **Architecture** | Structural rules (opt-in) | Custom import bans, layering rules, required patterns |\n\nSee the full [rules reference](docs/rules.md).\n\n---\n\n## Research\n\naislop rules are shaped by public scans and benchmark-derived failure modes, not only local fixtures. The [research program](docs/research-program.md) defines how to run repeatable open-source scans: pin the cohort, store raw JSON, classify findings, fix noisy rules with regression tests, and publish the limits.\n\n---\n\n## Docs\n\n[Installation](docs/installation.md) · [Commands](docs/commands.md) · [Rules](docs/rules.md) · [Config](docs/configuration.md) · [Scoring](docs/scoring.md) · [CI/CD](docs/ci.md) · [Telemetry](docs/telemetry.md) · [Research program](docs/research-program.md)\n\n## Community\n\n[Discussions](https://github.com/scanaislop/aislop/discussions) for questions, rule requests, and false-positive triage · [Issues](https://github.com/scanaislop/aislop/issues) for bugs\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). AI assistants: [AGENTS.md](AGENTS.md).\n\n## Acknowledgments\n\nBuilt on: [Biome](https://biomejs.dev/), [oxlint](https://oxc.rs/), [knip](https://knip.dev/), [ruff](https://docs.astral.sh/ruff/), [golangci-lint](https://golangci-lint.run/), [expo-doctor](https://docs.expo.dev/)\n\n## Contributors\n\n\u003c!-- CONTRIBUTORS-START --\u003e\n- [@heavykenny](https://github.com/heavykenny)\n- [@myke-awoniran](https://github.com/myke-awoniran)\n- [@yashrajoria](https://github.com/yashrajoria)\n\u003c!-- CONTRIBUTORS-END --\u003e\n\nAuto-updated by `.github/workflows/contributors.yml`. [Link commit email](https://github.com/settings/emails) or add to [`.github/contributors-overrides.json`](.github/contributors-overrides.json).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscanaislop%2Faislop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscanaislop%2Faislop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscanaislop%2Faislop/lists"}