npm package: @kvasar/openclaw-git
Description: Git management plugin for OpenClaw — clone, branch, diff, commit and push without leaving chat
Latest version: 1.5.8

# openclaw-git

Full Git workflow for [OpenClaw](https://docs.openclaw.ai) — clone repos, manage branches,
diff changes, stage, commit and push without leaving chat.

## Tools provided

| Tool | Description |
|------|-------------|
| `git_status` | Working-tree status: branch, staged, modified, untracked |
| `git_clone` | Clone a remote repo (supports shallow clones) |
| `git_checkout` | Switch branch or create + checkout a new one |
| `git_branch` | List local/remote branches |
| `git_diff` | Unified diff (unstaged or staged, optionally scoped to a file) |
| `git_log` | Recent commit history |
| `git_add` | Stage files (or everything) |
| `git_commit` | Create a commit from staged changes |
| `git_push` ⚠️ | Push branch to remote |
| `git_pull` | Fetch + merge from remote |
| `git_stash` | Push/pop/list stash |
| `git_reset` ⚠️ | Move HEAD (soft / mixed / hard) |

Tools marked ⚠️ are **optional** and must be explicitly allowed in config.

---

## Installation

```bash
# 1. Install the plugin
openclaw plugins install @kvasar/openclaw-git

# 2. Restart the gateway
openclaw gateway restart
```

Or from source:

```bash
git clone https://github.com/kvasar/openclaw-git
openclaw plugins install ./openclaw-git
openclaw gateway restart
```

---

## Configuration

### Bitbucket private repos (optional)

Generate an **API token** in Bitbucket:

1. Go to **Bitbucket → Personal settings → API tokens**
2. Click **Create API token**
3. Give it a label (e.g. `openclaw-git`)
4. Set scope: **Repositories → Read** (add **Write** if you want to push)
5. Copy the generated token

Then add to your OpenClaw config:

```json
{
  "plugins": {
    "entries": {
      "openclaw-git": {
        "enabled": true,
        "config": {
          "bitbucketApiToken": "ATBBxxxxxxxxxxxxxxxx"
        }
      }
    }
  }
}
```

> **How it works:** Bitbucket API token auth uses the static username `x-bitbucket-api-token-auth` with your token as the password. You can either pass a clean Bitbucket HTTPS URL and let the plugin inject the token from config, or pass a fully credentialed URL directly. The token is redacted from plugin responses.

For SSH clones (`git@bitbucket.org:...`) no token is needed — your SSH key handles auth normally.

### Optional tools allowlist

```json
{
  "tools": {
    "allow": ["git_push", "git_reset", "git_clone"]
  }
}
```

---

## Usage examples

Once installed, just ask the agent naturally:

```
Clone https://github.com/eclipse-edc/Connector into ~/projects/edc
```

```
Show me the status of ~/projects/my-app
```

```
Stage all changes in ~/projects/my-app and commit with message "fix: resolve NPE in auth filter"
```

```
Show me the diff of src/main/java/App.java before I stage it
```

```
Create a new branch feature/vc-policy and push it to origin
```

```
Pull the latest changes from main
```

---

## Development & Testing

### Install dev dependencies

```bash
cd openclaw-git-plugin
npm install
```

### Test files

| File | What it tests |
|------|--------------|
| `src/config.test.ts` | Unit tests — `isBitbucketUrl`, `injectBitbucketCredentials`, `redactCredentials` |
| `src/git-ops.test.ts` | Integration tests — all git ops against a real temp repo (no network) |
| `plugin.contract.test.ts` | OpenClaw SDK contract — plugin registration, tool schemas, tool execution |

### Run tests

```bash
# All tests (vitest)
npm test

# Watch mode during development
npm run test:watch

# Contract tests only (SDK-level validation)
npm run test:contract

# Node built-in test runner (no install needed, Node >= 22)
npm run test:node

# Type-check + all tests
npm run check
```

### What the contract test validates

Using `createTestRuntime` from `openclaw/plugin-sdk/testing`, the contract test verifies:

- Plugin `id` is `"openclaw-git"`
- Exactly **12 tools** are registered with correct names
- `git_clone`, `git_push`, `git_reset` are marked `optional: true`
- All 9 required tools are **not** optional
- Every tool has a `parameters` schema and a description > 10 chars
- `git_status`, `git_log`, `git_diff`, `git_branch` return correct text content
- `git_add` + `git_commit` round-trip works against a real repo
- Bitbucket URL without config → credential warning (not a crash)
- Bitbucket URL with config → no credential warning (attempts clone)

### Type-check only

```bash
npm run typecheck
```

Dependencies:

- [`simple-git`](https://github.com/steveukx/git-js) — git operations
- [`@sinclair/typebox`](https://github.com/sinclairzx81/typebox) — parameter schemas
- [`vitest`](https://vitest.dev) — test runner (dev only)

---

## License

MIT © KVASAR Technologies