Hange

/ˈhɑːn.dʒi/ (han-jee)

A small CLI soldier that goes hand in hand with a developer. An agentic answer for routine tasks.

Buzzwords 😎

Agent, RAG, Vector store, Goroutines, Worker Pool, Cobra CLI

Quickstart

go install . && hange -h        # install locally
echo "sk-..." | hange auth      # save your OpenAI API key (stdin or arg)
hange explain README.md cmd     # explain files or folders
hange commit-msg "ctx"          # generate a commit message for staged changes
# hange commit "ctx"            # same as above, but also runs git commit

Development

Shortest way to build the command is

go install . && hange version

Techs

This project is powered by Go Cobra library that provides the framework for CLI applications.

Installation

Hange can be installed by 2 ways:

1. Install it from GitHub repository by specific tag

   go install github.com/yaroslav-koval/hange@latest

2. Clone this repo locally and install using

   go install .

3. Download a release binary (no Go toolchain required). Example for macOS arm64:

   ver=v0.1.0
   url=https://github.com/yaroslav-koval/hange/releases/download/$ver/hange_darwin_arm64
   curl -sL "$url" -o hange && chmod +x hange
   ./hange version

   Consider moving hange into a directory on your PATH (e.g., /usr/local/bin) for easy access.

Requirements

• openAI access token
• git (binary)
• go 1.25+ (only for installation by Go commands. Not needed if downloaded from a GitHub release)

Config

• Default config file: ~/.hange (YAML). Override with --config flag or env HANGE_CONFIG_PATH.
• Values can also come from env vars with prefix HANGE_, e.g. HANGE_AUTH_OPENAI_TOKEN.
• The OpenAI token is stored at auth.openai.token, base64-encoded (not strong encryption).
• A config file is created automatically if missing.

Project structure

• main.go boots the Cobra CLI and embeds config.yaml for version output.
• cmd/ contains Cobra commands (auth, explain, commit[-msg], version) with minimal wiring only.
• domain/ holds the domain logic and entities
• pkg/consts and pkg/envs keep cross-cutting constants and env var names used by the CLI wiring.
• mocks/ stores generated interfaces; configs/badges/ holds badge data.

Adapters pattern

Packages keep core interfaces at the root and place concrete adapters in nested folders. Example: domain/agent defines the primary AIAgent along with secondary interfaces (CommitProcessor, ExplainProcessor); the OpenAI-backed implementations live in domain/agent/commit and domain/agent/explain, and factories pick the adapter at runtime. This keeps the core logic reusable while swapping integrations per environment.

Tests

Tests are powered by Testify and Mockery

All the mocks stored in directory mocks. Mocks for all the existing in application interfaces can be generated by running:

make gen-mocks

Command docs

Generated Cobra command reference lives in docs/commands. Start with hange.md, and use make gen-cli-docs to regenerate the markdown if commands or flags change.

Changelog

Release notes live in CHANGELOG.md; use docs/CHANGELOG_TEMPLATE.md when drafting a new entry.

Release pipeline

• Update code, bump version in config.yaml, and add a matching ## vX.Y.Z section at the top of CHANGELOG.md.
• Push to main: .github/workflows/autotag-on-config.yaml verifies the changelog entry and creates tag vX.Y.Z ( fails if tag exists).
• Tag push triggers .github/workflows/release.yml, which extracts the top changelog section as release notes and runs GoReleaser to publish binaries for macOS/Linux on amd64/arm64.

Reasons of using specific models.

Different commands can call different models by their reasons:

• explain works with gpt-nano models, despite gpt-codex models would fit here better. Reason is work with files and vector stores, this feature is not available for codex models.
• commit-msg and commit commands work with gpt-nano, commit content is embedded into input. Cost-efficient and the most fast model, commit shouldn't take much time.