{"id":49407966,"url":"https://github.com/elct9620/ccharness","last_synced_at":"2026-04-28T22:35:59.818Z","repository":{"id":312417834,"uuid":"1047435399","full_name":"elct9620/ccharness","owner":"elct9620","description":"A lightweight harness for Claude Code","archived":false,"fork":false,"pushed_at":"2025-10-08T12:36:05.000Z","size":441,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-08T14:37:19.335Z","etag":null,"topics":["claude-code"],"latest_commit_sha":null,"homepage":"","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/elct9620.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2025-08-30T12:17:43.000Z","updated_at":"2025-10-08T12:36:09.000Z","dependencies_parsed_at":"2025-08-30T14:26:50.437Z","dependency_job_id":"b8841a32-83a8-407b-9c94-7eca99943eb2","html_url":"https://github.com/elct9620/ccharness","commit_stats":null,"previous_names":["elct9620/ccharness"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/elct9620/ccharness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elct9620%2Fccharness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elct9620%2Fccharness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elct9620%2Fccharness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elct9620%2Fccharness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elct9620","download_url":"https://codeload.github.com/elct9620/ccharness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elct9620%2Fccharness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32402672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"ssl_error","status_checked_at":"2026-04-28T19:37:55.688Z","response_time":56,"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":["claude-code"],"created_at":"2026-04-28T22:35:59.275Z","updated_at":"2026-04-28T22:35:59.807Z","avatar_url":"https://github.com/elct9620.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code Harness\n\n[![codecov](https://codecov.io/gh/elct9620/ccharness/graph/badge.svg?token=C0FMNBUTA9)](https://codecov.io/gh/elct9620/ccharness)\n\nA set of lightweight tools for Claude Code users to improve their experience.\n\n\u003e [!WARNING]\n\u003e The hook is dangerous. Please review the code before using it, or fork and modify it to suit your needs.\n\n## Usage\n\nUse `npx -y @aotoki/ccharness \u003ccommand\u003e` to run commands without installing globally.\n\n### Hooks\n\nCreate a new hook in Claude Code with specified hook.\n\n```json\n{\n  \"hooks\": {\n    \"Stop\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"npx -y @aotoki/ccharness hook guard-commit\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n## Commands\n\nFollowing commands are available to help your Claude Code workflow.\n\n## Hooks\n\n### Guard Commit\n\nA `Stop` hook to ensure Claude Code make a commit when throttled.\n\n```bash\nnpx -y @aotoki/ccharness hook guard-commit\n```\n\nOptions:\n\n- `-f`, `--max-files \u003cnumber\u003e`: When exceeding the number of changed files, ask Claude Code to commit. Default is `-1` (disabled).\n- `-l`, `--max-lines \u003cnumber\u003e`: When exceeding the number of changed lines, ask Claude Code to commit. Default is `-1` (disabled).\n\n### Review Reminder\n\nA `PostToolUse` hook for `Write`, `Edit`, `MultiEdit` tool to remind Claude Code to review with rubric(s).\n\n```bash\nnpx -y @aotoki/ccharness hook review-reminder\n```\n\nOptions:\n\n- `-b`, `--block`: Block execution instead of providing additional context. When enabled, the hook will block Claude Code from proceeding until the review is addressed. Default is `false`.\n\n\u003e Currently, we only add context to remind agent we have rubric document, and use it to review the changes.\n\n### Commit Reminder\n\nA `PostToolUse` hook for `Write`, `Edit`, `MultiEdit` tools to remind Claude Code to commit when too many changes are made.\n\n```bash\nnpx -y @aotoki/ccharness hook commit-reminder\n```\n\nOptions:\n\n- `-f`, `--max-files \u003cnumber\u003e`: The maximum number of files to trigger a commit reminder, use -1 to disable. Default is `-1` (disabled).\n- `-l`, `--max-lines \u003cnumber\u003e`: The maximum number of lines changed to trigger a commit reminder, use -1 to disable. Default is `-1` (disabled).\n\n**Hook Configuration:**\n\nAdd this hook to your Claude Code settings:\n\n```json\n{\n  \"hooks\": {\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Write|Edit|MultiEdit\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"npx -y @aotoki/ccharness hook commit-reminder\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nThis hook monitors file changes after write operations and provides reminders to commit when the number of changed files or lines exceeds configured thresholds, helping maintain good commit hygiene.\n\n### Audit Read\n\nA `PreToolUse` hook for the `Read` tool to restrict Claude Code's access to sensitive files.\n\n```bash\nnpx -y @aotoki/ccharness hook audit-read\n```\n\nThis hook prevents Claude Code from reading files that match configured sensitive patterns. When a restricted file is accessed, the hook denies permission and explains the reason.\n\n**Hook Configuration:**\n\nAdd this hook to your Claude Code settings:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Read\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"npx -y @aotoki/ccharness hook audit-read\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n## Review (Experimental)\n\nReview a file against configured rubrics to get evaluation scores and feedback.\n\n```bash\nnpx -y @aotoki/ccharness review \u003cpath\u003e [options]\n```\n\nArguments:\n\n- `\u003cpath\u003e`: Path to the file to review against configured rubrics\n\nOptions:\n\n- `--max-retry \u003cnumber\u003e`: Maximum number of retry attempts if the review encounters errors. Default is `3`.\n\nExample:\n\n```bash\n# Review with custom retry limit\nnpx -y @aotoki/ccharness review src/main.ts --max-retry 5\n```\n\nThis command matches the file against rubric patterns defined in `ccharness.json` and provides evaluation results with scores and comments. If the review fails due to temporary errors, it will automatically retry up to the specified number of times.\n\n\u003e [!NOTE]\n\u003e Currently, the prompt for Claude Code cannot ensure output format. It may not work as expected after multiple retries.\n\n## Configuration\n\nCCharness supports configuration through JSON files in your project root:\n\n### Configuration Files\n\n- **`ccharness.json`**: Project-wide configuration that should be committed to version control\n- **`ccharness.local.json`**: Local overrides for personal preferences (ignored by git)\n\nWhen both files exist, `ccharness.local.json` settings will override `ccharness.json` settings.\n\n### Configuration Schema\n\n```json\n{\n  \"commit\": {\n    \"maxFiles\": 10,\n    \"maxLines\": 500,\n    \"reminder\": {\n      \"maxFiles\": 5,\n      \"maxLines\": 50,\n      \"message\": \"You have changed {changedFiles} files and {changedLines} lines without committing. Consider making a commit to save your progress.\"\n    }\n  },\n  \"review\": {\n    \"blockMode\": false\n  },\n  \"audit\": {\n    \"read\": [\n      \"path/to/sensitive/file.txt\",\n      \"logs/*.log\"\n    ]\n  },\n  \"rubrics\": [\n    {\n      \"name\": \"vitest\",\n      \"pattern\": \"test/.*\\\\.test\\\\.ts$\",\n      \"path\": \"docs/rubrics/vitest.md\"\n    }\n  ]\n}\n```\n\n### Configuration Precedence\n\nSettings are resolved in the following order (highest to lowest priority):\n\n1. Command-line options (e.g., `--max-files`, `--max-lines`)\n2. `ccharness.local.json` (local overrides)\n3. `ccharness.json` (project defaults)\n4. Built-in defaults\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felct9620%2Fccharness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felct9620%2Fccharness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felct9620%2Fccharness/lists"}