eckra - GitLite

KO | EN

gitlite — search

#kotlin #terminal #macos #gpt #cli #css #swift #nodejs #php #golang

eckra

(★ 12)

AI-powered Git management: smart commits, project stories, and the whole repo in one place

File Explorer

ZIP Download

- - bug_report.md
  - feature_request.md
- - ci.yml
  - publish.yml
- dependabot.yml
- PULL_REQUEST_TEMPLATE.md
- stale.yml
- release-notes.js
- - ai.js
  - clipboard.js
  - config.js
  - doctor.js
  - git.js
  - graph.js
  - lazygit.js
  - patch.js
  - providers.js
  - releaseNotes.js
  - suggest.js
  - update.js
- - app.js
  - common.js
  - diff-view.js
  - screen.js
- index.js
- ai.test.js
- branch.test.js
- clipboard.test.js
- commit-details.test.js
- commit.test.js
- common.test.js
- config.test.js
- conflict.test.js
- diff-view.test.js
- doctor.test.js
- git.test.js
- graph.test.js
- lazygit.test.js
- patch.test.js
- project.test.js
- providers.test.js
- release-notes.test.js
- screen.test.js
- settings.test.js
- status.test.js
- suggest.test.js
- timeline.test.js
- update.test.js
.gitignore
.prettierrc
AGENTS.md
CONTRIBUTING.md
eckra.gif
eckra.png
eslint.config.js
LICENSE
package-lock.json
package.json
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`npm install`

View Details ▼

Install Node packages.

npm {{[i|install]}}

Install dependencies listed in `package.json`:

npm {{[i|install]}} {{package_name}}@{{version}}

Download a specific version of a package and add it to the list of dependencies in `package.json`:

npm {{[i|install]}} {{package_name}} {{[-D|--save-dev]}}

Download the latest version of a package and add it to the list of dev dependencies in `package.json`:

🔍

`npm uninstall`

View Details ▼

Remove a package.

npm {{[r|uninstall]}} {{package_name}}

Remove a package from the current project:

npm {{[r|uninstall]}} {{package_name}} {{[-g|--global]}}

Remove a package globally:

npm {{[r|uninstall]}} {{package_name1 package_name2 ...}}

Remove multiple packages at once:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  <img src="https://cdn.jsdelivr.net/gh/sudoeren/eckra@master/eckra.png" alt="eckra terminal preview" width="800">
</p>

<h1 align="center">Eckra</h1>

<p align="center">
  <strong>AI-powered Git management: commits, stories, and the whole repo in one place</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/eckra"><img src="https://img.shields.io/npm/v/eckra?style=flat-square&color=1f6feb" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/eckra"><img src="https://img.shields.io/npm/dt/eckra?style=flat-square&color=1f6feb" alt="total downloads"></a>
  <a href="https://github.com/sudoeren/eckra/actions"><img src="https://img.shields.io/github/actions/workflow/status/sudoeren/eckra/ci.yml?style=flat-square&color=1f6feb" alt="CI status"></a>
</p>

---

## What is eckra?

eckra is an interactive, AI-powered Git management tool. It writes context-aware commit messages, turns your commit history into readable project stories, and brings staging, branches, stashes, and remotes into one dashboard. No config required to get started.

<p align="center">
  <img src="https://cdn.jsdelivr.net/gh/sudoeren/eckra@master/eckra.gif" alt="eckra demo" width="800">
</p>
<p align="center">
  <em>Interactive dashboard in action</em>
</p>

## Features

