# How to Use the Git Toolkit in aisuite: A Complete Guide for AI Agents

> Learn to use the Git Toolkit in aisuite with this guide. Enable AI agents to inspect Git status and view code changes using read-only operations.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: how-to-guide
- Published: 2026-06-16

---

**aisuite provides a built-in Git Toolkit that exposes read-only Git operations as callable tools, allowing AI agents to inspect repository status and view code changes without modifying the codebase.**

The **Git Toolkit** in aisuite enables agents to safely interact with Git repositories through a standardized interface. Defined in [`aisuite/toolkits/git.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/git.py), this toolkit wraps standard Git commands in lightweight Python functions that return structured data, making it easy for language models to consume repository information while maintaining security boundaries.

## What is the Git Toolkit in aisuite?

The Git Toolkit is a specialized module that converts Git operations into **tools** that agents can invoke. Unlike command-line Git wrappers, these tools include metadata describing their capabilities and risk levels, allowing orchestration systems to permission them appropriately.

According to the aisuite source code, the toolkit implements two primary capabilities:

- **git_status** – Executes `git status --short --branch` to retrieve the current repository state
- **git_diff** – Executes `git diff` to compare working directory changes against the index

Both tools carry metadata classifying them as **low risk** because they are strictly read-only; they never write to the repository, stage files, or execute commits.

## Core Git Tools and Their Implementation

The toolkit centers on a private `GitToolkit` class that handles path normalization, subprocess execution, and output safety.

### The git_status Tool

The `git_status` tool provides a snapshot of the repository state, including branch information and modified files. As implemented in [`aisuite/toolkits/git.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/git.py) (lines 27-30), it returns a dictionary containing:

- The executed command
- Exit code
- Standard output (stdout)
- Standard error (stderr)
- A `truncated` boolean flag

This tool automatically clips output to `max_output_chars` (default 20,000 characters) to prevent overwhelming LLM context windows.

### The git_diff Tool

The `git_diff` tool supports examining changes in the working directory. It accepts optional parameters for `path` (to limit diff scope) and `staged` (boolean to view staged changes via `--staged`). The implementation (lines 35-38) includes **path safety validation** through `_resolve_path`, which raises `PermissionError` if the requested path escapes the toolkit root directory.

## How the Git Toolkit Works Under the Hood

The `GitToolkit` class performs several safety-critical operations when processing Git commands:

1. **Path normalization** – Resolves the root directory using `Path(root).expanduser().resolve()` (line 48)
2. **Subprocess execution** – Runs Git via `subprocess.run` (lines 66-73)
3. **Output truncation** – Cuts long outputs to configurable limits (lines 94-96)
4. **Security enforcement** – Validates that all paths remain within the toolkit root (lines 85-90)

This architecture ensures that agents can only inspect repositories within explicitly defined boundaries, preventing directory traversal attacks.

## Using the Git Toolkit

### Basic Setup and Initialization

To use the toolkit, import aisuite and instantiate the Git tools for a specific repository:

```python
import aisuite as ai
from pathlib import Path

# Initialize the toolkit for your target repository

repo_root = Path("/path/to/your/repo")
git_tools = ai.toolkits.git(root=repo_root)

# Extract the callable functions

git_status = git_tools[0].func
git_diff = git_tools[1].func

```

### Checking Repository Status

Call `git_status()` to retrieve the current branch and modification status:

```python
status_info = git_status()
print(status_info["stdout"])

# Output includes:

# - Branch information

# - Modified files (M)

# - Untracked files (?)

# - Staged changes (A, D, etc.)

```

The returned dictionary includes an `exit_code` (0 for success) and a `truncated` flag indicating whether output exceeded the character limit.

### Viewing Code Changes

Use `git_diff` to inspect uncommitted changes. You can view unstaged changes, staged changes, or limit the scope to specific files:

```python

# View unstaged changes for a specific file

diff_info = git_diff(path="src/main.py")
print(diff_info["stdout"])

# View staged changes (equivalent to git diff --staged)

staged_diff = git_diff(path="src/main.py", staged=True)
print(staged_diff["stdout"])

# View all changes in the repository

full_diff = git_diff()

```

## Accessing Git History with the Coworker git_log Tool

For agents requiring commit history, aisuite provides a complementary `git_log` tool in [`platform/coworker/tools/git.py`](https://github.com/andrewyng/aisuite/blob/main/platform/coworker/tools/git.py). This tool adds the **git_log** capability, returning recent commit metadata without altering the repository.

Initialize it similarly:

```python
from platform.coworker.tools import git as coworker_git

# Register the git_log tool for your workspace

log_tools = coworker_git.git_tools(workspace=str(repo_root))
git_log = log_tools[0]

# Retrieve the latest 10 commits

history = git_log(max_count=10)
for commit in history["commits"]:
    print(f"{commit['hash']} – {commit['author']} ({commit['date']}): {commit['subject']}")

```

This tool is particularly useful for code review agents that need to understand recent development activity before suggesting changes.

## Summary

- The aisuite Git Toolkit in [`aisuite/toolkits/git.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/git.py) provides **read-only** access to repository status and diffs
- Two primary tools are available: `git_status` for branch/file state and `git_diff` for change comparison
- The toolkit enforces **path safety** and **output limits** (default 20,000 characters) to protect agent systems
- Tools return structured dictionaries with stdout, stderr, exit codes, and truncation flags
- The complementary `git_log` tool in [`platform/coworker/tools/git.py`](https://github.com/andrewyng/aisuite/blob/main/platform/coworker/tools/git.py) extends functionality to commit history
- All tools are classified as **low risk** because they cannot modify repository state

## Frequently Asked Questions

### How do I instantiate the Git Toolkit for multiple repositories?

Create separate toolkit instances for each repository root. Each `GitToolkit` instance is bound to a specific path validated during initialization, preventing cross-repository access. Simply call `ai.toolkits.git(root=Path("/repo1"))` and `ai.toolkits.git(root=Path("/repo2"))` to create isolated toolsets.

### Why does the Git Toolkit truncate output to 20,000 characters?

The `max_output_chars` parameter (configurable in the toolkit constructor) prevents large diffs or status outputs from overwhelming LLM context windows. This safety default is implemented in [`aisuite/toolkits/git.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/git.py) (lines 94-96) and can be adjusted based on your specific model's context limits.

### Can the Git Toolkit commit changes or push to remote repositories?

No. The toolkit is explicitly **read-only**, exposing only `git status` and `git diff` operations. According to the source code in [`aisuite/toolkits/git.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/git.py), the implementation lacks write operations, maintaining a low-risk profile suitable for autonomous agent execution.

### What happens if I try to access files outside the repository root?

The `_resolve_path` method raises a `PermissionError` (lines 85-90 in [`aisuite/toolkits/git.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/git.py)). This security boundary ensures that agents cannot use path traversal sequences (e.g., `../../../etc/passwd`) to access sensitive files outside the designated repository workspace.