glob

Search the workspace for files and folders matching a glob pattern and receive both a structured matches array and a human-readable summary. Use this whenever you need to find files or folders by name patterns across the project — it is fast, deterministic, and respects sandbox policy.

import { createAgent } from "@comma-agents/core";

const agent = createAgent({
  name: "explorer",
  model: "openai/gpt-4o",
  tools: ["glob"],
});

GlobToolConfig

Optional caps for the factory.

GlobMatch

One match returned in data.matches.

GlobData

The full structured payload.

Usage Examples

Match all TypeScript files:

await tool.glob({ pattern: "**/*.ts" });

Match all directories ending with -folder:

await tool.glob({ pattern: "*-folder" });

Exclusions and Sandbox Policy

By default, standard project directories (node_modules, .git, dist, build, .next, .turbo, coverage) are excluded from search and traversal. You can pass a custom excludeGlobs array to override this.

Entries blocked by forbiddenGlobs or by the sandbox read policy are filtered silently. The tool only fails with permission_denied when the searched root itself is unreadable.

Errors

Related

• list_directory — enumerate a single directory.
• search_files — search file contents using text or regex.