- **Works out of the box with [Ollama](https://ollama.com)**: no API key needed to start, cloud providers are optional
- **Interactive dashboard**: manage staging, branches, stashes, and remotes from one menu
- **AI commit messages** based on your actual diff, with 11 AI providers (OpenAI, Anthropic, Gemini, DeepSeek, Amazon Bedrock, OpenCode Go, and more; see the [provider table](#ai-configuration))
- **Multiple providers & accounts**: save several provider configurations side by side (e.g. two OpenAI accounts plus OpenRouter) and switch anytime from Settings or `eckra provider use`
- **Select & edit** any suggestion before committing
- **Choose your commit format**: `plain`, `conventional`, `conventional+body`, `gitmoji`, or `subject+body` (picked during setup, changeable in Settings or per-commit with `--type`)
- **Staged diff review** with syntax highlighting
- **Git Graph**: VS Code-style commit graph across all branches, with per-lane colors, pagination, and commit inspection
- **Project story**: AI timeline of your commit history
- **Lazygit integration**: run eckra's commit flow inside lazygit

## Installation

Install eckra globally:

```bash
npm install -g eckra
```

eckra can bind directly to [lazygit](https://github.com/jesseduffield/lazygit) right after installing:

```bash
eckra lazygit install
```

Then press `C` in lazygit's files view for an AI commit.

## Usage

Run `eckra` in any Git repository to open the dashboard:

```bash
eckra
```

> [!NOTE]
> On first run, eckra walks you through a quick setup wizard (provider, model, and preferred commit format). You can re-run the setup anytime with `eckra setup`.

Or jump straight into action:

| Command         | Alias | Action                        |
| :-------------- | :---- | :---------------------------- |
| `eckra commit`  | `c`   | AI-assisted commit flow       |
| `eckra status`  | `st`  | Status and staged files       |
| `eckra push`    | `p`   | Push to remote                |
| `eckra easy`    | `e`   | Stage all, AI commit, push (confirms each step) |
| `eckra story`   | `t`   | AI project timeline           |
| `eckra graph`   | `g`   | Interactive commit graph      |
| `eckra start`   | `s`   | Interactive dashboard         |
| `eckra lazygit` | `lg`  | Lazygit AI-commit integration |
| `eckra config`  | `cfg` | View or edit config           |
| `eckra provider`| `pv`  | Manage saved AI provider connections |
| `eckra doctor`  | `dr`  | Health check                  |
| `eckra suggest` | `sg`  | Print an AI commit message    |
| `eckra setup`   |       | Run the setup/onboarding wizard |
| `eckra model`   | `m`   | Show current AI settings & switch/manage providers |

> [!TIP]
> `eckra e` stages everything, generates an AI message, and asks you before committing and pushing.

From the dashboard you can also open **Git Graph** (under Branch) to see your full commit topology across all branches, page through history, and inspect commits for cherry-picking.

### Lazygit Integration

Use eckra's AI commit flow inside [lazygit](https://github.com/jesseduffield/lazygit):

```bash
eckra lazygit install
```

1. Restart lazygit and stage your files
2. Open the **files view** and press **`C`** (uppercase)
3. Review the generated commit message and confirm

eckra opens full-screen, writes the message, and commits once you approve.

#### Change the shortcut key

The key defaults to `C` (uppercase). If it collides with a lazygit shortcut you already use, pick another letter:

```bash
eckra config set lazygitKey g
eckra lazygit install    # re-applies the new key to lazygit's config
```

eckra warns you when the chosen letter is bound by a default lazygit shortcut, but lets you keep it anyway.

Manage the integration:

```bash
eckra lazygit            # Status + YAML snippet
eckra lazygit install    # Add the custom command
eckra lazygit remove     # Remove it
```

### CLI options

`eckra commit` flags:

| Flag                   | Alias | Action                                 |
| :--------------------- | :---- | :------------------------------------- |
| `--message <text>`     | `-m`  | Commit with this message, skip AI      |
| `--all`                | `-a`  | Stage all changes before generating    |
| `--yes`                | `-y`  | Skip the confirmation prompt           |
| `--generate <count>`   | `-g`  | Generate N messages to pick from       |
| `--type <format>`      | `-t`  | Commit message format (see below)      |
| `--clipboard`          | `-c`  | Copy the message to the clipboard instead of committing |
| `--no-verify`          | `-n`  | Bypass pre-commit and commit-msg hooks |
| `--exclude <files>`    | `-x`  | Exclude files/glob patterns from AI analysis (comma-separated) |
| `--max-length <n>`     |       | Preferred max subject length (default 50) |
| `--instruction <text>` |       | Extra instruction for the AI           |
| `--no-commit`          |       | Only generate and show the message     |

#### Commit message formats

`--type` (or the `commitType` config, chosen during setup) selects the format the AI writes in:

| Format              | Example subject            |
| :------------------ | :------------------------- |
| `plain`             | `add autocomplete search`  |
| `conventional`      | `feat(auth): add login`    |
| `conventional+body` | `feat: add login` + bullets (default) |
| `gitmoji`           | `✨ feat(auth): add login` |
| `subject+body`      | `add login` + bullets      |

Other commands:

```bash
eckra push -y                              # push without the confirmation prompt
eckra suggest --all --instruction "focus on the why"   # non-interactive, stdout
eckra suggest --output commit-msg.txt                  # write to a file (CI-friendly)
eckra story --count 20                                 # analyze the last 20 commits
eckra commit --type gitmoji                            # gitmoji-style message
eckra commit --clipboard                               # copy the message, don't commit
eckra commit -x "*.lock,config.local.js"              # ignore files in AI analysis
```

Risky operations ask for confirmation before running: **push**, **pull**, **push tags**, **delete tag**, **drop stash**, **amend**, **rebase** and **squash**. Pass `-y/--yes` on `eckra push` to skip it.

## AI Configuration

eckra works out of the box with **Ollama** (`http://localhost:11434`) using the lightweight [qwen3.5:2b](https://ollama.com/library/qwen3.5:2b) model:

```bash
ollama pull qwen3.5:2b
```

### Local providers (no API key)

| Provider      | Setup                                          | Default Model     |
| :------------ | :--------------------------------------------- | :---------------- |
| `Ollama`      | Local server, default `http://localhost:11434` | `qwen3.5:2b`      |
| `LM Studio`   | Local server, default `http://localhost:1234`  | (user-configured) |

### Cloud providers (API key)

| Provider                  | Requires                                                     | Default Model             |
| :------------------------ | :----------------------------------------------------------- | :------------------------ |
| `OpenAI`                  | OpenAI API key                                               | `gpt-5-mini`              |
| `Anthropic (Claude)`      | Anthropic API key                                            | `claude-haiku-4-5-20251001` |
| `Google Gemini`           | Google AI Studio API key                                     | `gemini-3.1-flash-lite`   |
| `OpenRouter`              | OpenRouter API key                                           | `openai/gpt-oss-120b`     |
| `DeepSeek`                | DeepSeek API key                                             | `deepseek-chat`           |
| `OpenCode Go`             | OpenCode Go API key                                          | `deepseek-v4-flash`       |
| `Ollama Cloud`            | Ollama Cloud API key (ollama.com/settings/keys)              | `qwen3.5:2b`              |
| `Amazon Bedrock`          | Bedrock API key + AWS Region (`bedrock-runtime` endpoint)    | `us.anthropic.claude-haiku-4-5` |
| `Amazon Bedrock Mantle`   | Bedrock API key + AWS Region (`bedrock-mantle` endpoint)     | `us.anthropic.claude-haiku-4-5` |

Providers are configured during setup and stored as **named connections** in `~/.eckra/config.json`. The configuration you pick during `eckra setup` becomes your `default` connection. eckra fetches the available models for you. Run `eckra model` to see your current AI settings (provider, connection, model, masked API key) and where they are stored, then switch or manage providers from the same menu.

### Saved connections (multiple providers & accounts)

eckra stores several provider configurations side by side, including different providers and/or multiple accounts for the same provider (e.g. a work and a personal OpenAI key). One connection is active at a time and every AI call uses it. With no explicit choice, eckra falls back to the `default` connection. You can override this per run with `ECKRA_ACTIVE_AI_CONNECTION` or pin a connection to a single repository with `eckra provider use <name> --local`, which is saved in `.eckrarc`.

The AI surfaces expose exactly two actions: **Switch Provider / Account** (pick an existing connection) and **Manage Providers** (everything else: add, edit credentials/model per connection, rename, delete). They live in the Settings menu and behind `eckra model`:

```bash
eckra provider list              # All saved connections, active marked with ✓
eckra provider add               # Interactive wizard: provider → key → model → name
eckra provider add --name work --provider openai \
  --set openaiApiKey=sk-... openaiModel=gpt-5-mini --use   # Non-interactive
eckra provider edit work         # Wizard: fix the API key or change the model
eckra provider use work          # Switch globally
eckra provider use home --local  # Pin a connection to this repo only (.eckrarc)
eckra provider show work         # Details (secrets masked)
eckra provider rename work is    # Rename (stays active if it was)
eckra provider remove work -y    # Delete
```

### Config CLI

```bash
eckra config                    # Show config (secrets masked)
eckra config get aiProvider     # Print a value
eckra config get aiProvider theme   # Print several values at once
eckra config set theme dark     # Set a value
eckra config set theme=dark locale=tr   # Set several key=value pairs at once
eckra config unset aiInstruction# Remove a key
eckra config reset              # Restore defaults
eckra config path               # Config file path
```

> [!NOTE]
> Add `--local` to target the project's `.eckrarc` instead. This file is gitignored as it can hold API keys.

A few useful keys: `commitType` (commit message format), `subjectMaxLength` (max subject characters, default 50), `locale` (language for messages, default `en`), `timeout` (AI request timeout in ms, default 30000), and `activeAiConnection` (the saved connection in use). Provider credentials and models live inside named connections. Manage them with `eckra provider` / `eckra model`, not `eckra config set` (which now rejects those keys with guidance). If you are upgrading from an older version, existing flat settings are migrated automatically into a `default` connection on first run and the old keys are kept for downgrade safety.

### Health check

`eckra doctor` checks Git, config, and the AI provider connection. Use `--no-provider` for an offline check or `--json` for CI. It exits with code `1` when any check fails.

### Updating

`eckra update` checks the npm registry and upgrades the global package:

```bash
eckra update            # Check and update (asks for confirmation)
eckra update --check    # Check only (exit code 1 if an update is available)
eckra update --yes      # Update without confirmation
```

You can also check from the menu: **More > Check for Updates**.

> [!NOTE]
> Running eckra via `npx eckra` always uses the latest version, no update needed.

### Scripts & CI

`eckra suggest` prints a commit message to stdout without any prompts:

```bash
eckra suggest                    # Message for staged changes
eckra suggest --all              # Stage everything first
eckra suggest --instruction "focus on the why"
eckra suggest --type gitmoji     # Pick the commit message format
eckra suggest -x "dist/"         # Exclude files from the analysis
```

## Troubleshooting

- **"AI Provider Error" / connection failed**: run `eckra doctor` to see exactly what's failing, then check the API key and model in **More > Settings**.
- **Wrong account or provider in use**: check which connection is active with `eckra provider list` and switch with `eckra provider use <name>`.
- **Ollama errors**: make sure the server is running (`ollama serve`) and the model is pulled: `ollama pull qwen3.5:2b`.
- **401 Unauthorized**: the API key is wrong or expired. Re-enter it in **More > Settings** or set it via `eckra config set <key> <value>`.
- **AI returns a warning or empty message**: some providers flag safe content; try a different model or check the provider's dashboard for rate limits.
- **Large diffs are truncated**: prompts are capped at 2000 characters by design. Commit in smaller chunks or stage related files only.

## Contributing

Please see [CONTRIBUTING.md](CONTRIBUTING.md).

## Uninstall

- **In-app:** `eckra` → **More > Settings** → **Uninstall Eckra** → type `uninstall`. This also removes the lazygit integration.
- **Manual:**

```bash
eckra lazygit remove   # remove the lazygit integration first (if you have it)
npm uninstall -g eckra
rm -rf ~/.eckra
```

## License

Distributed under the MIT License. See [LICENSE](LICENSE) for more information.