# How to Use Built-In Toolkits in AISuite: Shell, Git, and File Operations

> Learn how to use built-in toolkits in AISuite including Shell Git and File operations. Integrate system capabilities into your agents for enhanced functionality.

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

---

**AISuite provides three built-in toolkits—Shell, Git, and File—that expose system capabilities to agents as executable tools, configured via factory functions and passed to the Agent constructor as a list of callable objects.**

The `andrewyng/aisuite` repository includes ready-to-use toolkits that allow AI agents to safely interact with the host environment. When you use built-in toolkits in AISuite, you convert system operations like shell commands, Git queries, and file manipulations into structured tools that LLMs can invoke through the agent runtime. Each toolkit follows a consistent factory pattern that returns a list of `Tool` objects decorated with metadata describing capabilities and risk levels.

## Overview of AISuite Built-In Toolkits

AISuite ships with three primary toolkits located in `aisuite/toolkits/`:

- **ShellToolkit** ([`aisuite/toolkits/shell.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/shell.py)): Executes shell commands in a confined directory with command whitelisting and timeout controls.
- **GitToolkit** ([`aisuite/toolkits/git.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/git.py)): Provides read-only Git operations including status checks and diff generation.
- **FileToolkit** ([`aisuite/toolkits/files.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/files.py)): Handles file system operations across one or more roots with read/write permissions and safety guards.

Each toolkit exposes a factory function—`shell()`, `git()`, and `files()`—that instantiates the toolkit with your specific configuration and returns a list of tool objects. These tools wrap Python functions with `ToolMetadata` that categorizes operations by risk level and approval requirements.

## Shell Toolkit Configuration

The **ShellToolkit** class (defined at line 53 in [`aisuite/toolkits/shell.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/shell.py)) creates a sandboxed execution environment for command-line operations. The factory function accepts parameters that restrict command execution:

```python
from aisuite.toolkits.shell import shell

tools = shell(
    cwd=".",                           # Working directory for execution

    allowed_commands=["ls", "git"],    # Whitelist specific commands

    allow_all=False,                   # Block unrecognized commands

    allow_shell=False,                 # Disable shell operators (;, |, &&)

    default_timeout_seconds=30,        # Kill long-running commands

    max_output_chars=10000             # Truncate verbose output

)

```

The `shell()` factory returns a list containing the `run_shell` tool. The toolkit validates commands through `_validate_command()` to prevent shell injection unless `allow_shell=True`. Execution occurs in `ShellToolkit.run_shell()`, which returns a dictionary with `command`, `exit_code`, `stdout`, `stderr`, and `timed_out` fields.

**Call the tool directly:**

```python
run_shell = tools[0].fn
result = run_shell("ls -la")
print(result["stdout"])  # Contains directory listing

```

## Git Toolkit for Repository Inspection

The **GitToolkit** class (defined at line 44 in [`aisuite/toolkits/git.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/git.py)) provides read-only access to Git repositories. Unlike the Shell toolkit, Git operations are restricted to status and diff queries—no commits or modifications are permitted.

The `git()` factory creates tools scoped to a repository root:

```python
from aisuite.toolkits.git import git

tools = git(root=".", max_output_chars=8000)

```

This returns a list containing two tools:
- `git_status`: Returns `git status --short --branch` output
- `git_diff`: Returns `git diff` results, optionally for specific paths or staged changes

```python
git_status = tools[0].fn
git_diff = tools[1].fn

# Check repository status

status = git_status()
print(status["stdout"])

# View staged changes

diff = git_diff(staged=True)
print(diff["stdout"])

```

Both methods delegate to `_run()`, which executes Git commands with the repository root as the working directory. Output is automatically clipped to `max_output_chars` to prevent context window overflow.

## File Toolkit for Read and Write Operations

The **FileToolkit** class (defined at line 228 in [`aisuite/toolkits/files.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/files.py)) is the most comprehensive toolkit, supporting both read and write operations across configurable directory roots.

The `files()` factory accepts multiple roots and write permissions:

```python
from aisuite.toolkits.files import files

# Single writable root

tools = files(root=".", allow_write=True)

# Multiple roots with mixed permissions

tools = files(
    root=["/project/src", "/project/docs"],
    allow_write=[True, False]  # src writable, docs read-only

)

```

