Cavecrew-Investigator Agent Output Format: Structure and Syntax Rules

The cavecrew-investigator agent outputs code locations as three-field lines grouped under category headers, using a strict token-efficient syntax with file paths, back-ticked symbols, and six-word notes.

The cavecrew-investigator is a read-only code-location tool within the Caveman ecosystem designed to trace symbols across a codebase. According to the JuliusBrussee/caveman source code in agents/cavecrew-investigator.md, this agent formats findings to maximize token efficiency while maintaining readability for AI systems and developers investigating definitions, references, and test coverage.

Core Output Syntax

Every line produced by the cavecrew-investigator follows a rigid three-field structure designed for rapid scanning. Each field is separated by an em dash (—):

1. File path and line number – The exact location using the format <path:line>.
2. Symbol – The code symbol or string literal wrapped in backticks (`).
3. Brief note – A contextual description strictly limited to six words or fewer.

This format ensures that each result consumes minimal tokens while delivering precise location data and human-readable context.

Category Headers and Grouping

When the agent locates three or more results belonging to the same semantic category, it groups them under a one-word header. The header is followed by a colon and the relevant lines appear as bullet points beneath it.

The six supported category headers are:

• Defs: – Definitions of the queried symbol.
• Refs: – References to the symbol throughout the codebase.
• Callers: – Call-sites where a function is invoked.
• Tests: – Test files that exercise the symbol.
• Imports: – Import statements involving the symbol.
• Sites: – Generic usage sites that do not fit other categories.

If fewer than three results exist for a category, the agent omits the header and prints the lines directly to reduce vertical space.

Special Output Cases

The cavecrew-investigator handles edge cases with specific formatting rules defined in agents/cavecrew-investigator.md.

Single Match Output

When only one hit exists across all categories, the agent strips all headers and outputs a single standalone line. This eliminates unnecessary structure for trivial queries.

No Matches Response

If the search yields zero results, the agent returns the literal string:

No match.

This consistent negative response allows automated systems to detect empty result sets without parsing complex structures.

Summary Totals Line

At the end of grouped output, the agent may append a totals line summarizing the distribution of findings across categories. The format uses comma-separated counts:

2 defs, 3 callers, 1 test file.

The agent omits this summary line when the total result count is zero or one, as the individual lines provide sufficient information in those cases.

Source Implementation

The formatting specification resides in agents/cavecrew-investigator.md (lines 18–28 and 45–57), which defines the agent’s behavior, output schema, and tool integrations. The agent itself is registered within the Caveman ecosystem via agents/agents.json, linking the definition to the executable system architecture documented in docs/technical/architecture.md.

Usage Examples

The following examples illustrate the formatting rules as implemented in the Caveman source code.

Single Definition Result

When querying a unique symbol definition, the output appears as a single line without headers:

hooks/caveman-config.js:81 — `safeWriteFlag` — atomic write w/ O_NOFOLLOW

Multiple Results with Grouping

A query returning several categories triggers header grouping and a totals summary:

Defs:
- hooks/caveman-config.js:81 — `safeWriteFlag` — atomic write w/ O_NOFOLLOW
- hooks/caveman-config.js:160 — `readFlag` — paired reader
Callers:
- hooks/caveman-mode-tracker.js:33,87
- hooks/caveman-activate.js:40
Tests:
- tests/test_symlink_flag.js — 12 cases
2 defs, 3 callers, 1 test file.

Note that the Callers category omits the symbol field and brief note when listing multiple line numbers for the same file, collapsing them into a comma-separated list.

Empty Result Set

A failed lookup returns the minimal negative response:

No match.

Summary

• The cavecrew-investigator outputs three fields per line: file location, back-ticked symbol, and a ≤6-word note.
• Results group under one-word headers (Defs, Refs, Callers, Tests, Imports, Sites) only when three or more items share a category.
• Single matches render as standalone lines without headers; zero matches return No match..
• A totals line appears at the end for multi-category results, omitting categories with zero hits.
• The formatting rules are codified in agents/cavecrew-investigator.md and registered in agents/agents.json.

Frequently Asked Questions

What is the maximum length of the descriptive note in cavecrew-investigator output?

The brief note field is strictly limited to six words or fewer. This constraint ensures token efficiency while providing just enough context to distinguish similar symbols or explain the code's purpose.

When does the cavecrew-investigator omit category headers from its output?

The agent omits category headers when fewer than three results exist for that specific category. Additionally, if only a single hit exists across the entire search, the agent outputs a plain line without any headers. Headers are only rendered to organize three or more related entries.

How does the cavecrew-investigator indicate an empty search result?

When no matches exist for the queried symbol, the agent outputs the literal text No match. on its own line. This standardized negative response allows automated parsing without requiring JSON or complex error structures.

Where is the output format specification defined in the Caveman repository?

The complete formatting specification, including the three-field syntax and header rules, is defined in agents/cavecrew-investigator.md (specifically around lines 18–28 and 45–57). The agent's registration and integration within the broader system architecture is handled in agents/agents.json.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}