Skip to content

INTERFACE.md

Latest commit

 

History

History
228 lines (169 loc) · 5.86 KB

INTERFACE.md

File metadata and controls

228 lines (169 loc) · 5.86 KB
Raw

agentgrep Interface

Design goal

The interface surface should be small, opinionated, and composable.

agentgrep should sit between:

  • rg: one powerful search primitive with many knobs
  • MCP-style retrieval systems: many specialized operations

The v1 sweet spot is a small number of strong commands with rich result shapes.

Primary commands

agentgrep grep <query>
agentgrep find <query>
agentgrep outline <file>
agentgrep trace <query>

Command semantics

agentgrep grep

Exact lexical search.

Use when the user wants:

  • exact content matches
  • predictable semantics
  • exhaustive results
  • enclosing-symbol grouping for easier triage
  • a compact hint of surrounding file structure
  • script-friendly behavior

Examples:

agentgrep grep auth_status
agentgrep grep --regex "auth_.*status"
agentgrep grep --type rs auth_status
agentgrep grep --json auth_status

agentgrep find

Ranked file/path discovery.

Use when the user wants:

  • likely files
  • approximate path/name lookup
  • identifier-form robustness
  • better file discovery than rg --files | rg

Examples:

agentgrep find auth status
agentgrep find debug socket
agentgrep find provider mod

agentgrep outline

File structure scan for a known file.

Use when the user wants:

  • symbol inventory for a file
  • start/end ranges for functions, impls, structs, headings, etc.
  • a cheap pre-read map of the file
  • structure without full body retrieval

Examples:

agentgrep outline src/tool/lsp.rs
agentgrep outline --path /repo src/tui/app/remote.rs
agentgrep outline --max-items 20 src/main.rs

agentgrep trace

Broad relation-aware tracing mode using a small structured DSL.

Use when the user wants:

  • one search that internally performs several lexical probes
  • relation-aware results
  • grouped files plus useful local structure
  • the smallest useful context packet
  • less ambiguity than freeform natural language

Examples:

agentgrep trace subject:auth_status relation:rendered
agentgrep trace subject:provider_name relation:comes_from support:config
agentgrep trace subject:scroll relation:handled support:event
agentgrep trace subject:lsp relation:implementation kind:code path:src/tool

Useful patterns:

  • kind:code to suppress docs-oriented results
  • path:src/... to bias toward or constrain a subtree
  • --paths-only when the caller only wants candidate files
  • --debug-score when tuning ranking behavior

Harness context

outline and trace may accept a harness-provided context file:

agentgrep outline --context-json /tmp/agentgrep-context.json src/tool/lsp.rs
agentgrep trace --context-json /tmp/agentgrep-context.json subject:auth_status relation:rendered

The context file should contain abstract familiarity/freshness/pruning signals rather than raw transcript mechanics. See docs/HARNESS_CONTEXT.md.

Non-UTF-8 filenames

Displayed paths are the lossy UTF-8 form of the native path. When a filename is not valid UTF-8, the displayed path gets a stable suffix derived from the invalid bytes (a\uFFFD.txt#b=ff for b"a\xff.txt"), so two files whose lossy names collide always render differently and consumers that dedup on the displayed path cannot silently drop one. JSON output additionally carries a path_bytes field (hex of the raw relative path bytes) for such files. agentgrep outline accepts these disambiguated display paths, so paths emitted by grep/find/trace round-trip. Internal file opens always use the native path bytes, never the display string.

Harness context files (--context-json) must key path fields by the path exactly as agentgrep displays it, i.e. the disambiguated form (a\uFFFD.txt#b=ff) for non-UTF-8 names. Matching is exact string equality: a bare lossy key (a\uFFFD.txt) does not match any byte-collider, so familiarity recorded by older harnesses under the lossy form degrades safely to "unknown file" (full, uncompressed output) instead of compressing the wrong file. Harnesses should record the path string from agentgrep output verbatim.

Non-Unix (Windows) limitation

Raw path bytes are only available on Unix, so the guarantees above are Unix-only. On non-Unix targets a filename that is not valid Unicode (for example a Windows name containing unpaired UTF-16 surrogates):

  • gets no #b= suffix and no path_bytes JSON field, so two such names whose lossy display strings collide are not distinguished in output;
  • is still opened correctly by the native walker paths (find, trace, outline, and native grep keep the real PathBuf), but the rg fast path rebuilds the file path from the lossy display string, so such a file's matches may be silently dropped (the rebuilt path does not exist) or, if a decoy file literally named with U+FFFD exists, read from the wrong file.

No mode panics on such names; degradation is display-level only. This is a known, accepted limitation until raw OsStr handling is wired up for Windows (WTF-8/WTF-16 round-tripping).

Shared flags

Output

--json
--no-color
--paths-only
--debug-score

Scope

--type <type>
--glob <glob>
--hidden
--no-ignore
--path <root>

Result budgeting

--max-files <n>
--max-regions <n>

Debug and trust

--debug-plan
--debug-score
--debug-structure

Later possible commands

Not part of the initial surface, but plausible later if clearly useful:

agentgrep outline ...
agentgrep symbols ...

The project should resist surface-area growth until grep, find, outline, and trace are excellent.

Philosophy by mode

grep = truth

  • exact
  • exhaustive
  • predictable
  • closer to rg

find = discovery

  • file-oriented
  • ranked
  • approximate and robust

outline = structure

  • known-file oriented
  • no ranking
  • line ranges and symbol map

trace = relation-aware investigation

  • grouped
  • structured
  • relation-aware
  • optimized for fewer follow-up reads