File Operations
All file tools enforce path safety: paths must resolve within the current working directory.
Read-only tools (read_file, list_directory, file_info) also allow access to the application
install directory — this matters in Docker containers where the working directory may differ from
the install path (e.g., -w /tmp while the app lives at /app). Write tools are restricted to the
working directory by default, but additional write directories can be allowed via
--allow-write-path, COGTRIX_ALLOWED_WRITE_PATHS, or the allowed_write_paths config option (see
Configuration).
read_file
Read contents of a file.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | File path to read |
encoding | string | No | File encoding (default: “utf-8”) |
start_line | int | No | Line number to start reading from (0-based) |
max_lines | int | No | Maximum number of lines to read from start_line |
Example:
Read file: /path/to/config.jsonwrite_file
Write content to a file (creates if not exists, overwrites if it does).
Requires Confirmation: Yes
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | File path to write (must be within working directory) |
content | string | Yes | Content to write |
encoding | string | No | File encoding (default: “utf-8”) |
patch_file
Surgically replace an exact string in a file without rewriting the whole file.
Requires Confirmation: Yes
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | File path to edit (must be within an allowed write root) |
old_str | string | Yes | Exact string to find (must appear exactly once in the file) |
new_str | string | Yes | Replacement string (may be empty to delete the match) |
Notes:
- Fails with a clear error if
old_stris not found or appears more than once — add more surrounding context to make the match unique. - Writes the result atomically; the file is never left in a partial state.
- Prefer this over
write_filefor targeted edits to existing files.
append_file
Append content to an existing file.
Requires Confirmation: Yes
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | File path to append to |
content | string | Yes | Content to append |
encoding | string | No | File encoding (default: “utf-8”) |
list_directory
List contents of a directory.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | Directory path |
pattern | string | No | Glob pattern to filter files (default: ”*“) |
show_hidden | bool | No | Include hidden files (default: false) |
Returns: List of files/directories with sizes
file_info
Get detailed information about a file or directory.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | File or directory path |
Returns: Size, creation date, modification date, permissions
Git Operations
Run Git commands from within Cogtrix to inspect and manage a repository. Read-only tools (git_status, git_diff, git_log) run without confirmation. Write tools (git_add, git_commit, git_create_branch, git_checkout) require confirmation. All commands use os.getcwd() as the working directory. Arguments are passed as list tokens — no shell interpolation occurs.
git_status
Show the working tree status: staged changes, unstaged changes, and untracked files.
Parameters: None
Returns: Short-format status output with branch name.
git_diff
Show a unified diff of changes in the working tree (or staged changes).
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | No | "" (all) | Specific file or directory to diff. Leave empty to diff all changes. |
staged | bool | No | false | Show staged (cached) diff instead of unstaged working-tree diff. |
Returns: git diff --stat --patch output.
git_log
Show recent commit history with hash, date, author, and subject.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
max_count | int | No | 10 | Number of commits to show (1–100). |
branch | string | No | "" (current) | Branch or ref to show history for. |
Returns: Formatted one-line-per-commit log.
git_add
Stage one or more files for the next commit.
Requires Confirmation: Yes
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
paths | array of strings | Yes | File paths to stage. Pass ["."] to stage all changes. |
git_commit
Create a commit from all currently staged changes.
Requires Confirmation: Yes
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Commit message (max 4096 chars). |
git_create_branch
Create a new branch and switch to it.
Requires Confirmation: Yes
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | New branch name (max 256 chars). |
base | string | No | "HEAD" | Starting point: branch name, tag, or commit hash. |
git_checkout
Switch to a branch or restore a file to its last committed state.
Requires Confirmation: Yes
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
ref | string | Yes | Branch name to switch to, or file path to restore to HEAD. |
GitHub Operations
These tools shell out to the GitHub CLI (gh) and only
register when gh is on PATH and authenticated — if it isn’t, they never appear in
the toolbox. When no repo is given they operate on the configured default repository.
gh_create_issue
Open a new issue on a GitHub repository.
Requires Confirmation: Yes
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Issue title. |
body | string | No | Issue body / description (Markdown supported). |
repo | string | No | owner/repo. Uses the configured default when empty. |
labels | string | No | Comma-separated label names (e.g. bug,enhancement). |
gh_comment_issue
Add a comment to an existing issue or pull request.
Requires Confirmation: Yes
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
issue_number | int | Yes | Issue or PR number to comment on. |
body | string | Yes | Comment body (Markdown supported). |
repo | string | No | owner/repo. Uses the configured default when empty. |
gh_list_prs
List pull requests on a repository.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
repo | string | No | default | owner/repo. Uses the configured default when empty. |
state | string | No | open | Filter by state: open, closed, merged, or all. |
limit | int | No | — | Maximum number of PRs to return. |
Returns: One line per PR with number, title, and state.
gh_get_file
Fetch the contents of a file from a GitHub repository without cloning it.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | — | Path to the file within the repository. |
repo | string | No | default | owner/repo. Uses the configured default when empty. |
ref | string | No | default branch | Branch, tag, or commit to read from. |