JSON schema · skylakegrep

Reference · output schema

JSON shape.

--json writes a JSON array to stdout. Each element has the following fields:

[
 {
 "path": "skylakegrep/src/storage.py",
 "start_line": 197,
 "end_line": 271,
 "language": "python",
 "score": 0.824,
 "snippet": "def search(conn, query_embedding, top_k=10, …): …"
 }
]

path: Usually a project-relative indexed path. External filename or proactive lookup results may use an absolute path.
start_line, end_line: Inclusive 1-based line range of the chunk within path.
language: Tree-sitter language key, or the extension-derived key if the file used the fallback splitter.
score: Combined score (cosine plus lexical adjustment unless --semantic-only).
snippet: Verbatim source text of the chunk.

Compact agent JSON (0.8.0)

--agent-fast, --agent-context, --agent-slim and the MCP agent_context tool emit a compact shape by default (--format full restores the fields below). Each result keeps path (relative to the current directory when inside it), start_line, end_line, score (3 decimals), and, when present, confidence, evidence_terms, strict_verification and the first result's agent_summary (quality, confidence, missing_signal, likely_files not already shown, suggested_followup_probe). Added: lanes (recall lanes), also (supporting line ranges as [start, end], or [path, start, end] for another file) and source_type only when it is not source. Dropped: language, fallback, candidate_recall, search_intent, why_ranked, evidence_bundle and the supporting_chunks objects. Snippets keep the declaration and query-matching lines with ⋯ marking elided runs.

--agent-slim wraps the results as {"results": [...], "outline": [{"path", "lines": ["12: def f(...)"]}], "next": "skygrep symbols ..."}. skygrep symbols --json returns {"outline": [...]}, with truncated when the budget cut declarations and bodies (start, end, text) when --expand is set.

Optional evidence fields

Semantic-depth filename anchors can include extra evidence fields when the matched file has extractable text. These fields are additive and may be absent; scripts should treat them as optional:

fallback, filename_token: Retrieval provenance for filename-anchor results.
candidate_recall, candidate_recall_lanes: Optional 0.5.13 provenance for results surfaced by the adaptive candidate recall substrate. Lanes can include include-scope, path-token, symbol, chunk-text, or bounded ripgrep recall. Treat these as explanatory metadata; the required path / line / score / snippet fields are unchanged.
source_type, search_intent, evidence_terms, why_ranked: Optional agent-context ranking evidence: source category, inferred retrieval job, covered query terms, contributing recall lanes, source prior, and final score.
evidence_bundle, supporting_chunks: Optional primary and supporting line-range anchors used to provide bounded multi-part evidence without returning a full file.
agent_summary: Optional top-result summary with quality, calibrated confidence, confidence_basis (lexical-and-retrieval or retrieval-only), likely files, missing signal, and a scoped follow-up probe. Non-lexical queries never receive lexical coverage credit they could not produce.
strict_verification: Optional 0.7.0 high-risk evidence receipt emitted by --strict. It contains status (passed or inconclusive), initial/final quality, performed checks, independent recall lanes, semantic rank/agreement, evidence presence, indexed-source existence/freshness/mtime state, and an error string. Exit code 2 or any status other than passed must not be treated as verified.
query_excerpts: List of query-focused passages extracted from the anchored text/PDF/DOCX file.
content_excerpt: Joined query-focused passages, suitable for agent context.
content_preview, content_preview_truncated: Bounded full-text preview and whether it was clipped.
extracted_text_source, extraction_note: Extractor backend metadata, for example text passthrough, PDF text layer, DOCX parser, OCR note, or friendly extraction failure hint.