File Tools¶

janito provides a complete set of tools for working with the local filesystem: listing, reading, creating, modifying, searching, and deleting files and directories.

Availability¶

File tools are always available — the files toolset is auto-loaded, so you don't need any special flag:

# File tools work in interactive chat
janito

# ...and in single prompts
janito "List all Python files in this project"

Available Tools¶

Tool	Description	Permissions
`ListFiles`	List files and directories, with pattern filtering	`r`
`FindFiles`	Find files/dirs by name pattern and attributes (size, mtime, type)	`r`
`ReadFile`	Read the contents of a file (full or line range)	`r`
`ReadMultipleFiles`	Read several files in a single call	`r`
`SearchText`	Search for exact text across files	`r`
`SearchRegex`	Search for regex patterns across files	`r`
`CreateFile`	Create a file with the given content	`w`
`CreateDirectory`	Create a directory	`w`
`ReplaceTextInFile`	Replace text inside a file	`rw`
`MoveFile`	Move or rename a file or directory	`rw`
`DeleteFile`	Delete a file	`w`
`RemoveDirectory`	Remove a directory (optionally recursively)	`w`

Permission levels: r = read, w = write, rw = read and write. Write-capable tools are subject to janito's privilege settings.

Usage¶

Example Prompts¶

# Explore a directory
janito "List the files in the docs folder"

# Read a file
janito "Show me the contents of README.md"

# Read just part of a large file
janito "Show me lines 100 to 150 of app.py"

# Create a file
janito "Create a file called notes.txt containing 'hello world'"

# Edit a file
janito "In config.py, replace 'debug = False' with 'debug = True'"

# Search for text
janito "Find every file that mentions 'TODO'"

# Search with a regex
janito "Search for all email addresses in the project"

# Clean up
janito "Delete the temp.log file"

Tool Reference¶

ListFiles¶

List files and directories in a path.

Parameter	Type	Default	Description
`directory`	str	`"."`	Directory to list
`pattern`	str	`None`	Glob filter, e.g. `"*.py"`
`recursive`	bool	`False`	Recurse into subdirectories
`max_depth`	int	`None`	Max recursion depth (unlimited if `None`)
`respect_gitignore`	bool	`True`	Skip paths matched by `.gitignore` (`.janitoignore` is always respected; the `.janitoignore` file itself is always ignored)

ReadFile¶

Read the contents of a file (1-based indexing).

Parameter	Type	Default	Description
`filepath`	str	—	File to read
`start_line`	int	`1`	Start line (1-based). A negative value counts back from the end of the file (`-1` = last line, `-5` = fifth-to-last) and reads to EOF — like `tail -5`.
`max_lines`	int	`None`	Max lines to read from `start_line` (defaults to end of file). Ignored when `start_line` is negative.

# Last 20 lines of a log file, without knowing how long the file is
python -m janito.tools.files.read_file app.log --start-line -20

ReadMultipleFiles¶

Parameter	Type	Default	Description
`filepaths`	list	—	List of file paths to read

SearchText¶

Search for exact text matches.

Parameter	Type	Default	Description
`paths`	str	—	Space-separated files/directories to search
`query`	str	—	Exact text to find
`case_sensitive`	bool	`True`	Case-sensitive matching
`max_depth`	int	`None`	Max directory depth
`max_results`	int	`100`	Max results returned
`count_only`	bool	`False`	Return counts instead of lines
`respect_gitignore`	bool	`True`	Skip `.gitignore` paths (`.janitoignore` is always respected; the `.janitoignore` file itself is always ignored)
`exclude`	str	`None`	Space-separated glob patterns to exclude, e.g. `"/node_modules/ /__pycache__/"`

SearchRegex¶

Search for regular expression patterns. Same parameters as SearchText, but uses pattern (a regex) instead of query, and also accepts exclude.

CreateFile¶

Parameter	Type	Default	Description
`filepath`	str	—	Where to create the file
`content`	str	`""`	Content to write
`overwrite`	bool	`False`	Overwrite an existing file

Parent directories are created automatically.

CreateDirectory¶

Parameter	Type	Default	Description
`directory`	str	—	Directory to create
`parents`	bool	`False`	Create missing parent directories
`exist_ok`	bool	`False`	Don't error if it already exists

ReplaceTextInFile¶

Parameter	Type	Default	Description
`filepath`	str	—	File to modify
`old_str`	str	—	Exact text to find
`new_str`	str	—	Replacement text
`replace_all`	bool	`False`	Replace all occurrences

If old_str is not found, or is found multiple times while replace_all=False, the tool returns an error so you can refine the match.

MoveFile¶

Move or rename a file or directory.

Parameter	Type	Default	Description
`source`	str	—	Source path
`destination`	str	—	Destination path
`overwrite`	bool	`False`	Overwrite an existing destination
`create_dirs`	bool	`False`	Create missing parent directories
`preserve_metadata`	bool	`True`	Preserve timestamps/permissions

DeleteFile¶

Parameter	Type	Default	Description
`filepath`	str	—	File to delete
`force`	bool	`False`	Allow deleting directories too

RemoveDirectory¶

Parameter	Type	Default	Description
`directory`	str	—	Directory to remove
`recursive`	bool	`False`	Remove contents recursively
`force`	bool	`False`	Ignore errors (e.g. missing directory)

Tips¶

Use respect_gitignore=True (the default) when listing or searching to skip build artifacts and dependencies. A .janitoignore file in the working directory is always respected, even when respect_gitignore=False, and the .janitoignore file itself is automatically ignored so it never shows up in listings or search results.
Use ReadFile with start_line/max_lines for large files to limit output. To read the end of a long file (logs, changelogs) use a negative start_line (e.g. start_line=-30 for the last 30 lines) — you don't need to know the file length first, and an offset deeper than the file just returns it whole.
Use count_only=True with the search tools to gauge how many matches exist before pulling full results.
Use exclude with the search tools to skip directories or files you don't care about, e.g. exclude="node_modules/* dist/*". Patterns are matched against the full relative path and the basename, so both skip/* and skip work to exclude a directory.
Provide enough context in old_str for ReplaceTextInFile so it matches exactly once, or set replace_all=True intentionally.

Direct CLI Testing¶

Every file tool can be run directly for testing, outside of chat:

python -m janito.tools.files.list_files . --pattern "*.py" --recursive
python -m janito.tools.files.read_file README.md --start-line 1 --max-lines 20
python -m janito.tools.files.search_text . "TODO"

Add --json for machine-readable output.