The toolkit exposes eight methods as individual tools:

**Read operations:**
- `list_files(path, pattern, recursive, max_results)`: Browse directory contents
- `read_file(path)`: Read entire file contents
- `read_file_lines(path, start_line, max_lines)`: Read specific line ranges
- `search_files(query, path, pattern, max_results)`: Text search across files

**Write operations** (only available when `allow_write=True`):**
- `write_file(path, content, overwrite)`: Create or overwrite files
- `apply_unified_diff(diff)`: Apply standard unified diff patches
- `apply_patch(patch)`: Apply alternative patch formats
- `replace_in_file(path, old, new, expected_replacements)`: Find and replace text

Safety mechanisms in `FileToolkit` enforce **path confinement**—every resolved path must remain within an allowed root via the `_root_for()` method. The toolkit also maintains a default ignore list (including `.git` and `node_modules`) to prevent accidental exposure of large or sensitive directories.

**Working with file tools:**

```python
list_files = tools[0].fn
read_file = tools[1].fn
write_file = tools[4].fn  # Write tools follow read tools in the list

# List Python files

py_files = list_files(pattern="*.py", recursive=True)

# Read source

content = read_file("aisuite/toolkits/git.py")

# Write new file

write_file("output.txt", "Generated by AI", overwrite=True)

```

## Wiring Toolkits into an Agent

To use built-in toolkits in AISuite agents, aggregate the tool lists from multiple factories and pass them to the `Agent` constructor:

```python
from aisuite.agents import Agent
from aisuite.toolkits.shell import shell
from aisuite.toolkits.git import git
from aisuite.toolkits.files import files

# Combine toolkits using list concatenation

tool_set = (
    shell(cwd=".", allowed_commands=["ls", "git status"]) +
    git(root=".") +
    files(root=".", allow_write=True)
)

agent = Agent(
    model="gpt-4o-mini",
    tools=tool_set,
    # Additional configuration...

)

```

The agent runtime automatically serializes tool metadata for the LLM, handles execution when the model requests tool calls, and deserializes results back into the conversation flow. Each tool's `ToolMetadata` ensures the system knows the risk category and whether human approval is required before execution.

## Summary

- **AISuite provides three built-in toolkits**—Shell, Git, and File—located in [`aisuite/toolkits/shell.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/shell.py), [`aisuite/toolkits/git.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/git.py), and [`aisuite/toolkits/files.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/files.py) respectively.
- **Factory functions** (`shell()`, `git()`, `files()`) configure toolkit instances and return lists of executable `Tool` objects.
- **ShellToolkit** executes whitelisted commands with timeout controls and shell injection protection via `_validate_command()`.
- **GitToolkit** offers read-only repository inspection through `git_status` and `git_diff` tools.
- **FileToolkit** supports confined file operations with automatic path validation and separate read/write permissions.
- **Aggregate tools** from multiple factories using list concatenation and pass to the `Agent` constructor via the `tools` parameter.

## Frequently Asked Questions

### How do I restrict which shell commands an agent can execute?

Use the `allowed_commands` parameter in the `shell()` factory function. This list can contain exact command strings or prefixes that `ShellToolkit._validate_command()` checks before execution. Set `allow_all=False` (the default) to block unrecognized commands, and set `allow_shell=False` to prevent shell operators like pipes and semicolons.

### Can the Git toolkit modify repositories or only inspect them?

The Git toolkit is **read-only**. According to the source code in [`aisuite/toolkits/git.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/toolkits/git.py), it only exposes `git_status` and `git_diff` operations. The toolkit does not include methods for `git add`, `git commit`, `git push`, or any other write operations, ensuring safe repository inspection without modification risks.

### How does the File toolkit prevent agents from accessing sensitive directories?

`FileToolkit` enforces **path confinement** through the `_root_for()` method, which validates that every resolved path remains within an allowed root directory. Additionally, the toolkit maintains a default ignore list that excludes directories like `.git`, `node_modules`, and `__pycache__` from search and list operations, preventing accidental exposure of large or private files.