How to Customize OpenCodeReview Output Format for JSON and Agent Workflows

Use --format json to emit structured data and --audience agent to suppress UI noise, enabling machine-readable output for CI pipelines and autonomous agents.

The alibaba/open-code-review CLI tool generates LLM-powered code reviews, but integrating these results into automated workflows requires customizing the output format. By leveraging specific flags defined in the source code, you can transform human-readable terminal output into structured JSON payloads optimized for programmatic consumption.

Core CLI Flags for Output Customization

OpenCodeReview exposes two orthogonal dimensions that control stdout behavior. According to the source code in cmd/opencodereview/shared_flags.go, the addOutputFlags function registers these options for every CLI command.

The --format Flag: JSON vs. Text

The --format flag accepts json as its primary alternative to the default text rendering. When specified, the emitRunResult function in cmd/opencodereview/review_cmd.go (and analogously in cmd/opencodereview/scan_cmd.go) serializes the internal Result type to a strict JSON payload rather than rendering colorized terminal output. Omitting this flag produces human-readable text with progress indicators and ANSI color codes.

The --audience Flag: Human vs. Agent

The --audience flag accepts human or agent, with the validateAudience function in shared_flags.go enforcing these values at runtime. When set to agent, the newQuietHandle function in cmd/opencodereview/shared.go mutes progress bars, interactive prompts, and other UI artifacts. This flag ensures clean stdout streams regardless of the chosen format.

Source Code Architecture for Output Handling

Understanding the implementation path helps troubleshoot formatting issues and build custom integrations.

Flag registration occurs in cmd/opencodereview/shared_flags.go, where addOutputFlags attaches both --format and --audience to the CLI parser.

Runtime silencing depends on newQuietHandle in cmd/opencodereview/shared.go, which instantiates a quiet handler when audience == "agent", preventing UI noise from reaching stdout.

Result emission happens in cmd/opencodereview/review_cmd.go via emitRunResult, which checks outputFormat == "json" to determine whether to marshal the Result struct or render text. The same pattern exists in cmd/opencodereview/scan_cmd.go for full-file scans.

JSON Schema and Payload Structure

The JSON structure mirrors the Result type defined in internal/result/result.go. This schema contains three primary fields:

• comments: An array of objects containing file path, line number, severity level, and message text for each issue detected.
• summary: A top-level markdown or HTML summary providing an overview of the review findings.
• metadata: Timestamps, LLM identity information, and original command-line options including the --audience value used during execution.

Practical Integration Patterns

Combine both flags for standard automation workflows that require clean, structured data.

CI Pipeline Integration

Capture the review as JSON for downstream dashboards and reporting systems:

ocr review --format json --audience agent > /tmp/review.json
curl -X POST -H "Content-Type: application/json" \
     -d @/tmp/review.json https://my-dashboard.example/api/reviews

Agent-to-Agent Data Flow

Feed structured reviews directly into downstream LLMs or automation agents that expect machine-readable input:

ocr review --format json --audience agent | my-agent --input-format json

Selective Field Extraction

Filter specific fields using jq without modifying the OpenCodeReview source code:

ocr review --format json --audience agent | jq '.comments'

Advanced Customization Strategies

When the default schema does not match your integration requirements, you have two pathways for customization.

Post-Processing Pipeline

Pipe the JSON output into a transformation script that unmarshals, mutates, and re-marshals the data to match your target schema. This approach requires no modifications to internal/result/result.go and adapts the output to bespoke dashboards or agent protocols.

Forking and Modifying the Result Type

For permanent schema changes, edit the Result struct and its serialization logic in internal/result/result.go, then rebuild the binary. This method alters the fundamental output structure that emitRunResult produces in review_cmd.go, allowing you to rename keys, embed additional context, or flatten nested structures.

Summary

• Use --format json to generate machine-readable structured output instead of colorized text, as implemented in review_cmd.go and scan_cmd.go.
• Use --audience agent to suppress progress bars and UI noise via newQuietHandle in shared.go, producing clean stdout for automation.
• Reference internal/result/result.go to understand the exact JSON schema containing comments, summaries, and metadata.
• Implement post-processing or fork the repository to customize the JSON payload structure for specific integration requirements.

Frequently Asked Questions

What is the default output format if I omit the --format flag?

OpenCodeReview defaults to human-readable, colorized text output designed for terminal review. The default value triggers standard UI rendering paths rather than the JSON serialization route in emitRunResult.

Can I use --audience agent without --format json?

Yes. The --audience agent flag independently suppresses interactive elements and progress indicators through newQuietHandle. When combined with the default text format, it produces plain text without color codes or UI artifacts, though JSON is typically preferred for agent consumption.

How do I exclude specific fields from the JSON output without modifying source code?

Use command-line JSON processors like jq to filter the output. For example, ocr review --format json --audience agent | jq 'del(.metadata)' removes the metadata object while preserving comments and summary data, allowing you to shape the payload to your specific schema requirements.

Does the JSON output contain color codes or formatting characters?

No. When --format json is specified, the emitRunResult function bypasses all UI rendering logic defined in shared.go, producing a pure data stream without ANSI color codes, progress indicators, or other terminal formatting artifacts.

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