Githuman

When to use

Use this skill whenever you are working with GitHuman to review AI-generated code changes before committing them. GitHuman provides a web interface for visual code review with inline comments, suggestions, and todo management.

How to use

Read individual rule files for detailed explanations and examples:

• rules/installation.md - Installing and running GitHuman
• rules/review-workflow.md - Complete workflow for reviewing AI-generated changes
• rules/staging.md - Staging files for review directly in GitHuman
• rules/cli-commands.md - All CLI commands with examples
• rules/todos.md - Managing todos and follow-up tasks
• rules/comments.md - Adding inline comments and suggestions to code
• rules/export.md - Exporting reviews for documentation
• rules/tips.md - Best practices and productivity tips

CLI Commands

Complete reference for all GitHuman CLI commands.

serve

Start the web interface for visual code review.

npx githuman serve

Options:

• --port <number> - Use a custom port (default: 3847)
• --no-open - Don't open the browser automatically

list

List all reviews in the current repository.

npx githuman list

Shows review ID, status, creation date, and file count.

resolve

Mark a review as approved and resolve all comments.

# Resolve a specific review by ID
npx githuman resolve abc123

# Resolve the most recent review
npx githuman resolve last

export

Export a review to markdown for documentation.

# Export to stdout
npx githuman export last

# Export to a file
npx githuman export last -o review.md

# Export a specific review
npx githuman export abc123 -o review-abc123.md

todo

Manage todos for follow-up work.

# List all pending todos
npx githuman todo list

# Add a new todo
npx githuman todo add "Refactor the auth module"

# Mark a todo as done
npx githuman todo done 1

# Show all todos including completed
npx githuman todo list --all

help

Show help for any command.

npx githuman --help
npx githuman serve --help
npx githuman todo --help

Comments and Suggestions

Add inline comments and suggestions to code during review.

Adding Comments

Inline Comments

Click on any line in the diff view to add a comment. Comments are attached to specific lines and will show in context.

Comment Types

• Question - Ask for clarification about the code
• Note - Leave information for future reference
• Suggestion - Propose a code change
• Issue - Flag a problem that needs attention

Suggestions

Suggestions allow you to propose specific code changes:

1. Click on the line you want to change 2. Select "Suggestion" as the comment type 3. Write the suggested replacement code 4. The reviewer can apply the suggestion directly

Resolving Comments

Comments can be resolved in two ways:

1. Individually - Click the resolve button on each comment 2. All at once - Run npx githuman resolve last to mark the review as approved and resolve all comments

Best Practices

1. Be specific - Reference exact variable names, functions, or patterns 2. Explain why - Don't just say "change this", explain the reasoning 3. Use suggestions for simple fixes - If you know exactly what the code should be, use a suggestion 4. Create todos for complex issues - If a comment requires significant work, convert it to a todo 5. Keep comments focused - One issue per comment makes them easier to track and resolve

Exporting Reviews

Export reviews to markdown for documentation, sharing, or archival.

Basic Export

# Export the most recent review
npx githuman export last

# Export a specific review by ID
npx githuman export abc123

Save to File

# Save to a specific file
npx githuman export last -o review.md

# Save with a descriptive name
npx githuman export last -o reviews/feature-auth-review.md

Export Format

The exported markdown includes:

• Review metadata (date, status, files)
• List of all changed files
• Inline comments and their status
• Suggestions and whether they were applied
• Associated todos

Example output:

# Code Review - 2024-01-15

**Status**: Approved
**Files**: 5 changed

## Files Changed
- src/auth/login.ts
- src/auth/logout.ts
- tests/auth.test.ts

## Comments

### src/auth/login.ts:42
> Consider adding rate limiting here
Status: Resolved

### src/auth/login.ts:67
> Suggestion: Use optional chaining
Status: Applied

Use Cases

1. Documentation - Keep a record of why changes were made 2. Team sharing - Share reviews with team members not using GitHuman 3. Audit trail - Maintain history of code review decisions 4. Learning - Review past feedback to improve code quality over time

Installation

GitHuman can be run directly with npx or installed globally.

Quick Start (No Installation)

npx githuman serve

This downloads and runs GitHuman immediately, opening the web interface at http://localhost:3847.

Global Installation

For frequent use, install globally:

npm install -g githuman

Then run commands directly:

githuman serve
githuman list
githuman todo list

Requirements

• Node.js 24 or later (uses native SQLite)
• Git repository (GitHuman works within git repos)

Data Storage

GitHuman stores data in .githuman/reviews.db (SQLite database) in your repository root. This file contains:

• All reviews and their status
• Inline comments and suggestions
• Todos and their completion status

Important: The .githuman/ directory is not tracked by git. Back it up if you need to preserve review history.

Review Workflow

The complete workflow for reviewing AI-generated code changes before committing.

Basic Workflow

1. AI Makes Changes

After an AI agent modifies your codebase, you'll have unstaged changes in git.

