https://github.com/elct9620/ccharness
A lightweight harness for Claude Code
https://github.com/elct9620/ccharness
claude-code
Last synced: about 2 months ago
JSON representation
A lightweight harness for Claude Code
- Host: GitHub
- URL: https://github.com/elct9620/ccharness
- Owner: elct9620
- License: mit
- Created: 2025-08-30T12:17:43.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-10-08T12:36:05.000Z (9 months ago)
- Last Synced: 2025-10-08T14:37:19.335Z (9 months ago)
- Topics: claude-code
- Language: TypeScript
- Homepage:
- Size: 431 KB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Claude Code Harness
[](https://codecov.io/gh/elct9620/ccharness)
A set of lightweight tools for Claude Code users to improve their experience.
> [!WARNING]
> The hook is dangerous. Please review the code before using it, or fork and modify it to suit your needs.
## Usage
Use `npx -y @aotoki/ccharness ` to run commands without installing globally.
### Hooks
Create a new hook in Claude Code with specified hook.
```json
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "npx -y @aotoki/ccharness hook guard-commit"
}
]
}
]
}
}
```
## Commands
Following commands are available to help your Claude Code workflow.
## Hooks
### Guard Commit
A `Stop` hook to ensure Claude Code make a commit when throttled.
```bash
npx -y @aotoki/ccharness hook guard-commit
```
Options:
- `-f`, `--max-files `: When exceeding the number of changed files, ask Claude Code to commit. Default is `-1` (disabled).
- `-l`, `--max-lines `: When exceeding the number of changed lines, ask Claude Code to commit. Default is `-1` (disabled).
### Review Reminder
A `PostToolUse` hook for `Write`, `Edit`, `MultiEdit` tool to remind Claude Code to review with rubric(s).
```bash
npx -y @aotoki/ccharness hook review-reminder
```
Options:
- `-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`.
> Currently, we only add context to remind agent we have rubric document, and use it to review the changes.
### Commit Reminder
A `PostToolUse` hook for `Write`, `Edit`, `MultiEdit` tools to remind Claude Code to commit when too many changes are made.
```bash
npx -y @aotoki/ccharness hook commit-reminder
```
Options:
- `-f`, `--max-files `: The maximum number of files to trigger a commit reminder, use -1 to disable. Default is `-1` (disabled).
- `-l`, `--max-lines `: The maximum number of lines changed to trigger a commit reminder, use -1 to disable. Default is `-1` (disabled).
**Hook Configuration:**
Add this hook to your Claude Code settings:
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "npx -y @aotoki/ccharness hook commit-reminder"
}
]
}
]
}
}
```
This 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.
### Audit Read
A `PreToolUse` hook for the `Read` tool to restrict Claude Code's access to sensitive files.
```bash
npx -y @aotoki/ccharness hook audit-read
```
This 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.
**Hook Configuration:**
Add this hook to your Claude Code settings:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Read",
"hooks": [
{
"type": "command",
"command": "npx -y @aotoki/ccharness hook audit-read"
}
]
}
]
}
}
```
## Review (Experimental)
Review a file against configured rubrics to get evaluation scores and feedback.
```bash
npx -y @aotoki/ccharness review [options]
```
Arguments:
- ``: Path to the file to review against configured rubrics
Options:
- `--max-retry `: Maximum number of retry attempts if the review encounters errors. Default is `3`.
Example:
```bash
# Review with custom retry limit
npx -y @aotoki/ccharness review src/main.ts --max-retry 5
```
This 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.
> [!NOTE]
> Currently, the prompt for Claude Code cannot ensure output format. It may not work as expected after multiple retries.
## Configuration
CCharness supports configuration through JSON files in your project root:
### Configuration Files
- **`ccharness.json`**: Project-wide configuration that should be committed to version control
- **`ccharness.local.json`**: Local overrides for personal preferences (ignored by git)
When both files exist, `ccharness.local.json` settings will override `ccharness.json` settings.
### Configuration Schema
```json
{
"commit": {
"maxFiles": 10,
"maxLines": 500,
"reminder": {
"maxFiles": 5,
"maxLines": 50,
"message": "You have changed {changedFiles} files and {changedLines} lines without committing. Consider making a commit to save your progress."
}
},
"review": {
"blockMode": false
},
"audit": {
"read": [
"path/to/sensitive/file.txt",
"logs/*.log"
]
},
"rubrics": [
{
"name": "vitest",
"pattern": "test/.*\\.test\\.ts$",
"path": "docs/rubrics/vitest.md"
}
]
}
```
### Configuration Precedence
Settings are resolved in the following order (highest to lowest priority):
1. Command-line options (e.g., `--max-files`, `--max-lines`)
2. `ccharness.local.json` (local overrides)
3. `ccharness.json` (project defaults)
4. Built-in defaults