Ultrahope Documentation

Ultrahope generates commit message candidates from your diff — right in the terminal. You compare, edit, or escalate. You have the final word.

Quickstart

Install once, use from any repo.

npm install -g ultrahope

Stage your changes and run:

git add -p
git ultrahope commit

That's it. Works immediately — no account needed.

The free tier gives you 5 requests per day. If you need more, see pricing.

Git

commit

Generate commit messages from staged changes:

git ultrahope commit

Ultrahope reads your git diff --cached, sends it to the configured models, and presents multiple candidates in an interactive selector.

--guide

Provide additional context to steer the generated messages:

git ultrahope commit --guide "security fix for CVE-2024-1234"

The guide text is passed alongside your diff so the model can produce more relevant messages. Maximum 1024 characters.

Aliases

The CLI registers shorter names you can use instead of git ultrahope:

• git hope commit
• git uh commit

They behave identically.

Jujutsu

Ultrahope supports Jujutsu as a first-class VCS.

Setup

Register ultrahope as a jj alias:

ultrahope jj setup

This runs jj config set --user aliases.ultrahope '["util", "exec", "--", "ultrahope", "jj"]' so you can call it as a jj subcommand.

describe

Generate commit descriptions from revision changes:

jj ultrahope describe

By default it operates on the working-copy revision (@). Use -r to target a different revision:

jj ultrahope describe -r @-

The --guide flag works the same as in git ultrahope commit.

commit

Generate and apply a commit message as a new working-copy commit:

jj ultrahope commit

By default it operates on the working copy (@) and runs jj commit -m <message>.

The --guide flag works the same as in git ultrahope commit and jj ultrahope describe.

Behavioral difference

• jj ultrahope describe updates the target revision metadata (message) and does not create a new commit.
• jj ultrahope commit always creates a new working-copy change with the generated message.

Translate

Pipe arbitrary text into ultrahope translate to generate structured output:

git diff HEAD~3..HEAD | ultrahope translate --target pr-title-body

Available targets:

Interactive UI

When candidates are ready, Ultrahope presents an interactive selector:

Escalation

Press Shift+E during selection to re-generate using the pro tier escalation models. This is useful when the default tier models produce unsatisfying results and you want a stronger second pass.

Shift+E is available only to users with a Pro entitlement. For anonymous users and authenticated users who are not currently subscribed to Pro, the option is hidden because Pro-tier model usage requires the Pro plan.

Configuration

Ultrahope reads configuration from TOML files. No configuration is required — sensible defaults are provided.

Resolution order

Settings are resolved in this order (first match wins):

1. CLI flags (--models)
2. Project config (.ultrahope.toml or ultrahope.toml in the repo root, searched upward)
3. Global config (~/.config/ultrahope/config.toml)
4. Built-in defaults

Config file format

# ~/.config/ultrahope/config.toml

# Models to use for generation (each model produces one candidate)
models = ["mistral/ministral-3b", "xai/grok-code-fast-1"]

# Models to use when pressing Shift+E to escalate to the pro tier
escalation_models = ["anthropic/claude-sonnet-4.6", "openai/gpt-5.3-codex"]

Place an .ultrahope.toml in your repository root to set project-specific models.

Models

See the models page for the full list of available models and providers, including which models are Pro-only.

CLI flags

Override models for a single invocation:

Escalation models are configured in escalation_models in your config file and are typically pro tier models.

Use this flag to override defaults for a single command:

git ultrahope commit --models "anthropic/claude-sonnet-4.6,openai/gpt-5.3-codex"

Running this command without Pro will still start, but pro tier models will be rejected at generation time if selected.

Authentication

Anonymous (Free tier)

The CLI works without an account. On first use, an anonymous session is created automatically and stored locally.

• 5 requests per day
• 40,000 character input limit per request
• Resets daily

This is not a trial. It is a permanent free tier with these limits.

Login

To remove limits, create an account and authenticate:

ultrahope login

This opens a browser-based device code flow. Once authorized, the token is saved and used for all subsequent requests.

Credentials

Credentials are stored at:

~/.config/ultrahope/credentials.json

The file contains your access token and installation ID. It is created automatically.

Environment Variables

Pricing

Pro overage is billed at actual model cost. See pricing for current details.

License

The CLI (packages/cli) is MIT licensed. The web application (packages/web) is AGPL-3.0 licensed.

Source code: github.com/toyamarinyon/ultrahope