---
slug: "andre-barbosa-pi-commit"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/AndreB10/pi-commit@main/README.md"
repo: "https://github.com/AndreB10/pi-commit"
source_file: "README.md"
branch: "main"
---
# @andre-barbosa/pi-commit

A read-only [pi](https://pi.dev) extension that suggests Conventional Commit messages for uncommitted changes.

**pi-commit never stages files and never creates commits.** It only inspects Git state, sends bounded change context to a model, and displays suggested text.

## Install

Install from npm:

```bash
pi install npm:@andre-barbosa/pi-commit
```

Try a local checkout without installing it:

```bash
pi -e ./src/index.ts
```

Or install the local checkout as a pi package:

```bash
pi install .
```

The package can also be placed in a global or project extension directory supported by pi.

## Commands

### One message for all changes

```text
/commit
```

### One message per folder

```text
/commit /folder1 /folder2
```

Folder arguments are relative to the current Git repository root. If the current directory is not in a repository, they are relative to the current directory so child repositories can still be requested. Leading `/` is optional and denotes that path base; it is not an absolute filesystem path. Quote folders containing spaces:

```text
/commit "/packages/web app" /packages/api
```

For each requested folder, pi-commit runs Git with that folder as its working directory when Git can be used there. A nested repository is therefore inspected as its own repository, even when its folder is ignored by a parent repository, while an ordinary folder in the current repository remains folder-scoped. Multiple arguments may target different repositories. If a folder cannot be used as a Git working directory, pi-commit falls back to the previous repository-root pathspec inspection.

An explicitly requested folder overrides an ignore rule on that folder. In that case, ignored files are reported as `!!` and receive the same bounded, sensitive-name-aware previews as untracked files. Ignored files elsewhere remain excluded.

Overlapping folder arguments are rejected so the same change is not described twice. Folders with no changes are reported and skipped. The command does not stage or partition changes—it only returns suggested messages.

### Select a smaller model

```text
/commit-model
```

The interactive selector shows eight models at a time, fuzzy-filters as you type, and opens on the current commit model.
A model can also be selected directly:

```text
/commit-model google/gemini-2.5-flash
```

For a temporary CLI override:

```bash
pi --commit-model google/gemini-2.5-flash
```

The selection is independent from pi's conversation model: pi-commit never calls `pi.setModel()`. Interactive selections are saved in `pi-commit.json` under pi's global agent directory. Credentials remain managed by pi; configure providers through `/login` or `models.json`.

## Output

Each model call must return exactly one line in this form:

```text
feat(ui): add compact navigation controls
```

Allowed types are `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, and `revert`. Responses are validated and retried once when malformed.

Suggestions open in an editor dialog for manual adjustment. Press Enter to copy the edited text to the clipboard and close; press Escape to close without copying. Neither action stages files or creates a commit.

## What is inspected

pi-commit reads:

- NUL-delimited `git status` output, including ignored files only when their folder was explicitly requested
- staged and unstaged diff statistics
- staged and unstaged patches
- bounded previews of untracked and explicitly included ignored text files

Binary files and symlinks are represented by metadata. Untracked or explicitly included ignored files with names that appear sensitive, such as `.env`, credential, secret, PEM, or key files, are not read. Context is capped before it is sent to the model, while complete filenames and statuses are retained.

Selected model providers receive the included source diff. Review the provider's privacy policy before using the extension with sensitive repositories. Tracked sensitive files may still appear in Git patches.

## Safety boundary

Production Git execution is centralized in `ReadOnlyGit` and permits only:

- `git rev-parse`
- `git status`
- `git diff`
- `git check-ignore`

Commands are invoked with argument arrays, external diff/text conversion is disabled, and there is no implementation for `git add`, `git commit`, `git stash`, `git reset`, checkout, or push.

## Development

```bash
npm install
npm run check
npm test
```