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

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): Executes shell commands in a confined directory with command whitelisting and timeout controls.
• GitToolkit (aisuite/toolkits/git.py): Provides read-only Git operations including status checks and diff generation.
• FileToolkit (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) creates a sandboxed execution environment for command-line operations. The factory function accepts parameters that restrict command execution:

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:

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) 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:

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

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) is the most comprehensive toolkit, supporting both read and write operations across configurable directory roots.

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

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:

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:

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, aisuite/toolkits/git.py, and 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}