hgassist: Hypergraph - Ask AI Anything

hgassist is a powerful, AI-driven command-line assistant designed to streamline your development workflow. It integrates directly into your terminal, helping you with common but time-consuming tasks like writing commit messages, summarizing changes, and creating pull requests, allowing you to stay focused on coding.

Why Use hgassist?

• Save Time: Automate repetitive tasks. Let AI draft your commit messages, PR descriptions, and code summaries in seconds.
• Improve Quality: Generate clear, conventional, and context-aware descriptions for your work, improving team communication and project documentation.
• Reduce Context Switching: Stay in your terminal. No need to switch to a browser or other applications to ask questions or draft text.
• Overcome Writer's Block: Get a high-quality first draft for any development-related text, from a simple commit to a complex PR review.

How It Works

hgassist uses the context from your local Git repository to provide relevant and intelligent assistance. When you run a command, it analyzes your staged changes, commit history, branch differences, and any provided prompts to generate accurate and helpful output. For interacting with GitHub features like issues and pull requests, it uses the official GitHub CLI (gh) under the hood.

Prerequisites

Before installing hgassist, you must install and configure the GitHub CLI.

1. Install GitHub CLI (gh)

The GitHub CLI is required to authenticate with GitHub and interact with repositories, issues, and pull requests.

You can find the official, detailed installation instructions for your operating system here: https://github.com/cli/cli#installation

Here are some common commands for popular package managers:

• macOS (Homebrew):

  brew install gh

• Windows (Winget):

  winget install -e --id GitHub.cli

• Debian/Ubuntu/Linux: (You may need to add a repository first, see the official guide)

  sudo apt install gh

2. Configure GitHub CLI

After installing gh, you need to authenticate with your GitHub account. Run the following command in your terminal and follow the on-screen instructions. It will likely ask you to log in via your web browser.

gh auth login

Once you are successfully logged in, you are ready to install and use hgassist.

Installation

To use hgassist, you need to have Node.js and either npm or Yarn installed. Install the package globally on your system using one of the following commands:

npm

npm install @hgraph/assist -g

Yarn

yarn global add @hgraph/assist

Global Command: hgassist

This is the main entry point for the entire application. You'll typically follow it with a subcommand, most commonly git.

Usage

hgassist <git> [--prompt=<string>] [--copy] [--plain-text] [--help] [--doc] [--version]

Commands

The primary subcommand available at the global level is:

| Command | Description | | :------ | :---------------------------------------------------- | | git | Accesses the suite of AI tools for Git-related tasks. |

Options

These options can be applied to modify the behavior of the command:

| Option | Description | | :------------------ | :--------------------------------------------------------- | | --prompt=<string> | Provide a specific question or instruction to the AI. | | --copy | Automatically copy the generated output to your clipboard. | | --plain-text | Output raw text without any special formatting or styling. |

Common Options

These options are for getting information about the tool itself:

| Option | Description | | :---------- | :-------------------------------------- | | --help | Show detailed help information. | | --doc | Generate documentation for the tool. | | --version | Show the current version of hgassist. |

Git Integration: hgassist git

This is the workhorse for developers. This command group uses AI to simplify and accelerate your day-to-day Git workflow.

Usage

hgassist git <todo|pr|summary|commit|review> [--prompt=<string>] [--copy] [--plain-text]

Subcommands

The git command provides the following powerful subcommands:

| Command | Description | | :-------- | :---------------------------------------------------------------------------- | | todo | Breaks down a complex GitHub issue or PR into a clear, actionable checklist. | | pr | Automatically drafts a well-structured pull request title and description. | | summary | Generates a concise summary of changes between commits or branches. | | commit | Crafts a descriptive, conventional commit message from your staged changes. | | review | Provides an AI-generated code review for a pull request, helping spot issues. |

hgassist git todo

Tackling a large GitHub issue can be daunting. This command reads the content of an issue or PR and generates a checklist of implementation tasks to help you get started.

Use Case

You are assigned issue #142, which describes a new feature. To plan your work, you can automatically generate a to-do list.

Example

# Generate a todo list from issue #142
hgassist git todo --issue=142

Options

| Option | Description | | :------------------ | :------------------------------------------------------------------ | | --copy | Copy the generated checklist to the clipboard. | | --plain-text | Show the list as plain text without checklist formatting (- [ ]). | | --issue=<string> | The number of the GitHub issue or pull request to read from. | | --prompt=<string> | Use a local description instead of fetching a GitHub issue. |

hgassist git pr

Avoid writer's block when creating pull requests. This command analyzes the difference between your current branch and the target branch, then generates a comprehensive title and description for your PR.

Use Case

You've just finished your feature on the feat/user-auth branch. Now you can create a PR without manually writing up all the changes.

Example

# Generate and create a PR for the current branch
hgassist git pr

# To skip the confirmation step, useful in scripts
hgassist git pr --yes

An example of what it might generate:

Title: feat: Implement user authentication endpoints

Body:

### Summary > This pull request introduces a complete user authentication flow, including user registration, login, and token generation. It adds the necessary models, controllers, and routes to secure application endpoints.

### Changes > - Added User model with password hashing. > - Created /auth/registerand/auth/login endpoints. > - Implemented JWT for session management. > - Added middleware to protect routes.

### Related Issue > Closes #42

Options

| Option | Description | | :------------------ | :------------------------------------------------------------ | | --copy | Copy the generated title and body to the clipboard. | | --plain-text | Show output without any Markdown formatting. | | --prompt=<string> | Add extra details or instructions for the AI to consider. | | --branch=<string> | Explicitly define the branch to diff against for the PR. | | --yes | Create/edit the pull request without asking for confirmation. |

hgassist git summary

Quickly understand the changes in a commit or between branches. This is perfect for daily stand-ups, status updates, or for generating release notes.

Use Case

You need to explain what was changed in the latest commit (a1b2c3d) to a colleague.

Example

# Summarize the changes in a specific commit
hgassist git summary --commit=a1b2c3d

Options

| Option | Description | | :------------------ | :--------------------------------------------------------------- | | --copy | Copy the generated summary to the clipboard. | | --plain-text | Show output without any special formatting. | | --commit=<string> | The commit hash to generate a summary for. (Defaults to HEAD). |

hgassist git commit

Write clean, conventional commit messages effortlessly. This command looks at your staged files (git add .) and generates a commit message that explains what you did and why.

Use Case

You have staged changes for a bugfix and want a well-formatted commit message without having to write it from scratch.

Example

# Stage your files first
git add .

# Let AI generate the commit message and commit the changes
hgassist git commit

Options

| Option | Description | | :------------- | :--------------------------------------------- | | --copy | Copy the generated message to the clipboard. | | --plain-text | Show the message without any extra formatting. |

hgassist git review

Get an AI-powered "second pair of eyes" on your code. This command can review a pull request by its number, URL, or branch name, providing feedback on potential bugs, style issues, and areas for improvement.

Use Case

A teammate has submitted a pull request and you want to get an initial, automated review before you dive in manually.

Example

# Review pull request #88 in the current repository
hgassist git review --pr=88

# Or review a PR from a URL
hgassist git review --url=https://github.com/owner/repo/pull/88

Options

| Option | Description | | :------------------ | :-------------------------------------------------- | | --copy | Copy the generated review to the clipboard. | | --plain-text | Show the review without any special formatting. | | --branch=<string> | Specify a branch to review against the base branch. | | --pr=<string> | The number of the pull request to review. | | --url=<string> | The full URL of the pull request to review. |