{"id":45498470,"url":"https://github.com/mauhpr/agentlint-plugin","last_synced_at":"2026-05-15T00:17:31.382Z","repository":{"id":339075307,"uuid":"1160371124","full_name":"mauhpr/agentlint-plugin","owner":"mauhpr","description":"Claude Code plugin for AgentLint — real-time quality guardrails for AI coding agents","archived":false,"fork":false,"pushed_at":"2026-04-08T00:25:54.000Z","size":60,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T01:32:23.282Z","etag":null,"topics":["ai-agents","claude-code","claude-code-plugin","guardrails","hooks","linting","python"],"latest_commit_sha":null,"homepage":"https://github.com/mauhpr/agentlint","language":"Shell","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/mauhpr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-17T21:28:50.000Z","updated_at":"2026-04-08T00:25:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mauhpr/agentlint-plugin","commit_stats":null,"previous_names":["mauhpr/agentlint-plugin"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/mauhpr/agentlint-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mauhpr%2Fagentlint-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mauhpr%2Fagentlint-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mauhpr%2Fagentlint-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mauhpr%2Fagentlint-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mauhpr","download_url":"https://codeload.github.com/mauhpr/agentlint-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mauhpr%2Fagentlint-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32315712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T21:09:39.134Z","status":"ssl_error","status_checked_at":"2026-04-26T21:09:21.240Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-agents","claude-code","claude-code-plugin","guardrails","hooks","linting","python"],"created_at":"2026-02-22T18:04:14.767Z","updated_at":"2026-05-15T00:17:31.362Z","avatar_url":"https://github.com/mauhpr.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agentlint — Claude Code Plugin\n\nClaude Code marketplace wrapper for AgentLint's AI-agent guardrail engine. It gives Claude Code native hooks for code quality, security, infrastructure safety, file-scope governance, and CLI tool integration. AgentLint core supports 76 rules across 8 packs; this plugin registers the high-value Claude Code runtime hooks by default.\n\n\u003e **Note:** This repo is intentionally Claude Code-specific because it packages the marketplace plugin. The `agentlint` Python package is multi-agent and supports Claude Code, Cursor, Kimi, Grok, Gemini, Codex, Continue, OpenAI Agents, MCP, and generic HTTP. See the [main repo](https://github.com/mauhpr/agentlint) for those setup paths.\n\n## Prerequisites\n\nInstall the `agentlint` Python package:\n\n```bash\npip install agentlint\n```\n\nFor this 2.3.x plugin release, use AgentLint 2.3.0 or newer.\n\n## Binary resolution\n\nThe plugin automatically resolves the `agentlint` binary at runtime — no PATH configuration needed. It probes, in order: PATH lookup, `~/.local/bin` (pipx), `uv tool` install location, and `python -m agentlint`. This works regardless of how you installed the package.\n\nIf auto-resolution still fails, run `agentlint setup` to register hooks with an absolute path instead.\n\n## Install from GitHub\n\nAdd the marketplace and install:\n\n```bash\nclaude plugin marketplace add mauhpr/agentlint-plugin\nclaude plugin install agentlint@agentlint\n```\n\nFor non-Claude platforms, use the Python package directly. The main AgentLint repo has setup guides for Cursor, Codex, Gemini, Kimi, Grok, Continue, OpenAI Agents SDK, MCP, and generic integrations.\n\n## Install Locally\n\n```bash\nclaude --plugin-dir /path/to/agentlint-plugin\n```\n\n## What it does\n\nAgentLint core supports all 17 Claude Code lifecycle events. This Claude Code plugin registers these runtime hook groups out of the box:\n\n| Event | Behavior |\n|-------|----------|\n| **PreToolUse** | Blocks secrets, `.env` commits, force-pushes, destructive commands, unsafe shell execution, SQL injection. With security pack: blocks Bash file writes and network exfiltration. |\n| **PostToolUse** | Checks file size, tracks edit drift, detects dead imports, warns on error handling removal. **Runs configured CLI tools** (linters, scanners, test runners) via CLI integration. |\n| **SubagentStart** | Injects safety briefing into subagent context. |\n| **SubagentStop** | Audits subagent transcripts for dangerous commands. |\n| **Stop** | Generates quality report with debug artifacts, TODOs, token budget, circuit breaker status. |\n\n## Rule packs\n\n| Pack | Rules | Activates when |\n|------|-------|----------------|\n| **universal** | 23 | Always active |\n| **quality** | 7 | Always active |\n| **python** | 6 | `pyproject.toml` or `setup.py` exists |\n| **frontend** | 8 | `package.json` exists |\n| **react** | 3 | `react` in package.json dependencies |\n| **seo** | 4 | SSR/SSG framework detected |\n| **security** | 7 | Opt-in |\n| **autopilot** | 18 | Opt-in |\n\n## Monorepo Support\n\nDifferent subdirectories can use different packs:\n\n```yaml\nprojects:\n  frontend/:\n    packs: [universal, frontend, react]\n  backend/:\n    packs: [universal, python]\n```\n\nFiles outside project prefixes fall back to global `packs:`. Longest prefix wins.\n\n## Warning Suppression\n\nSuppress noisy warnings for the rest of the session:\n\n```bash\nagentlint suppress drift-detector    # suppress a rule\nagentlint suppress --list            # show suppressed rules\nagentlint suppress --remove drift-detector  # unsuppress one rule\nagentlint suppress --clear           # clear all suppressions\n```\n\nERRORs are never suppressed (safety invariant). Auto-suppress available via `auto_suppress_after: N` config.\n\n## Global Config Defaults\n\nSet defaults that cascade to all rules:\n\n```yaml\nrules:\n  strict_mode: true          # all rules inherit this\n  auto_suppress_after: 5     # auto-suppress after 5 consecutive fires\n  no-secrets:\n    strict_mode: false       # per-rule override\n```\n\n## Session Summary\n\nView cumulative session activity at any time:\n\n```bash\nagentlint report --summary              # text dashboard\nagentlint report --summary --format json # structured output\n```\n\nShows violations (blocked/warnings/info), top rules, files touched, suppressed rules, circuit breaker state, and subagent activity. The Stop report also includes cumulative totals automatically.\n\n## MCP Server\n\nAgents can **pre-validate code before writing**, eliminating the block-retry loop from PreToolUse hooks:\n\n```bash\npip install agentlint[mcp]\n```\n\n**Tools:**\n- `check_content(content, file_path, tool_name?, event?)` — pre-validate code or Bash commands\n- `list_rules(pack?)` — discover available rules\n- `get_config()` — read current configuration\n- `suppress_rule(rule_id)` — suppress a warning rule for the session\n\n**Resources:** `agentlint://rules`, `agentlint://config`\n\nThe MCP server registers automatically when the plugin is enabled (requires `agentlint[mcp]`). See the [full MCP guide](https://github.com/mauhpr/agentlint/blob/main/docs/mcp.md) for workflow recipes and troubleshooting.\n\n## CI Mode\n\nRun agentlint in CI pipelines — same rules, same config:\n\n```bash\nagentlint ci --diff origin/main...HEAD\n```\n\nExit 0 = clean/warnings. Exit 1 = ERROR violations. Use `--format json` for machine-readable output.\n\n## File-Scope Governance\n\nRestrict which files the agent can access:\n\n```yaml\nrules:\n  file-scope:\n    allow: [\"src/**\", \"tests/**\", \"docs/**\"]\n    deny: [\"*.env\", \"credentials/**\", \".github/workflows/**\"]\n```\n\nDeny takes precedence over allow. Blocks Write, Edit, Read, and Bash file operations. Path traversal blocked.\n\n## CLI Integration\n\nRun any command-line tool as a PostToolUse check. Global defaults cascade to all commands:\n\n```yaml\nrules:\n  cli-integration:\n    timeout: 15           # default for all commands\n    diff_only: true       # only report violations on changed lines\n    commands:\n      - name: ruff\n        glob: \"**/*.py\"\n        command: \"ruff check {file.path} --output-format=concise\"\n        timeout: 30       # override for ruff only\n      - name: ruff-format\n        glob: \"**/*.py\"\n        command: \"ruff format {file.path}\"\n        mode: auto-fix    # run silently, apply fix, no warning\n      - name: prettier\n        glob: \"**/*.{ts,tsx,js,jsx}\"\n        command: \"prettier --write {file.path}\"\n        mode: auto-fix\n```\n\n**Modes:** `check` (default — report violations), `auto-fix` (run silently, warn only on failure).\n\n**`diff_only`:** Filters CLI output to only violations on changed lines. Pre-existing violations are suppressed.\n\nTemplate placeholders (`{file.path}`, `{file.stem}`, `{file.dir}`, `{project.dir}`, `{env.VARNAME}`, etc.) resolve from hook context. All values are shell-escaped for security.\n\n## Custom packs\n\nCustom rules are grouped by `pack` attribute. Add the pack name to `packs:` to activate:\n\n```yaml\npacks:\n  - universal\n  - fintech           # custom pack\n\ncustom_rules_dir: .agentlint/rules/\n```\n\nUse `agentlint doctor` to detect orphaned packs.\n\n## Circuit Breaker\n\nWhen a blocking rule fires 3+ times, it degrades from ERROR → WARNING → INFO → suppressed. Security-critical rules (`no-secrets`, `no-env-commit`) are exempt. Auto-resets after 5 clean evaluations or 30 minutes.\n\n## Configuration\n\n```bash\nagentlint init           # Create agentlint.yml\nagentlint setup          # Install hooks\nagentlint doctor         # Diagnose issues\nagentlint list-rules     # Show all rules\nagentlint status         # Version, packs, rule count, project mappings\nagentlint suppress       # Suppress/unsuppress warning rules\nagentlint ci             # Scan changed files for CI\nagentlint-mcp            # Run MCP server (requires agentlint[mcp])\n```\n\nSee [agentlint documentation](https://github.com/mauhpr/agentlint) for full reference.\n\n## Agents\n\n- `/agentlint:security-audit` — Scan codebase for security vulnerabilities\n- `/agentlint:doctor` — Diagnose configuration and hook issues\n- `/agentlint:fix` — Auto-fix common violations with confirmation\n\n## Commands\n\n- `/agentlint:lint-status` — Show active rules and session violations\n- `/agentlint:lint-config` — Show or edit configuration\n\n## Troubleshooting\n\n**Hooks not firing?** Run `claude plugin list` to verify installation.\n\n**`agentlint: command not found`?** Install it (`pip install agentlint`) or run `agentlint setup`.\n\n**Timeouts?** PreToolUse hooks have a 5s timeout. Use `severity: relaxed` for large projects.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmauhpr%2Fagentlint-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmauhpr%2Fagentlint-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmauhpr%2Fagentlint-plugin/lists"}