CodeRoast

CodeRoast is an agent-based architecture for generating evidence-bound code reviews and "roasts" with strong separation between deterministic analysis and constrained narration.

Overview

This repository currently contains the architecture specification in AGENTS.md. The design focuses on deterministic data extraction first, followed by a tightly constrained generative step for human-readable output.

Architecture

Pipeline:

CLI Agent
  -> Repo Scanner Agent
  -> Code Analysis Agent
  -> Insight Aggregator Agent
  -> Evidence Guard Agent
  -> Roast Narrator Agent
  -> Output Formatter Agent

Agents at a Glance

• CLI Agent: parses commands and orchestrates the pipeline
• Repo Scanner Agent: discovers files, languages, and entry points
• Code Analysis Agent: extracts structural signals and metrics
• Insight Aggregator Agent: merges findings and ranks issues with confidence
• Evidence Guard Agent: validates evidence completeness and gates narration
• Roast Narrator Agent: generates explanation constrained to evidence
• Output Formatter Agent: renders final output for the terminal

Design Principles

• Deterministic before generative
• Single responsibility per agent
• Evidence-bound communication
• Graceful degradation when generative steps fail

Hallucination Safeguards

• No raw code is sent to the narrator
• Narration is limited to known signals and evidence
• Evidence completeness is validated before narration
• Confidence is attached to every issue

Getting Started

Prerequisite: Node.js 20+ (required by @google/genai).

Install (npm)

npm install -g coderoast

Run:

coderoast --path . --severity savage --focus architecture

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. (Optional) Enable Gemini narration (Google Gen AI SDK):

set GEMINI_API_KEY=your_api_key

You can also add it to a .env file at the project root (see .env.example):

GEMINI_API_KEY=your_api_key

The Google Gen AI SDK also supports GOOGLE_API_KEY if you prefer that name.

Optional overrides:

GEMINI_MODEL=gemini-2.5-flash
GEMINI_API_VERSION=v1

If you see a model not found error, set GEMINI_MODEL to an available model (for example, gemini-3-flash-preview if your API access includes it) or specify GEMINI_API_VERSION. The SDK defaults to beta endpoints unless you set an API version.

4. Run the CLI:

npm start -- --path . --severity savage --focus architecture

To include raw evidence and patch diffs in the output, add --details:

npm start -- --path . --severity savage --focus architecture --details

You can cap the evidence list with --details-limit (default is 3 when details are shown). Use --details-limit=0 to show all evidence lines.

5. (Optional) Preview evidence-locked fixes:

npm start -- --path . --fix

Fix-It only outputs patch previews and does not edit files.

6. (Optional) Proof-locked apply (new branch + tests):

npm start -- --path . --fix --apply-fixes

Optional flags:

• --fix-branch <name>: name the branch to create (default is coderoast-fix-<timestamp>).
• --fix-test-cmd "<cmd>": override the test command (default is npm test).
• --fix-debug: save raw Gemini patch output to a temp file for debugging.
• --fix-limit <n>: limit how many Fix-It attempts to run.

Scripts

• npm run lint - run ESLint
• npm run lint:fix - auto-fix lint issues
• npm run demo:fix - create a demo repo and run Fix-It (requires GEMINI_API_KEY for suggestions)
• npm run demo:judge - run a judge-style report on the current repo (--details + --fix)
• npm run typecheck - run TypeScript in no-emit mode
• npm run build - compile to dist/
• npm start - run the compiled CLI
• npm test - build and run the test suite

Project Structure

• src/index.ts - CLI entry point
• src/pipeline.ts - agent pipeline orchestrator
• src/agents/ - agent implementations
• src/types.ts - shared types and schemas

Learn More

See AGENTS.md for the full specification and detailed agent responsibilities.