Skip to slide
034 / 221

CH 03 · Tool Design · 07/18

Read as one page

Real code: OpenCode's grep returns a small, capped answer

OpenCode is an open-source coding agent written in TypeScript, and it ships both halves of this pairing. Its read tool is the expensive one: a file of 50 KB or less, read with no offset or limit, comes back in one call, and a larger file is paged at 2000 lines or 50 KB, whichever comes first. Its grep tool is the cheap one, and the read tool's own description says so: "use grep to find specific content in large files." Watch how grep keeps its answer small, and how it admits when it cut something.

const limit = input.limit ?? FileSystem.DEFAULT_SEARCH_LIMIT // [1]
const matches = yield* ripgrep
  .grep({
    cwd,
    pattern: input.pattern,
    // ... (4 lines: single file, include glob, literal, case sensitivity)
    limit: limit + 1, // [2]
  })
  // ... (24 lines: timeout, rewrite paths relative to the project)
return { matches: matches.slice(0, limit), truncated: matches.length > limit } // [3]

Source: anomalyco/opencode, packages/core/src/tool/plugin/grep.ts (MIT)

/** Format raw search matches into concise model content. */
export const toModelContent = (matches: EncodedOutput, truncated = false) => {
  const lines = matches.length === 0 ? ["No matches found"] : [`Found ${matches.length} matches`] // [4]
  let current = ""
  for (const match of matches) {
    if (current !== match.entry.path) { // [5]
      if (current) lines.push("")
      current = match.entry.path
      lines.push(`${match.entry.path}:`)
    }
    lines.push(`  Line ${match.line}: ${match.text}`)
  }
  if (truncated)
    lines.push(
      "",
      `(Results are truncated: showing first ${matches.length} results. Consider using a more specific path or pattern.)`, // [6]
    )
  return lines.join("\n")
}

Source: anomalyco/opencode, packages/core/src/tool/plugin/grep.ts (MIT)

What to notice

  1. [1] DEFAULT_SEARCH_LIMIT is 100 (set in filesystem.ts). The model may pass its own limit; if it says nothing, the answer holds at most 100 matching lines. ripgrep is the fast command-line search program running underneath. yield* runs that search and unwraps the matches.
  2. [2] Grep asks ripgrep for one more row than it will show. Ripgrep's reader takes one past that request (Stream.take(input.limit + 1) in ripgrep.ts) and, if the extra row arrived, returns only the requested count. Grep still sees one spare row, slices it off, and sets truncated.
  3. [3] It keeps the first limit rows (100 if the model passed none) and sets truncated when a spare row came back.
  4. [4] toModelContent builds the text the model reads. EncodedOutput is the plain list of matches: each has a path, a line number, and a text preview. Before this function is called, each path is resolved against the project directory, so the model sees absolute paths. The matches value in the return above stays relative. The text leads with the count, and "No matches found" is an explicit answer, not an empty string to interpret.
  5. [5] Matches are grouped under their file path, so each path appears once, and each match is one line: a line number and a preview (ripgrep.ts cuts any preview past 2,000 characters).
  6. [6] When results were cut, the model is told so, and told what to do next.

One grep call costs about one line per match and points at the file and line to read next. A grep that dumped every match in a big repository could cost more than the read it was meant to replace.

Read it yourself: open packages/core/src/tool/plugin/read.ts, the expensive half. Read the tool's description, then find toModelContent near the bottom and answer: what does the model see when a file is longer than one page? Expect a note naming the exact offset to continue from. One notice tells the model where to continue; grep's tells it to search more narrowly.

Finished this idea?

Your learning progress stays in this browser.