Tools

Grepticon hands your agent four read-only tools, named after their command-line counterparts so a model's existing priors carry over: ls, find, cat, and grep. Every output is plain text, and every truncation or empty result ends in a steering footer that tells the agent its next move. This page is the conceptual and usage guide; for exact parameters and response schemas, see the Read API reference.

You don't call these tools yourself in an agent loop — you hand them to the model with createVfsTools(session) (see the Quickstart) and it decides which to use. Understanding how they behave helps you reason about what your agent will do.

ls — see the layout

Lists the immediate children of a directory (default /, the workspace root), directories first, then files with their text sizes. Because directory names usually map the topics, ls is how an agent orients: list the root to learn the shape, then list into the directory most related to the question — the listing often names the exact file to read. ls shows up to 1,000 entries; past that, switch to find with a pattern.

find — locate files by name

Globs over the workspace's file paths — **/*.md, reports/**/q3*. A bare name matches literally and exactly; for a substring match, wrap it in stars (**/*billing*). Results come newest-first, capped by head_limit (default 100, up to 1,000). Use find when you know something about the path; use ls to explore structure rather than guessing patterns.

cat — read a file

Reads a file's text with line numbers, cat -n style. offset (1-based) and limit page through large files. The line numbers are the point: they compose with grep, which reports matches as path:512:…, so an agent greps to find the line and then cats around that offset. Large responses are truncated with a footer naming the offset to continue from, and very long lines are cut with a marker. Binary originals like PDFs are served as their extracted text — an agent reads them exactly like Markdown.

grep — search contents

Searches file text with an RE2 regular expression (the same family as ripgrep: literals, character classes, alternation, quantifiers, and anchors all work; backreferences and lookaround do not). Two habits make grep effective:

• Search stems and synonyms, not question phrasing. The documents rarely use the words your user did. For "how fast do they stop", grep halt|brake|stop, not how fast. One or two words per attempt beats a long phrase, and several cheap greps with different wordings beat one perfect pattern.
• Start broad, then narrow. output_mode defaults to files_with_matches — the matching file paths, densest first. Use it to find the right file, then cat it; switch to content (lines as path:line:text, with -A / -B / -C context) when you want the matches themselves, or count for a tally. Add -i for case-insensitivity (a good default) and a glob like *.md to filter candidates.

A zero-match grep isn't a dead end — it's a signal to reword and try again.

How an agent navigates

The tools compose into a natural retrieval loop, no index required:

1. ls the root to learn the workspace's shape.
2. grep a stem (or find a path) to locate the right file.
3. cat that file — whole, or around a grep's line number — to read the answer.

Every step is scoped by the reading token's claims, so an agent only ever sees — and searches — the files it's permitted to. See Access control.

The semantic cut

Grepticon deliberately ships no semantic search and no embedding index. There is no search tool, no vector store, no chunking step — retrieval is literal search over whole files. This is a design choice, not a missing feature:

• Whole files, read directly. Skipping chunking and embeddings removes the usual failure modes — stale indexes, chunk-boundary context loss, and embedding drift — and lets the model reason over complete documents.
• Grep is fast and exact. The RE2 engine matches in linear time (no catastrophic backtracking on user patterns), and a good agent compensates for vocabulary gaps by trying synonyms and stems the way a person greps a codebase.

In head-to-head evaluation, this filesystem-plus-grep approach out-scores naive top-k RAG on answer accuracy — the numbers and method are on the Benchmark page.

Reference

For each tool's exact parameters, defaults, and response envelope, see the generated Read API reference.