This library exposes a small, well-defined subset of Git operations as AI-callable tools. It is built on top of adachsoft/gitlib and is intended to be used by agents via the SPI layer of adachsoft/ai-tool-call.

There are currently two main SPI tools provided:

GitTool – full Git tool with both read and write operations.
ReadOnlyGitTool – read-only Git tool exposing only non-mutating operations.

Supported operations

Common operation model

Both tools share the same conceptual parameters shape:

{
  "operation": "operation-name",
  "options": {
    // operation-specific
  }
}

`GitTool` operations (read & write)

status – read repository status (branch, staged/modified/untracked/deleted files, raw output).
add – stage files in the index.
commit – create a new commit with a message.
push – push commits or tags to a remote.
tag_list – list tags (optionally filtered by pattern).
tag_create – create a new tag (lightweight or annotated, optional signing and force).
tag_delete – delete a local tag.
checkout – switch branches/tags/commits and optionally create a new branch.
show – show details of a Git object (commit, tag, etc.).
diff – show changes for a given path or commit range.
remote_list – list configured remotes with their URLs.

`ReadOnlyGitTool` operations (read-only)

The read-only tool exposes only non-mutating operations:

status
tag_list
show
diff
remote_list

This is useful for agents that must never change repository state but still need rich visibility into the Git history and configuration.

Installation

Install via Composer:

composer require adachsoft/git-tool

This package depends on:

adachsoft/ai-tool-call – SPI + public API for calling tools from agents.
adachsoft/gitlib – Git operations backend.

Check their respective composer.json files for exact PHP version requirements.

Architecture overview

The package is intentionally small and split into three main layers:

SPI Tools (integration layer)
- AdachSoft\GitTool\Tool\GitTool – implementation of AdachSoft\AiToolCall\SPI\ToolInterface.
- AdachSoft\GitTool\Tool\GitToolFactory – implementation of AdachSoft\AiToolCall\SPI\Factory\ToolFactoryInterface.
- AdachSoft\GitTool\Tool\ReadOnlyGitTool – read-only tool implementation of ToolInterface.
- AdachSoft\GitTool\Tool\ReadOnlyGitToolFactory – factory for the read-only tool.
Service layer
- AdachSoft\GitTool\Service\GitToolService / GitToolServiceInterface.
- AdachSoft\GitTool\Service\GitOperationRegistry / GitOperationRegistryInterface.
DTOs & Exceptions
- AdachSoft\GitTool\Dto\GitToolRequestDto, GitToolResultDto.
- Domain-specific exceptions under AdachSoft\GitTool\Exception.

The SPI layer knows only about the generic operation and options structure. The service layer maps these operations to concrete calls on Adachsoft\GitLab\Contracts\GitRepositoryInterface from adachsoft/gitlib.

Configuration: base_path

The Git repository location is configured once, when the tool is created by the factory. It is not provided per call.

GitToolFactory::create() and ReadOnlyGitToolFactory::create() accept an AdachSoft\AiToolCall\SPI\Collection\ConfigMap with the following option:

base_path (string, optional)
- Base path of the Git repository.
- When omitted, the current working directory (getcwd()) is used.
- When provided, it must be a non-empty string and an existing directory.

Example:

use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\GitTool\Tool\GitToolFactory;
use AdachSoft\GitTool\Tool\ReadOnlyGitToolFactory;

$config = new ConfigMap([
    'base_path' => '/path/to/your/git/repository',
]);

$writeFactory = new GitToolFactory();
$writeTool = $writeFactory->create($config); // AdachSoft\GitTool\Tool\GitTool

$readOnlyFactory = new ReadOnlyGitToolFactory();
$readOnlyTool = $readOnlyFactory->create($config); // AdachSoft\GitTool\Tool\ReadOnlyGitTool

The hosting application is responsible for wiring the factories into the SPI infrastructure of adachsoft/ai-tool-call (see that package's documentation for exact integration steps).

Tool interface: operations and options

The tool parameters are described by GitTool::getDefinition() and ReadOnlyGitTool::getDefinition() via SpiToolDefinitionDto. Conceptually, the parameters have the following shape:

{
  "operation": "status | add | commit | push | tag_list | tag_create | tag_delete | checkout | show | diff | remote_list",
  "options": {
    // operation-specific
  }
}

Refer to the PHPDoc blocks in GitTool and ReadOnlyGitTool for the exact list of parameters and result structures.

Result format

Every successful tool call returns a ToolCallResultDto that wraps a KeyValueMap with the following structure:

{
  "operation": "operation-name",
  "data": { /* operation-specific result */ }
}

Examples:

// status
{
  "operation": "status",
  "data": {
    "branch": "main",
    "staged": ["src/GitTool.php"],
    "modified": [],
    "untracked": ["README.md"],
    "deleted": [],
    "raw_output": "On branch main..."
  }
}

// remote_list
{
  "operation": "remote_list",
  "data": {
    "remotes": [
      {
        "name": "origin",
        "fetch_url": "git@github.com:adachsoft/git-tool.git",
        "push_url": "git@github.com:adachsoft/git-tool.git"
      }
    ]
  }
}

Error handling

The tools validate input at the SPI boundary:

missing or empty operation – InvalidToolCallException.
non-array options – InvalidToolCallException.
unsupported operation for the given tool (e.g. write operation on read-only tool) – InvalidToolCallException.

Domain-level errors are mapped to ToolExecutionException: