file_search

Gate: ungated · belongs to file · read

Find files by name or path pattern. A pattern without / matches file names anywhere below the search root (*.md); a pattern with a / matches the path relative to that root. Ungated, like the other file reads — see the file kind.

Input

Field	Type	Required	Notes
pattern	string	yes	Glob, e.g. *.md or notes/*.md.
path	string	no	Directory to search from. Omit for the workspace root.

Output

A JSON array of workspace-relative paths:

["notes/todo.md", "notes/2026/plan.md"]

A broad sweep stops at 500 matches and appends a (truncated at 500 results) line after the JSON — so a wide glob degrades visibly instead of silently.

From JavaScript

wrapper (idiomatic)

const hits = await nocturn.fs.search("*.md", "notes");

nocturn.call

const raw = nocturn.call("file_search", { pattern: "*.md", path: "notes" });
const hits = JSON.parse(raw.split("\n")[0]);

Notes

The wrapper already splits the truncation note off before parsing; with the generic form you do it yourself, as above.