Show HN: Hands-please – Run local code agents using only code comments

1 week ago 9

hands-please

Watch codebase for // @ai fix this code
Run an agent like Claude Code in the background with the prompt from the comment until lint/build passes

$ npx hands-please@latest --agent 'claude --print --output-format stream-json --verbose --allowedTools "Edit,Write,WebFetch"' --check 'npm run check' --file-check 'npm run lint'

Add a comment:

// @ai add a test case to divide by 0 describe("division", () => { it("should divide 10 by 2", () => { expect(10 / 2).toBe(5); }); });

$ npx hands-please@latest --agent 'claude --print --output-format stream-json --verbose --allowedTools "Edit,Write,WebFetch"' --check 'npm run check' --file-check 'npm run lint' ⠏ Watching for comments with "@ai".... ℹ 🫱 Processing comment src/math.test.ts:194 ℹ 🤖 I'll implement the test case for division by zero as requested in the comment. ℹ 🤖 Added test case that verifies division by zero returns Infinity in JavaScript. ℹ 💸 $0.04 in 12.38s ℹ ✓ $ npm run lint ℹ ✓ $ npm run check ℹ ✓ All checks passed ⠙ Watching files for "@ai"....

hands-please is configured using command line arguments:

# Basic usage npx hands-please --agent <agent-command> --check <check-command> --file-check <file-check-command> [options] # Options: # --agent The command to run the AI agent in non-interactive mode(required) # --check The command to check the codebase (required) # --file-check The command to check specific files (required) # --trigger The tag that triggers comment processing (default: "@ai") # --skip-watch Exit after processing all comments (default: false)

Example for Claude Code:

pnpm dlx hands-please@latest \ --agent 'claude --print --output-format stream-json --verbose --allowedTools "Edit,Write,WebFetch"' \ --check 'pnpm check' \ --file-check 'pnpm lint'

I wanted the productivity of vibe coding without the mess: Running local coding agents with surgical precision based on comments.

There is no chat interface, the only way to interact with the code agents is through code comments.

Workflow:

Pick up a comment containing @ai
Run agent with prompt from comment or linting issues
Run file-check command on changed files, on error go to 2.
Run full codebase check command, on error go to 2.
=> Done! Process next comment.

For hands-please to work well it's important to provide a file-specific check using the --file-check option like eslint that works with eslint <file1> <file2>. This allows hands-please to run checks only on changed files and provide feedback to the code agent that is relevant to the changes it made. => Super fast feedback loop!

aider: For the comment-based code agent
Claude Code: For the DX and the nice auto-mode experience

Read Entire Article