Understanding Output¶

After running code-context-agent index or code-context-agent analyze, all artifacts are written to the .code-context/ directory inside your repository root (configurable via --output-dir).

Directory Structure¶

.code-context/
├── CONTEXT.md                     # Executive summary with cross-cutting narrative
├── CONTEXT.signatures.md          # Compressed source signatures via repomix
├── CONTEXT.orientation.md         # Token-aware codebase overview via repomix
├── heuristic_summary.json         # Bridge between indexer and coordinator
├── analysis_result.json           # Structured analysis output (AnalysisResult model)
├── files.all.txt                  # Complete file manifest
├── bundles/
│   ├── BUNDLE.auth.md             # Per-area deep-dive narrative
│   ├── BUNDLE.hotspots.md
│   └── BUNDLE.{area}.md
├── tmp/
│   └── teams/
│       ├── team-structure/
│       │   ├── findings.md        # Raw team findings (markdown)
│       │   └── metadata.json      # Team execution stats
│       ├── team-history/
│       │   ├── findings.md
│       │   └── metadata.json
│       └── team_debug.jsonl       # Append-only debug log for all team runs
├── git_hotspots.json              # Git churn analysis
├── git_cochanges.json             # File co-change coupling data
├── semgrep_auto.json              # Semgrep auto-config findings
├── semgrep_owasp.json             # Semgrep OWASP Top Ten findings
├── typecheck.json                 # Type checker output (ty or pyright)
├── lint.json                      # Ruff linter output
├── complexity.json                # Radon cyclomatic complexity
├── dead_code_py.json              # Vulture dead code (Python)
├── dead_code_ts.json              # Knip dead code (TypeScript/JavaScript)
└── deps.json                      # Dependency tree (pipdeptree or npm)

Coordinator Output Files¶

CONTEXT.md¶

The executive summary produced by the coordinator agent via the write_bundle tool (called with is_context=True). This is the primary output for human consumption.

CONTEXT.md provides a cross-cutting narrative that synthesizes findings from all specialist teams. It covers:

• High-level architecture description
• Key business logic locations
• Architectural risks and their severity
• Cross-cutting concerns that span multiple areas
• Refactoring recommendations

bundles/BUNDLE.{area}.md¶

Per-area deep-dive narratives generated by the coordinator. Each bundle follows a seven-section structure:

1. One-paragraph summary — what the area does in business terms
2. Key files — ranked list with role descriptions and file:line ranges
3. Call flow — how data/control flows through the area (mermaid diagrams)
4. Blast radius — what breaks if you change this area
5. Risk assessment — security, complexity, coupling, test coverage
6. Change guidance — where to start, what to watch out for
7. Git context — ownership, churn frequency, implicit coupling

Bundles are generated for:

• The --focus area (if specified) — always gets a dedicated bundle
• High blast radius areas (extreme fan-in/fan-out)
• Hot spots (high churn combined with high complexity)
• Critical business logic areas

tmp/teams/{id}/findings.md¶

Raw findings written by specialist team agents during their investigation. Each team writes its findings to a dedicated directory under tmp/teams/.

Findings are in markdown format and include:

• File and line references for all claims
• Mermaid diagrams for architecture and call flows
• Answers to key questions posed by the coordinator

tmp/teams/{id}/metadata.json¶

Execution metadata for each team run:

{
  "files_read": ["src/auth.py", "src/middleware.py"],
  "tools_used": ["gitnexus_context", "read_file_bounded", "rg_search"],
  "duration_s": 142.3,
  "status": "done"
}

analysis_result.json¶

The structured output of the full analysis, serialized from the AnalysisResult Pydantic model. Contains:

Indexer Output Files¶

These files are produced by the deterministic indexer (code-context-agent index) without any LLM calls. They serve as input to the coordinator agent and the verdict engine.

heuristic_summary.json¶

The bridge artifact between the deterministic indexer and the LLM-powered coordinator. It aggregates all indexer outputs into a compact JSON structure that tells the coordinator what to focus on.

