@mrkaran/hodor 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +43 -47
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -9,89 +9,85 @@ Hodor runs as a stateful agent with tools (`bash`, `grep`, `read`, `git diff`) t
9
9
  ## Install
10
10
 
11
11
  ```bash
12
- # npx (zero install, always latest)
12
+ # Just run it (zero install, always latest)
13
13
  npx @mrkaran/hodor <PR_URL>
14
14
 
15
- # Global install
15
+ # Or install globally
16
16
  npm install -g @mrkaran/hodor
17
+ ```
18
+
19
+ Docker images are also available at `ghcr.io/mr-karan/hodor:latest` for CI environments.
17
20
 
18
- # Docker
19
- docker pull ghcr.io/mr-karan/hodor:latest
21
+ ## Setup
20
22
 
21
- # From source
22
- git clone https://github.com/mr-karan/hodor && cd hodor
23
- bun install && bun run build
23
+ ```bash
24
+ # Set an API key for your LLM provider
25
+ export ANTHROPIC_API_KEY=sk-... # Anthropic (default)
26
+ export OPENAI_API_KEY=sk-... # OpenAI
27
+ export AWS_PROFILE=default # AWS Bedrock (no API key needed)
28
+
29
+ # For posting reviews as comments
30
+ gh auth login # GitHub
31
+ glab auth login # GitLab
24
32
  ```
25
33
 
26
34
  ## Usage
27
35
 
28
36
  ```bash
29
37
  # Review a GitHub PR
30
- hodor https://github.com/owner/repo/pull/123
38
+ npx @mrkaran/hodor https://github.com/owner/repo/pull/123
31
39
 
32
40
  # Review a GitLab MR (including self-hosted)
33
- hodor https://gitlab.example.com/org/project/-/merge_requests/42
41
+ npx @mrkaran/hodor https://gitlab.example.com/org/project/-/merge_requests/42
34
42
 
35
- # Post the review as a comment
36
- hodor <PR_URL> --post
43
+ # Post the review as a PR/MR comment
44
+ npx @mrkaran/hodor <PR_URL> --post
37
45
 
38
46
  # Review local changes (no PR URL needed)
39
- hodor --local # diff against origin/main
40
- hodor --local --diff-against HEAD~1 # diff against specific ref
41
- hodor --local --diff-against feature-branch
47
+ npx @mrkaran/hodor --local # diff against origin/main
48
+ npx @mrkaran/hodor --local --diff-against HEAD~1 # diff against specific ref
42
49
 
43
50
  # Use a different model
44
- hodor <PR_URL> --model openai/gpt-5
45
- hodor <PR_URL> --model bedrock/converse/anthropic.claude-sonnet-4-5-v2
51
+ npx @mrkaran/hodor <PR_URL> --model openai/gpt-5
52
+ npx @mrkaran/hodor <PR_URL> --model bedrock/converse/anthropic.claude-sonnet-4-5-v2
46
53
 
47
54
  # Extended reasoning for complex PRs
48
- hodor <PR_URL> --reasoning-effort high
49
- hodor <PR_URL> --ultrathink
55
+ npx @mrkaran/hodor <PR_URL> --reasoning-effort high
50
56
 
51
57
  # Custom review instructions
52
- hodor <PR_URL> --prompt "Focus on SQL injection and auth bypasses"
53
- hodor <PR_URL> --prompt-file .hodor/security-review.md
58
+ npx @mrkaran/hodor <PR_URL> --prompt "Focus on SQL injection and auth bypasses"
54
59
 
55
60
  # Verbose mode (watch the agent think)
56
- hodor <PR_URL> -v
57
- ```
58
-
59
- **Docker:**
60
- ```bash
61
- docker run --rm \
62
- -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
63
- -e GITHUB_TOKEN=$GITHUB_TOKEN \
64
- ghcr.io/mr-karan/hodor:latest \
65
- https://github.com/owner/repo/pull/123 --post
61
+ npx @mrkaran/hodor <PR_URL> -v
66
62
  ```
67
63
 
68
- ## Configuration
64
+ > If you installed globally with `npm install -g`, replace `npx @mrkaran/hodor` with `hodor`.
69
65
 
70
- ### CLI Flags
66
+ ## CLI Flags
71
67
 
72
68
  | Flag | Default | Description |
73
69
  |------|---------|-------------|
