Gitwise

Gitwise is a terminal-first CLI that uses AI to help with two repetitive git tasks:

• writing commit messages
• naming branches

The current MVP focuses on fast suggestions, explicit confirmation before git mutations, and support for OpenAI-compatible APIs using gpt-5-mini or gpt-5-nano.

Gitwise is available under the MIT License. See LICENSE.

Current Status

Implemented today:

• gitwise commit suggestion flow from staged changes
• gitwise branch suggestion flow from natural-language intent
• interactive choose, edit, confirm, and regenerate actions
• actual git commit -m and git switch -c execution after confirmation
• config loading from global and repo config files
• schema validation for AI responses
• basic secret detection for staged diffs and file names
• test suite for core modules and CLI safety behavior

Requirements

• Bun 1.3+
• git installed and available in PATH
• an OpenAI-compatible API key

Install Dependencies

bun install

Development Commands

bun run dev --help
bun run check
bun run test
bun run build

Configuration

Gitwise reads config from:

• global: ~/.gitwise/config.json
• repo: .gitwise.json

To set up the machine-level config interactively, run:

gitwise config

That command writes defaults to ~/.gitwise/config.json and can also store your API key in ~/.gitwise/.env.

Gitwise also loads environment variables from:

• global: ~/.gitwise/.env
• repo: .env

Repo config overrides global config. Repo .env values override ~/.gitwise/.env values. Existing shell environment variables still win over both.

You can copy the starter file from .gitwise.json.example.

Example config:

{
  "provider": "openai-compatible",
  "model": "gpt-5-mini",
  "apiBaseUrl": "https://api.openai.com/v1",
  "apiKeyEnv": "OPENAI_API_KEY",
  "commitStyle": "conventional",
  "branchNaming": "{type}/{slug}",
  "includeRecentCommits": true,
  "maxDiffLines": 300
}

Lower-cost model option:

{
  "model": "gpt-5-nano"
}

Export your API key before running the CLI:

export OPENAI_API_KEY="your-api-key"

Or keep the secret in a project .env file while keeping .gitwise.json for non-secret settings:

printf 'OPENAI_API_KEY="your-api-key"\n' > .env

Example split setup:

/.gitwise.json

{
  "apiKeyEnv": "OPENAI_API_KEY",
  "model": "gpt-5-mini"
}

/.env

OPENAI_API_KEY="your-api-key"

For a machine-wide setup, you can also use ~/.gitwise/.env.

Usage

Suggest a commit message

Stage your changes first, then run:

gitwise commit

Useful variants:

gitwise commit --dry-run
gitwise commit --json
gitwise commit --no-history
gitwise commit --skip-safety
gitwise commit -d -j -H -S

Suggest a branch name

gitwise branch "add github oauth login"

Useful variants:

gitwise branch --dry-run "fix config parsing"
gitwise branch --json "set up release workflow"
gitwise branch -d "fix config parsing"
gitwise branch -j "set up release workflow"

Set up machine config

gitwise config

Safety Model

Gitwise is built to assist, not silently mutate git state.

• it checks that you are in a git repository before running git-dependent commands
• it refuses commit when nothing is staged
• it blocks obvious secret-like content from being sent to the AI provider
• you can bypass that check with gitwise commit --skip-safety when you intentionally want to send the staged diff anyway
• it only runs git commit -m or git switch -c after interactive confirmation

Project Layout

src/
  ai/
  commands/
  config/
  git/
  safety/
  ui/
  cli.ts
tests/
docs/

Testing

The test suite covers:

• config defaults and override precedence
• .env parsing and precedence
• branch name sanitization
• secret detection
• AI response schema validation
• provider response parsing compatibility
• diff truncation
• CLI safety behavior outside a repo and with no staged changes
• mocked provider-backed branch dry-run flow

Run tests with:

bun run test

Distribution

To build the lightweight Bun bundle locally:

bun run build

That produces dist/gitwise, which uses the Bun installed on the target machine instead of bundling the Bun runtime.

To use the JS build locally:

bun run build
bun run start -- --help
./dist/gitwise --help

To install the package globally from this repo with Bun:

bun install -g .

GitHub Actions automation is included for binary builds and releases:

• .github/workflows/ci.yml runs tests and typechecks on macOS, Linux, and Windows for pushes to main and for pull requests
• .github/workflows/release.yml builds a lightweight Bun bundle for tags like v0.1.0 and attaches gitwise-bun.tar.gz and gitwise-bun.zip to the GitHub Release automatically

The release bundle expects Bun to already be installed on the destination machine.

To publish a release bundle:

git tag v0.1.0
git push origin v0.1.0

Next Steps

Planned improvements include:

• tighter provider compatibility across OpenAI-style backends
• richer non-interactive automation flags
• more tests around full command execution flows
• PR title and body generation after the commit/branch MVP is solid

License

MIT. See LICENSE.