{
  "volume": {
    "total_files": 847,
    "total_lines": 52340,
    "estimated_tokens": 130850,
    "languages": {"py": 312, "ts": 485, "go": 50}
  },
  "health": {
    "semgrep_findings": {"critical": 0, "high": 2, "medium": 8, "low": 15, "info": 3},
    "owasp_findings": {"injection": 1, "auth": 2},
    "type_errors": 14,
    "lint_violations": 42,
    "dead_code_symbols": 23,
    "avg_cyclomatic_complexity": 4.7
  },
  "git": {
    "total_commits_analyzed": 1520,
    "active_contributors": 8,
    "most_coupled_pairs": [
      "src/api/routes.py <-> src/api/handlers.py",
      "src/models/user.py <-> src/services/auth.py"
    ]
  },
  "complexity": {
    "top_complex_functions": [
      {"name": "process_request", "file": "src/handler.py", "lines": "42-128", "complexity": 18}
    ],
    "bus_factor_risks": ["src/legacy/ (1 contributor, 47 files)"]
  },
  "gitnexus": {
    "indexed": true,
    "repo_name": "my-project",
    "community_count": 12,
    "process_count": 34,
    "symbol_count": 2060,
    "edge_count": 4161,
    "top_communities": [
      {"name": "API Layer", "symbols": 245, "cohesion": 0.82}
    ]
  },
  "mcp": {
    "context7_available": true
  }
}

CONTEXT.signatures.md¶

Compressed source signatures generated by repomix with tree-sitter body stripping. Contains function and class signatures with bodies removed, providing a token-efficient overview of the codebase's public API surface.

Generated with:

repomix --compress --remove-comments --remove-empty-lines --style markdown

CONTEXT.orientation.md¶

Token-aware codebase overview generated by repomix. Provides a hierarchical directory tree with per-file token counts (up to 300 entries), giving the coordinator a sense of where complexity lives.

Generated with:

repomix --no-files --style markdown --token-count-tree 300

files.all.txt¶

Plain text file listing every file in the repository (one per line, relative paths). Used by the BM25 search index for fast text search.

Static Analysis Outputs¶

All static analysis files are optional — the indexer skips any tool that is not installed and continues with the remaining steps.

semgrep_auto.json¶

Results from semgrep --config auto. Contains general code quality and security findings in semgrep's native JSON format. Findings are grouped by severity (critical, high, medium, low, info).

semgrep_owasp.json¶

Results from semgrep --config p/owasp-top-ten. Specifically targets the OWASP Top Ten vulnerability categories. Findings are grouped by category (e.g., injection, auth, crypto).

typecheck.json¶

Type checker output from either ty (preferred) or pyright (fallback). Only produced for Python projects. Contains diagnostic entries with file, line, and error message.

lint.json¶

Ruff linter output in JSON format. Contains lint violations with rule codes, file locations, and messages.

complexity.json¶

Radon cyclomatic complexity analysis for Python files. JSON dict mapping file paths to lists of function complexity entries:

{
  "src/handler.py": [
    {"name": "process_request", "lineno": 42, "endline": 128, "complexity": 18, "type": "function"}
  ]
}

dead_code_py.json¶

Vulture dead code detection results for Python (minimum confidence 80%). Array of entries:

[
  {"file": "src/utils.py", "line": 15, "message": "unused function 'old_helper'"}
]

dead_code_ts.json¶

Knip dead code detection results for TypeScript/JavaScript projects. Uses knip's JSON reporter format.

deps.json¶

Dependency tree from pipdeptree --json (Python) or npm ls --json --depth=1 (Node.js). Provides a snapshot of the project's dependency graph.

Git Analysis Outputs¶

git_hotspots.json¶

Top 30 most frequently changed files across the last 200 commits:

{
  "hotspots": [
    {"path": "src/api/routes.py", "commits": 45, "percentage": 22.5}
  ],
  "total_commits_analyzed": 200
}

git_cochanges.json¶

Co-change coupling data for the top 10 hotspot files. Shows which files tend to change together, indicating implicit coupling:

{
  "src/api/routes.py": {
    "file_path": "src/api/routes.py",
    "total_commits": 45,
    "cochanged_files": [
      {"path": "src/api/handlers.py", "count": 38, "percentage": 84.4}
    ]
  }
}