74
- | `--model` | `anthropic/claude-sonnet-4-5` | LLM model (Anthropic, OpenAI, or Bedrock) |
70
+ | `--model` | `anthropic/claude-sonnet-4-5-20250929` | LLM model (Anthropic, OpenAI, or Bedrock) |
75
71
  | `--reasoning-effort` | – | Extended thinking: `low`, `medium`, `high` |
76
72
  | `--ultrathink` | Off | Maximum reasoning effort |
77
- | `--local` | Off | Review local changes (no PR URL required) |
78
- | `--diff-against` | `origin/main` | Git ref to diff against in local mode |
79
- | `--post` | Off | Post review comment to GitHub/GitLab |
73
+ | `--local` | Off | Review local git changes (no PR URL required) |
74
+ | `--diff-against` | `origin/main` | Git ref to diff against in `--local` mode |
75
+ | `--post` | Off | Post review as a comment on the PR/MR |
80
76
  | `--prompt` | – | Append custom instructions to the review prompt |
81
- | `--prompt-file` | – | Replace the review prompt entirely |
82
- | `--workspace` | Temp dir | Workspace directory (re-use for faster multi-PR reviews) |
77
+ | `--prompt-file` | – | Use a custom prompt file |
78
+ | `--workspace` | Temp dir | Workspace directory (reuse for faster multi-PR reviews) |
83
79
  | `--bedrock-tags` | – | JSON cost allocation tags for AWS Bedrock |
84
- | `--prometheus-push` | – | Push metrics to a Prometheus Pushgateway URL |
80
+ | `--prometheus-push` | – | Push review metrics to a Prometheus Pushgateway |
85
81
  | `-v, --verbose` | Off | Stream agent reasoning and tool calls |
86
82
 
87
- ### Environment Variables
83
+ ## Environment Variables
88
84
 
89
85
  | Variable | Purpose |
90
86
  |----------|---------|
91
87
  | `ANTHROPIC_API_KEY` | Claude API key |
92
88
  | `OPENAI_API_KEY` | OpenAI API key |
93
- | `LLM_API_KEY` | Generic fallback (used when provider-specific key is not set) |
94
- | `GITHUB_TOKEN` / `GITLAB_TOKEN` | Post comments to PRs/MRs (only with `--post`) |
89
+ | `LLM_API_KEY` | Generic fallback (when provider-specific key is not set) |
90
+ | `GITHUB_TOKEN` / `GITLAB_TOKEN` | Post comments to PRs/MRs (with `--post`) |
95
91
  | `AWS_PROFILE` or `AWS_ACCESS_KEY_ID` | AWS Bedrock auth (no API key needed) |
96
92
 
97
93
  ## CI/CD
@@ -129,19 +125,19 @@ hodor-review:
129
125
  extends: .hodor-review
130
126
  ```
131
127
 
132
- See [AUTOMATED_REVIEWS.md](./docs/AUTOMATED_REVIEWS.md) for advanced workflows.
128
+ See [AUTOMATED_REVIEWS.md](./docs/AUTOMATED_REVIEWS.md) for advanced CI workflows.
133
129
 
134
130
  ## Token Optimization
135
131
 
136
132
  Hodor automatically optimizes token usage:
137
133
 
138
- - **Diff embedding**: For PRs under 200KB, the diff is embedded directly in the prompt, cutting turns from ~60 to ~5.
139
- - **Incremental reviews**: On re-runs, only reviews changes since the last hodor comment (detected via SHA markers).
140
- - **Compaction**: SDK auto-summarizes older turns when context grows too large.
134
+ - **Diff embedding**: For PRs under 200KB, the diff is embedded directly in the prompt, cutting agent turns from ~60 to ~5.
135
+ - **Incremental reviews**: On re-runs, only reviews changes since the last hodor comment (detected via SHA markers in posted comments).
136
+ - **Compaction**: SDK auto-summarizes older conversation turns when context grows too large.
141
137
 
142
138
  ## Skills
143
139
 
144
- Hodor discovers repository-specific review guidelines from `.pi/skills/` or `.hodor/skills/`. Create a skill file to enforce conventions:
140
+ Hodor discovers repository-specific review guidelines from `.pi/skills/` or `.hodor/skills/`:
145
141
 
146
142
  ```bash
147
143
  mkdir -p .hodor/skills/review-guidelines
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "publishConfig": {
4
4
  "access": "public"
5
5
  },
6
- "version": "0.4.1",
6
+ "version": "0.5.0",
7
7
  "description": "AI-powered code review agent that finds bugs, security issues, and logic errors in pull requests",
8
8
  "type": "module",
9
9
  "main": "dist/index.js",