{"id":43258594,"url":"https://github.com/pthm/cclint","last_synced_at":"2026-02-01T14:02:13.093Z","repository":{"id":332190803,"uuid":"1132621665","full_name":"pthm/cclint","owner":"pthm","description":"A linter for Claude Code configurations. Analyzes CLAUDE.md files, .claude/ directories, and related configuration files to identify issues","archived":false,"fork":false,"pushed_at":"2026-01-12T23:29:40.000Z","size":130,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T00:48:29.443Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/pthm.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-01-12T08:13:37.000Z","updated_at":"2026-01-12T23:29:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pthm/cclint","commit_stats":null,"previous_names":["pthm/cclint"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/pthm/cclint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pthm%2Fcclint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pthm%2Fcclint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pthm%2Fcclint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pthm%2Fcclint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pthm","download_url":"https://codeload.github.com/pthm/cclint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pthm%2Fcclint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28980159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T13:38:33.235Z","status":"ssl_error","status_checked_at":"2026-02-01T13:38:32.912Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":[],"created_at":"2026-02-01T14:02:12.283Z","updated_at":"2026-02-01T14:02:13.086Z","avatar_url":"https://github.com/pthm.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"128\" alt=\"cclint\" src=\"https://github.com/user-attachments/assets/ed1ff742-1f80-4ff3-87ba-81802b70fd96\" /\u003e\n\n# cclint\n\nA comprehensive linter and analyzer for [Claude Code](https://claude.com/code) configurations. Keep your agent instructions clean, consistent, and effective by catching issues before they impact your workflow.\n\n## Why cclint?\n\nAs your Claude Code configurations grow—spanning `CLAUDE.md` files, `.claude/` directories, nested commands, skills, and subagents—it becomes increasingly difficult to:\n- Track which files are actually being loaded into context\n- Spot broken references, circular dependencies, or duplicate instructions\n- Ensure instructions are clear, actionable, and conflict-free\n- Estimate token usage and optimize context size\n- Understand the full scope of what each agent sees\n\n**cclint solves this** by analyzing your entire configuration graph, providing automated checks, interactive visualization, and intelligent insights.\n\n## Features\n\n### 1. Catch Configuration Issues Early\n\nAutomated linting rules detect common problems across structural, content quality, and AI-powered categories:\n\n**Structural Issues**\n- Broken file references and URLs\n- Circular dependencies\n- Missing entrypoints for commands and skills\n- Overly broad file permissions\n- Missing tool or skill declarations\n\n**Content Quality**\n- Vague or unclear instructions\n- Contradictory guidance\n- Missing critical context\n- Excessive verbosity\n\n**AI-Powered Analysis** (via `--deep` flag)\n- Duplicate instructions across scopes\n- Subtle contradictions in guidance\n- Clarity and actionability scoring\n\n\u003cimg width=\"1664\" height=\"720\" alt=\"CleanShot 2026-01-12 at 11 56 23@2x\" src=\"https://github.com/user-attachments/assets/75566cdb-7ebb-41a8-acc2-a6cde0acecde\" /\u003e\n\n### 2. Visualize Configuration Hierarchies\n\nThe interactive graph browser provides a complete view of your configuration structure:\n- Navigate through main agent, subagents, commands, and skills\n- See which files are loaded in each scope\n- Track references between files\n- Understand inheritance and nesting\n- Preview file contents inline\n\n\u003cimg width=\"3302\" height=\"1874\" alt=\"CleanShot 2026-01-12 at 11 54 02@2x\" src=\"https://github.com/user-attachments/assets/b8c08482-8915-43f0-8eac-5ccad650a495\" /\u003e\n\n### 3. Understand Context Usage\n\nGenerate detailed reports showing:\n- Reference maps across all configuration files\n- Token usage estimates per scope\n- File category breakdown\n- Reference types (files, URLs, tools, MCP servers, skills)\n\n### 4. Auto-Fix Common Issues\n\nAutomatically resolve fixable problems with:\n- Standard auto-fixes for structural issues\n- AI-assisted fixes (via `--ai` flag) for content improvements\n- Dry-run mode to preview changes\n\n\n## Installation\n\n### Homebrew\n\n```bash\nbrew install pthm/tap/cclint\n```\n\n### Go Install\n\n```bash\ngo install github.com/pthm/cclint/cmd/cclint@latest\n```\n\n## Quick Start\n\n```bash\n# Lint your configuration\ncclint lint .\n\n# View the interactive configuration graph\ncclint graph .\n\n# Generate a detailed report\ncclint report .\n```\n\n## Usage\n\n### Lint Command\n\nCheck your configurations for issues:\n\n```bash\n# Basic linting (structural + content quality rules)\ncclint lint\n\n# Deep analysis with AI-powered rules (requires Claude API)\ncclint lint --deep\n\n# Lint specific directory\ncclint lint /path/to/project\n\n# Output as JSON\ncclint lint --format json\n\n# Specify agent type (default: claude-code)\ncclint lint --agent claude-code\n```\n\n### Graph Command\n\nExplore your configuration hierarchy interactively:\n\n```bash\n# Launch interactive graph browser\ncclint graph\n\n# Print tree to stdout (non-interactive)\ncclint graph --print\n\n# Specify directory\ncclint graph /path/to/project\n```\n\n**Interactive Controls:**\n- `↑/k`, `↓/j` - Navigate up/down\n- `←/h`, `→/l` - Collapse/expand nodes\n- `Enter`/`Space` - Toggle expand/collapse\n- `r` - Toggle reference display\n- `s` - Toggle scope grouping\n- `q` - Quit\n\n### Report Command\n\nGenerate comprehensive configuration reports:\n\n```bash\n# Generate report with metrics and references\ncclint report\n\n# Output as JSON for programmatic use\ncclint report --format json \u003e report.json\n```\n\n### Fix Command\n\nAutomatically fix issues:\n\n```bash\n# Auto-fix standard issues\ncclint fix\n\n# Preview fixes without applying (dry-run)\ncclint fix --dry-run\n\n# Enable AI-assisted fixes for content issues\ncclint fix --ai\n\n# Combine dry-run with AI fixes\ncclint fix --ai --dry-run\n```\n\n### Version Command\n\n```bash\ncclint version\n```\n\n## How It Works\n\ncclint understands the full context hierarchy of Claude Code configurations:\n\n1. **Agent-Aware Parsing** - Loads agent profiles (like `claude-code.yaml`) that define entrypoints, reference patterns, and priority markers\n2. **Scope Discovery** - Identifies distinct scopes: main agent, subagents, commands, and skills—each with their own context boundaries\n3. **Reference Tracking** - Follows file references, URLs, tool declarations, MCP server connections, and skill invocations up to 5 levels deep\n4. **Intelligent Analysis** - Runs both heuristic and LLM-based rules that understand the semantic meaning of your instructions\n5. **Context-Aware Reporting** - Provides insights specific to each scope, helping you understand what each agent actually sees\n\n## Common Use Cases\n\n- **Pre-commit checks** - Catch issues before they're committed\n- **Debugging context** - Understand why an agent isn't seeing certain instructions\n- **Token optimization** - Identify and reduce bloated configurations\n- **Team collaboration** - Ensure consistent, high-quality agent configurations\n- **Configuration refactoring** - Safely reorganize complex setups with confidence\n\n## Development\n\nSee [CLAUDE.md](CLAUDE.md) for:\n- Build and development commands\n- Architecture overview\n- How to add custom linting rules\n- Testing and contribution guidelines\n\n## Roadmap\n\nThis is an active project. Planned features include:\n- Additional linting rules\n- Performance optimizations for large codebases\n- CI/CD integration examples\n- Configuration migration tools\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpthm%2Fcclint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpthm%2Fcclint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpthm%2Fcclint/lists"}