2. Start the Review Server

npx githuman serve

This opens the web interface at http://localhost:3847.

3. Review Unstaged Changes

The home page shows all unstaged changes. You can:

• View diffs for each modified file
• Stage individual files or hunks directly in the UI
• Add inline comments on specific lines

4. Stage Files for Review

Either:

• Click the stage button in GitHuman's UI next to each file
• Use git commands: git add <files>

5. Review Staged Changes

Navigate to "Staged Changes" to see what will be committed. This is your final review before committing.

6. Add Comments and Suggestions

Click on any line to add:

• Comments for questions or notes
• Suggestions for code improvements
• Todos for follow-up work

7. Resolve and Commit

When satisfied:

# Mark the review as approved
npx githuman resolve last

# Commit the changes
git commit -m "Your commit message"

Example Session

# AI agent makes changes...

# Start review
npx githuman serve

# (Review in browser, stage files, add comments)

# Approve the review
npx githuman resolve last

# Check for any todos before committing
npx githuman todo list

# Commit
git commit -m "Add feature X"

Staging Files

GitHuman allows you to stage files directly in the web interface without switching to the terminal.

Staging in the UI

Stage Individual Files

On the unstaged changes view, each file has a stage button. Click it to stage that file for commit.

Stage Hunks

For files with multiple changes, you can stage individual hunks (sections of changes) rather than the entire file.

Unstage Files

Already staged files can be unstaged from the "Staged Changes" view.

Staging from Terminal

You can also use standard git commands:

# Stage specific files
git add src/feature.ts tests/feature.test.ts

# Stage all changes
git add .

# Stage interactively
git add -p

GitHuman will reflect the staging state in real-time.

Best Practices

1. Review before staging - Look at the diff in GitHuman before staging 2. Stage related changes together - Keep commits focused and atomic 3. Don't stage generated files - Avoid staging files that should be in .gitignore 4. Use partial staging - Stage only the hunks you want when a file has mixed changes

Tips and Best Practices

Productivity tips for getting the most out of GitHuman.

Quick Commands

# Start review quickly
npx githuman serve

# Approve and resolve the last review in one command
npx githuman resolve last

# Check pending todos before committing
npx githuman todo list

Keyboard Shortcuts

In the web interface:

• j / k - Navigate between files
• n / p - Navigate between changes
• c - Add comment on selected line
• s - Stage current file
• ? - Show all shortcuts

Workflow Tips

1. Review Before Staging

Always review the diff before staging. This helps catch issues early:

npx githuman serve
# Review unstaged changes first
# Then stage what looks good

2. Use Partial Staging

When a file has both good and bad changes, stage only the good hunks from the UI.

3. Create Todos for Non-Blocking Issues

Don't block your commit for minor issues. Create a todo and address it in a follow-up:

npx githuman todo add "Improve error messages in auth module"
git commit -m "Add auth feature"
# Handle the todo later

4. Export Important Reviews

For significant changes, export the review for documentation:

npx githuman export last -o docs/reviews/feature-x.md

5. Check Todos Before Each Commit

Make it a habit:

npx githuman todo list && git commit -m "message"

Integration with AI Workflows

When working with AI agents:

1. Let the AI make changes 2. Run npx githuman serve to review 3. Add comments for anything the AI should fix 4. Create todos for follow-up work 5. Approve and commit when satisfied

This creates a feedback loop where you can catch AI mistakes before they're committed.

Performance Tips

• Install globally for faster startup: npm install -g githuman
• Keep reviews small - Review and commit frequently rather than accumulating large changesets
• Use `--no-open` when you already have the browser open: npx githuman serve --no-open

Todos

Track follow-up tasks during code review with GitHuman's todo feature.

Creating Todos

From the Web UI

While reviewing code, you can create todos directly from inline comments. This links the todo to the specific line of code.

From the CLI

npx githuman todo add "Write tests for the new endpoint"
npx githuman todo add "Update documentation for API changes"

Listing Todos

# Show pending todos
npx githuman todo list

# Show all todos including completed
npx githuman todo list --all

Example output:

Pending todos:
  1. [ ] Write tests for the new endpoint
  2. [ ] Update documentation for API changes
  3. [ ] Review error handling in auth module

Completing Todos

# Mark todo #1 as done
npx githuman todo done 1

Best Practices

1. Create todos during review - When you spot something that needs attention but isn't blocking, create a todo 2. Check todos before committing - Run npx githuman todo list before each commit 3. Keep todos actionable - Write clear, specific tasks 4. Link to code - Create todos from inline comments to maintain context

Workflow Integration

# After AI makes changes
npx githuman serve

# (Review and create todos for follow-up work)

# Check what's pending
npx githuman todo list

# If todos are blocking, address them first
# If not, commit and handle todos in follow-up commits
git commit -m "Add feature X"

# Work through remaining todos
npx githuman todo done 1
# ... make changes ...
git commit -m "Add tests for feature X"