# Coding (/tools/toolkits/local/coding)



`CodingTools` is a minimal toolkit for coding agents. Four core tools (read, edit, write, shell) let an agent run tests, use git, install packages, and edit code. Three exploration tools (grep, find, ls) are opt-in.

## Prerequisites [#prerequisites]

[Create and activate a virtual environment](/sdk/setup), then install:

```shell
uv pip install agno openai
```

The Agent model uses an OpenAI key, separately from any toolkit provider credentials.

## Set OpenAI Key [#set-openai-key]

Set your `OPENAI_API_KEY` as an environment variable. You can get one [from OpenAI](https://platform.openai.com/account/api-keys).

<CodeBlockTabs defaultValue="Mac">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Mac">
      Mac
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Windows PowerShell">
      Windows PowerShell
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Mac">
    ```bash
    export OPENAI_API_KEY=sk-***
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Windows PowerShell">
    ```powershell
    $env:OPENAI_API_KEY = "your-openai-api-key"
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Example [#example]

```python title="cookbook/91_tools/coding_tools/01_basic_usage.py"
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.coding import CodingTools

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[CodingTools(base_dir=".")],
    instructions="You are a coding assistant. Use the coding tools to help the user.",
    markdown=True,
)

agent.print_response(
    "List the files in the current directory and read the README.md file if it exists.",
    stream=True,
)
```

<Warning>
  `CodingTools` can run arbitrary shell commands. By default `restrict_to_base_dir=True` checks explicit file paths, visible shell arguments and `allowed_commands`. An allowed program still executes with the process's filesystem, environment and network permissions. Keep human supervision for untrusted prompts, and run inside a sandbox (container, VM, or [Daytona](/tools/toolkits/others/daytona)) for untrusted code execution.
</Warning>

## Toolkit Params [#toolkit-params]

| Parameter              | Type                  | Default      | Description                                                                                                |
| ---------------------- | --------------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
| `base_dir`             | `Optional[Path\|str]` | `cwd`        | Root directory for file operations.                                                                        |
| `restrict_to_base_dir` | `bool`                | `True`       | Check explicit file paths and shell arguments against `base_dir`; this does not sandbox executed programs. |
| `max_lines`            | `int`                 | `2000`       | Maximum lines returned before truncating.                                                                  |
| `max_bytes`            | `int`                 | `50000`      | Maximum bytes returned before truncating.                                                                  |
| `shell_timeout`        | `int`                 | `120`        | Timeout in seconds for shell commands.                                                                     |
| `enable_read_file`     | `bool`                | `True`       | Enable the `read_file` tool.                                                                               |
| `enable_edit_file`     | `bool`                | `True`       | Enable the `edit_file` tool.                                                                               |
| `enable_write_file`    | `bool`                | `True`       | Enable the `write_file` tool.                                                                              |
| `enable_run_shell`     | `bool`                | `True`       | Enable the `run_shell` tool.                                                                               |
| `enable_grep`          | `bool`                | `False`      | Enable the `grep` tool.                                                                                    |
| `enable_find`          | `bool`                | `False`      | Enable the `find` tool.                                                                                    |
| `enable_ls`            | `bool`                | `False`      | Enable the `ls` tool.                                                                                      |
| `instructions`         | `Optional[str]`       | `None`       | Custom instructions for the agent. Built from the enabled tools if None.                                   |
| `add_instructions`     | `bool`                | `True`       | Add the instructions to the agent's system message.                                                        |
| `all`                  | `bool`                | `False`      | Enable all tools regardless of individual flags.                                                           |
| `allowed_commands`     | `Optional[List[str]]` | sensible set | Allowed shell command names when `restrict_to_base_dir` is True.                                           |

## Toolkit Functions [#toolkit-functions]

| Function     | Description                                                       |
| ------------ | ----------------------------------------------------------------- |
| `read_file`  | Read a file with line numbers and pagination (`offset`, `limit`). |
| `edit_file`  | Exact text find-and-replace, returns a diff.                      |
| `write_file` | Create or overwrite a file.                                       |
| `run_shell`  | Execute a shell command with a timeout.                           |
| `grep`       | Search file contents (opt-in).                                    |
| `find`       | Find files by glob pattern (opt-in).                              |
| `ls`         | List directory contents (opt-in).                                 |

## Developer Resources [#developer-resources]

* [Tools source](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/coding.py)
* [Basic usage](https://github.com/agno-agi/agno/blob/main/cookbook/91_tools/coding_tools/01_basic_usage.py)
* [All tools](https://github.com/agno-agi/agno/blob/main/cookbook/91_tools/coding_tools/02_all_tools.py)
* [Workspace toolkit](/tools/toolkits/local/workspace) for a confirmation-gated alternative