@elizaos/plugin-git

Git CLI integration plugin for elizaos. Provides atomic git operations as actions and repository state as providers.

Installation

bun add @elizaos/plugin-git

Configuration

All configuration is optional. The plugin uses system git credentials by default.

Variable	Description
GIT_ALLOWED_PATH	Restrict all git operations to this directory
GIT_TOKEN	Token for HTTPS authentication (e.g., GitHub PAT)
GIT_USERNAME	Username for HTTPS authentication
GIT_PASSWORD	Password for HTTPS authentication
GIT_AUTHOR_NAME	Author name for commits
GIT_AUTHOR_EMAIL	Author email for commits
GIT_CLONE_TIMEOUT	Clone timeout in seconds (default: 300)
GIT_WORKING_COPIES_DIR	Base directory for managed clones (default: ~/.eliza/git)

Usage

Add the plugin to your elizaos project:

import { gitPlugin } from '@elizaos/plugin-git';

const project = {
  plugins: [gitPlugin],
  // ...
};

Actions

Tier 1 - Core Operations

Action	Description	Example
GIT_CLONE	Clone a repository	"Clone the elizaos/eliza repository"
GIT_ADD	Stage files for commit	"Stage all changes"
GIT_COMMIT	Create a commit	"Commit with message 'Fix bug'"
GIT_PUSH	Push to remote	"Push my changes"
GIT_PULL	Pull from remote	"Pull latest changes"
GIT_CHECKOUT	Switch/create branches	"Switch to develop branch"

Tier 2 - Common Workflows

Action	Description	Example
GIT_MERGE	Merge branches	"Merge feature into main"
GIT_INIT	Initialize new repo	"Create a new git repository"
GIT_FETCH	Fetch without merge	"Check for remote updates"

Tier 3 - Advanced Operations

Action	Description	Example
GIT_STASH	Stash/restore WIP	"Stash my changes"
GIT_RESET	Reset changes	"Unstage all files"

Providers

Providers inject git context into agent prompts automatically.

Provider	Description
GIT_INSTRUCTIONS	Comprehensive usage instructions for all git capabilities (highest priority)
GIT_WORKING_COPIES	Lists managed repositories and their locations
GIT_STATUS	Shows current repo status (staged, modified, untracked files)
GIT_BRANCHES	Shows branch information (local and remote)
GIT_LOG	Shows recent commit history

The GIT_INSTRUCTIONS provider ensures agents always know what git operations they can perform and how to use them. It prevents agents from claiming they cannot perform git operations.

Security

The plugin includes security guards to prevent operations on sensitive system directories:

• Blocked: /etc, /usr, /bin, /sbin, /lib, /boot, /sys, /proc, /dev, etc.
• Blocked: ~/.ssh, ~/.gnupg, and other sensitive user directories
• Optional: Use GIT_ALLOWED_PATH to restrict operations to a specific directory

Integration with plugin-github

This plugin is designed to work alongside @elizaos/plugin-github. The plugin-github handles GitHub API operations while plugin-git handles local git CLI operations.

import { gitPlugin } from '@elizaos/plugin-git';
import { githubPlugin } from '@elizaos/plugin-github';

const project = {
  plugins: [gitPlugin, githubPlugin],
  // ...
};

Exported Utilities

For use by other plugins:

import {
  // State management
  loadGitState,
  saveGitState,
  getActiveRepository,
  addWorkingCopy,
  
  // Security
  validatePath,
  isGitRepository,
  
  // Execution
  safeSpawn,
  parseStatusOutput,
} from '@elizaos/plugin-git';

License

MIT