{"id":38345077,"url":"https://github.com/hegner123/checkfor","last_synced_at":"2026-01-17T03:02:40.296Z","repository":{"id":332243706,"uuid":"1133173173","full_name":"hegner123/checkfor","owner":"hegner123","description":"Token-efficient file search tool with JSON output and MCP server support","archived":false,"fork":false,"pushed_at":"2026-01-13T05:07:25.000Z","size":35,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T05:18:52.165Z","etag":null,"topics":["claude-code","cli","cli-tool","developer-tools","file-search","go","golang","json","mcp-server","model-context-protocol","refactoring","search-tool"],"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/hegner123.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-13T01:34:16.000Z","updated_at":"2026-01-13T05:07:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hegner123/checkfor","commit_stats":null,"previous_names":["hegner123/checkfor"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hegner123/checkfor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hegner123%2Fcheckfor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hegner123%2Fcheckfor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hegner123%2Fcheckfor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hegner123%2Fcheckfor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hegner123","download_url":"https://codeload.github.com/hegner123/checkfor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hegner123%2Fcheckfor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28492593,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T02:39:23.645Z","status":"ssl_error","status_checked_at":"2026-01-17T02:34:19.649Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["claude-code","cli","cli-tool","developer-tools","file-search","go","golang","json","mcp-server","model-context-protocol","refactoring","search-tool"],"created_at":"2026-01-17T03:02:36.188Z","updated_at":"2026-01-17T03:02:40.280Z","avatar_url":"https://github.com/hegner123.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# checkfor\n\n[![Tests](https://github.com/hegner123/checkfor/actions/workflows/test.yml/badge.svg)](https://github.com/hegner123/checkfor/actions/workflows/test.yml)\n[![Go Version](https://img.shields.io/badge/go-1.23-blue.svg)](https://go.dev/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Go Report Card](https://goreportcard.com/badge/github.com/hegner123/checkfor)](https://goreportcard.com/report/github.com/hegner123/checkfor)\n\nAn MCP server tool for searching files in directories with compact JSON output. Designed for AI-optimized, token-efficient verification during refactoring workflows.\n\n## Features\n\n- **MCP server by default** - Optimized for Claude Code integration\n- **Multi-directory search** - Search across multiple directories in controlled, single-depth scans\n- **Compact JSON output** - 41% smaller than pretty-printed JSON for maximum token efficiency\n- **Per-directory results** - Organized output with relative paths for better AI reasoning\n- **Exclude filtering** - Filter out unwanted matches with multiple exclude patterns\n- **Filter statistics** - Track original vs filtered match counts per directory\n- **File extension filtering** - Target specific file types\n- **Case-insensitive search** - Optional case-insensitive matching\n- **Whole-word matching** - Avoid false positives from partial matches\n- **Context lines** - Show N lines before/after matches for understanding\n\n## Installation\n\n### 1. Build from source\n\n```bash\ngo build -o checkfor\n```\n\n### 2. Install to PATH (Required for MCP mode)\n\nInstalling checkfor to your system PATH allows MCP server integration with Claude Code.\n\n**System-wide installation** (recommended):\n```bash\nsudo cp checkfor /usr/local/bin/\n```\n\n**User-local installation** (if you don't have sudo access):\n```bash\nmkdir -p ~/bin\ncp checkfor ~/bin/\n# Add ~/bin to PATH if not already (add to ~/.bashrc or ~/.zshrc):\nexport PATH=\"$HOME/bin:$PATH\"\n```\n\nVerify installation:\n```bash\ncheckfor --help\n```\n\n### 3. MCP Server Setup (For Claude Code Integration)\n\nTo use checkfor as an MCP tool in Claude Code:\n\n**Step 1:** Add to your Claude Code MCP configuration (project `.mcp.json` or global `~/.claude/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"checkfor\": {\n      \"command\": \"checkfor\"\n    }\n  }\n}\n```\n\nNote: The `--mcp` flag is no longer needed - MCP mode is now the default behavior.\n\n**Step 2:** Restart Claude Code or reload MCP servers\n\n**Step 3 (Optional but Recommended):** Optimize Claude Code's tool selection\n\nAdd this to your global `~/.claude/CLAUDE.md` to help Claude Code automatically choose checkfor for verification tasks:\n\n```markdown\n## Tool Usage - Search Optimization\n\n### When to use checkfor (MCP tool)\nUse the `checkfor` tool for controlled multi-directory searches at single depth (non-recursive). This tool is optimized for token efficiency with compact JSON output and per-directory results.\n\n**Use checkfor when:**\n- Verifying refactoring completion across multiple packages/directories\n- Checking specific directories for remaining instances of old patterns\n- Searching files without recursing into subdirectories\n- You need minimal, token-efficient output with per-directory statistics\n- Filtering out specific patterns with exclude filters\n\n**Example:**\n\ncheckfor tool with:\n- dir: [\"/path/to/pkg/handlers\", \"/path/to/pkg/models\"] (optional, defaults to current directory)\n- search: \"oldFunctionName\" (required)\n- ext: \".go\" (optional, filters by extension)\n- exclude: [\"oldFunctionNames\", \"testOldFunction\"] (optional, filters out matches)\n- case_insensitive: false (optional)\n- whole_word: false (optional)\n- context: 0 (optional, number of context lines)\n- hide_filter_stats: false (optional, hides original_matches and filtered_matches)\n\n\n### When NOT to use checkfor\n- Recursive/deep directory searches (use Grep instead)\n- Complex regex patterns (use Grep instead)\n- When you need full file content (use Read instead)\n```\n\nThis helps Claude Code automatically choose the most efficient tool for verification tasks.\n\n### 4. Development (Optional)\n\nRun tests to verify your installation:\n\n```bash\ngo test -v\n```\n\nRun tests with coverage:\n\n```bash\ngo test -v -race -coverprofile=\"coverage.out\" -covermode=atomic\n```\n\n## Usage\n\n### MCP Mode (Default)\n\nBy default, checkfor runs as an MCP server:\n\n```bash\ncheckfor\n```\n\nThis starts the MCP server and waits for JSON-RPC requests on stdin. This is the primary mode for Claude Code integration.\n\n### CLI Mode\n\nTo use checkfor in CLI mode (for testing or scripting), add the `--cli` flag:\n\n```bash\ncheckfor --cli --search \u003cstring\u003e [options]\n```\n\n### Required Flags\n\n- `--search` - String to search for\n\n### Optional Flags\n\n- `--cli` - Run in CLI mode (default is MCP server mode)\n- `--dir` - Comma-separated list of directories to search (defaults to current directory)\n- `--ext` - File extension to filter (e.g., `.go`, `.txt`, `.js`)\n- `--exclude` - Comma-separated list of strings to exclude from results\n- `--case-insensitive` - Perform case-insensitive search\n- `--whole-word` - Match whole words only\n- `--context` - Number of context lines before and after each match (default: 0)\n- `--hide-filter-stats` - Hide original_matches and filtered_matches from output\n\n## Examples\n\n### Basic search (current directory)\n```bash\ncheckfor --cli --search \"oldFunctionName\"\n```\n\n### Search specific directory\n```bash\ncheckfor --cli --dir ./src --search \"oldFunctionName\"\n```\n\n### Search multiple directories\n```bash\ncheckfor --cli --dir \"./pkg/handlers,./pkg/models,./pkg/services\" --search \"UserModel\" --ext .go\n```\n\n### Search with exclude filter\n```bash\ncheckfor --cli --dir ./pkg --search \"m.Table\" --exclude \"m.Tables,m.TableName\" --ext .go\n```\n\n### Case-insensitive search\n```bash\ncheckfor --cli --search \"todo\" --case-insensitive\n```\n\n### Whole word matching\n```bash\ncheckfor --cli --search \"log\" --whole-word --ext .go\n```\n\n### With context lines\n```bash\ncheckfor --cli --dir ./services --search \"deprecated\" --context 2\n```\n\n### Hide filter statistics\n```bash\ncheckfor --cli --search \"old\" --exclude \"older\" --hide-filter-stats\n```\n\n## Best Practices\n\n- **Plan verification steps:** Include specific checkfor searches in your refactoring plans\n- **Verify incrementally:** Check progress after each major change\n- **Track progress per directory:** Use per-directory match counts to see which packages are clean\n- **Use exclude filters:** Filter out known false positives or related patterns\n- **Monitor filter stats:** Track `original_matches` vs `filtered_matches` to verify exclude patterns work correctly\n- **Use whole-word matching:** Add `--whole-word` flag to avoid false positives from similar names\n- **Add context when needed:** Use `--context 1` or `--context 2` to understand surrounding code\n\n## Output Format\n\nThe tool outputs compact JSON with per-directory results for optimal AI consumption:\n\n### Single Directory\n\n```json\n{\"directories\":[{\"dir\":\".\",\"matches_found\":2,\"files\":[{\"path\":\"handler.go\",\"matches\":[{\"line\":42,\"content\":\"  result := oldFunctionName()\"}]}]}]}\n```\n\n### Multiple Directories with Exclude Filter\n\n```json\n{\"directories\":[{\"dir\":\"./pkg/handlers\",\"matches_found\":3,\"original_matches\":5,\"filtered_matches\":2,\"files\":[{\"path\":\"user.go\",\"matches\":[{\"line\":42,\"content\":\"m.Table(\\\"users\\\")\"}]}]},{\"dir\":\"./pkg/models\",\"matches_found\":0,\"files\":[]}]}\n```\n\n### Pretty-printed Example (for documentation)\n\n```json\n{\n  \"directories\": [\n    {\n      \"dir\": \"./pkg/handlers\",\n      \"matches_found\": 2,\n      \"original_matches\": 4,\n      \"filtered_matches\": 2,\n      \"files\": [\n        {\n          \"path\": \"handler.go\",\n          \"matches\": [\n            {\n              \"line\": 42,\n              \"content\": \"  result := oldFunctionName()\",\n              \"context_before\": [\n                \"func processRequest() {\",\n                \"  // Process the request\"\n              ],\n              \"context_after\": [\n                \"  return result\",\n                \"}\"\n              ]\n            }\n          ]\n        }\n      ]\n    },\n    {\n      \"dir\": \"./pkg/models\",\n      \"matches_found\": 0,\n      \"files\": []\n    }\n  ]\n}\n```\n\n### Output Fields\n\n**Per Directory:**\n- `dir` - Directory path\n- `matches_found` - Total matches in this directory after filtering\n- `original_matches` - Total matches before filtering (only when exclude is used and not hidden)\n- `filtered_matches` - Number of matches filtered out (only when exclude is used and not hidden)\n- `files` - Array of files with matches (relative paths)\n\n**Per File:**\n- `path` - File path relative to directory\n- `matches` - Array of match objects\n\n**Per Match:**\n- `line` - Line number\n- `content` - Line content\n- `context_before` - Lines before match (if --context specified)\n- `context_after` - Lines after match (if --context specified)\n\n## Performance\n\ncheckfor is designed for token efficiency during AI-assisted refactoring workflows:\n\n### Token Savings\n\n- **Compact JSON:** 41% smaller than pretty-printed JSON\n- **Relative paths:** 68% reduction in path data for multi-file results\n- **Per-directory structure:** Direct access to statistics without parsing\n\n### Real-World Comparison\n\nIn a multi-phase refactoring session:\n\n- **~8,000 tokens** used with checkfor\n- **~155,250 tokens** would have been used with Read tool (19.4x more efficient)\n- **~35,100 tokens** would have been used with Grep tool (4.4x more efficient)\n\nThis efficiency prevented exceeding the 200K token context limit and enabled completion in a single session, saving approximately $1.77 in API costs.\n\n**Key benefits:**\n- 95% token reduction vs Read tool\n- 77% token reduction vs Grep tool\n- 41% reduction via compact JSON output\n- 68% path data reduction via relative paths\n- 3-5x faster response time\n- Near-zero error rate with exact counts\n- Better AI reasoning with per-directory results\n\nSee [detailed case study](docs/CASE_STUDY.md) for full analysis with real-world data.\n\n## Architecture\n\n- **Default mode:** MCP server (JSON-RPC 2.0 over stdin/stdout)\n- **CLI mode:** Direct JSON output (requires `--cli` flag)\n- **Single-depth:** Non-recursive scanning per directory\n- **Multi-directory:** Controlled searches across specific directories\n- **Per-directory results:** Organized output with directory-specific statistics\n\n## Exit Codes\n\n- `0` - Success (matches found or not)\n- `1` - Error (invalid arguments, directory not found, etc.)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhegner123%2Fcheckfor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhegner123%2Fcheckfor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhegner123%2Fcheckfor/lists"}