@archships/dim-plugin-grep-glob

Official supported filesystem search plugin for dim-agent-sdk.

What it adds

• glob: list files that match a glob pattern
• grep: regex-first content search with grouped output, pagination, and file/count modes

Permissions

• requests fs: 'read'

Usage

import { createAgent, createModel } from '@archships/dim-agent-sdk'
import { createGrepGlobPlugin } from '@archships/dim-plugin-grep-glob'

const agent = createAgent({
  model: createModel(adapter),
  plugins: [createGrepGlobPlugin()],
  includeBuiltinTools: false,
})

Path overrides

path accepts relative and absolute file or directory paths. Relative paths resolve against the active session cwd; absolute paths keep their absolute location. File paths are converted to their parent directory plus a basename filter so grep and glob can target one file.

Glob behavior

glob now returns richer discovery metadata and accepts:

• pattern: glob pattern to match
• path: optional file or directory path
• limit: optional maximum number of returned files; defaults to 100
• sortBy: mtime or path; defaults to mtime

The tool renders a summary line plus file paths in text output, and exposes files, numFiles, truncated, durationMs, resolved path, and sortBy in structuredContent.

Example:

{
  "pattern": "src/**/*.ts",
  "path": ".",
  "limit": 20,
  "sortBy": "mtime"
}

Grep behavior

grep now defaults to grouped content output and accepts:

• pattern: regex pattern to search for
• path: optional file or directory path
• include or glob: optional file glob filter
• outputMode: content, files, or count
• beforeContext, afterContext, context
• ignoreCase, lineNumbers, headLimit, offset, multiline, timeoutMs

It also accepts compatibility aliases such as output_mode, head_limit, -A, -B, -C, -i, and -n.

Example:

{
  "pattern": "createAgent\\(",
  "include": "*.{ts,tsx}",
  "outputMode": "content",
  "context": 1,
  "headLimit": 20,
  "timeoutMs": 3000
}

Notes

• tool execution uses the standard file system gateway
• official glob / grep tool path overrides resolve relative paths against the active cwd and accept absolute paths
• grep remains regex-first, but now defaults timeoutMs to 3000 and forwards it to the filesystem gateway
• content mode pre-bounds regex scanning when headLimit > 0, so early pages do not always scan the full repository
• regex mode rejects high-risk constructs such as lookbehind, backreferences, and broad repeated groups, and uses bounded regex search budgets with input-size caps
• the plugin also injects prompt guidance that tells models to narrow path / include, prefer glob before open-ended grep, and reduce scope after timeouts
• this plugin is covered by the centralized plugin integration smoke tests