Codestin Search App

Two frontmatter fields decide what an agent scans. precondition decides whether the agent runs on this repository at all. where decides which files it reviews.

The precondition gate

Omit precondition and the agent always runs. Set it with a regex check, a prompt check, or both.

Form	Runs	Queues the agent when
`regex`	On disk. No model call.	Any sub-check matches.
`prompt`	One call to a large language model (LLM). It sees the recon brief.	The model answers yes.
Both	`regex` first	`regex` matches and the model answers yes.

The regex check runs first and costs nothing. When an agent declares both and the regex check does not match, the agent skips before it reaches the LLM call.

Regex sub-checks

Four sub-checks live under precondition.regex. Any one match queues the agent.

Sub-check	Queues the agent when
`extensions`	A file with one of these extensions exists.
`files`	A file matches one of these path globs.
`directories`	A directory matches one of these globs and holds at least one file.
`patterns`	A `regex` matches a line, inside `in` and outside `notIn`.

Each patterns entry sets regex, an optional label, and optional in and notIn glob lists. An empty in list means any file. No official agent uses directories today, but the schema and the evaluator both support it.

precondition:
  regex:
    extensions:
      - swift
      - m
      - mm
  prompt: Run only if this project uses ios — look for it in the manifest (package.json / composer.json / go.mod / etc.) and in the code.

From agentgg-agents/agents/mobile/ios-url-scheme.md. The regex check queues the agent for any Swift or Objective-C project. The prompt check narrows further with an LLM call.

The where scope

where sets the files an agent’s tool session starts from. The agent can still read more files with its Read, Glob, and Grep tools.

Key	Selects
`extensions`	Files by extension. The main knob for most agents.
`filePatterns`	Files by glob, directory, or exact path. Combined with `extensions`.
`excludePatterns`	Globs the agent stays out of. Added to the scan’s `--exclude` list.
`preFilter`	Anchors that narrow matched files to candidates. See below.
`maxFilesPerBatch`	Candidate files per investigation session. Default 5.
`maxTurnsPerBatch`	Tool-use turns allowed per session. Default 50 with a file scope, 150 without one.

Agents with no file scope

An agent that declares no extensions and no filePatterns has no file scope. It receives no candidate files and searches the whole repository itself with its Read, Glob, and Grep tools, in a single session, so maxFilesPerBatch and preFilter have nothing to narrow and do nothing. The 150 turn default applies only when maxTurnsPerBatch is absent, so an agent that loses its scope but keeps maxTurnsPerBatch runs on its own declared value instead. excludePatterns still applies, together with --auto-exclude and the default exclude set, so the agent is told to skip paths such as node_modules and build output. A scoped agent reports the files it reviewed against a known total. An unscoped one has no total to report against.

preFilter anchors

A preFilter entry narrows the matched files further. A file becomes a candidate only when at least one entry matches a line inside it. The matching line numbers and labels pass to the model as anchors.

Form	Matches on
`{ regex, label }`	A per-line regex. Cheap. Blind to the parsed syntax.
`{ semgrepRule, label }`	A named Semgrep rule. Matches the parsed syntax tree.

Semgrep rules as anchors

A semgrepRule value is a bare name, never a path and never a registry identifier. The CLI resolves the name in this order: first the directories passed to --semgrep-rules, then the catalog’s own semgrep-rules/ folder. It matches <name>.yml or <name>.yaml in the first directory that has one.

where:
  preFilter:
    - { semgrepRule: "http-endpoints", label: "HTTP request handler" }

From agentgg-agents/agents/auth/missing-access-control-semgrep.md. The name resolves to agentgg-agents/semgrep-rules/http-endpoints.yml, a rule that finds a route handler declared by file position instead of a path string, a pattern a per-line regex cannot express.

A full example

precondition:
  regex:
    patterns:
      - regex: export\s+(async\s+function|const|function)\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b
        in:
          - '**/app/**/route.{ts,tsx}'
          - '**/app/api/**/route.{ts,tsx}'
        label: App Router HTTP method export
  prompt: Run only if this project uses nextjs.
where:
  filePatterns:
    - '**/app/**/route.{ts,tsx}'
    - '**/app/api/**/route.{ts,tsx}'
  preFilter:
    - regex: export\s+(async\s+function|const|function)\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b
      label: App Router HTTP method export
  maxFilesPerBatch: 5
  maxTurnsPerBatch: 30

From agentgg-agents/agents/auth/js-nextjs-middleware-only-auth.md, trimmed. The precondition queues the agent only for a Next.js project with an exported route handler. The where scope hands the agent those same route files, with the export line as its anchor.

Get started

Help

Targeting

The precondition gate

Regex sub-checks

The where scope

Agents with no file scope

preFilter anchors

Semgrep rules as anchors

A full example

​The precondition gate

​Regex sub-checks

​The where scope

​Agents with no file scope

​preFilter anchors

​Semgrep rules as anchors

​A full example

The precondition gate

Regex sub-checks

The where scope

Agents with no file scope

preFilter anchors

Semgrep rules as anchors

A full example