openclaw-git

Full Git workflow for OpenClaw — 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

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

# 2. Restart the gateway
openclaw gateway restart

Or from source:

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:

{
  "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 ([email protected]:...) no token is needed — your SSH key handles auth normally.

Optional tools allowlist

{
  "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

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

# 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

npm run typecheck

Dependencies:

• simple-git — git operations
• @sinclair/typebox — parameter schemas
• vitest — test runner (dev only)

License

MIT © KVASAR Technologies