# How to Customize OpenCodeReview Output Format for JSON and Agent Workflows

> Customize OpenCodeReview output to JSON or agent format. Learn how to generate machine-readable data for CI pipelines and autonomous agents with simple command-line options.

- Repository: [Alibaba/open-code-review](https://github.com/alibaba/open-code-review)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/review_cmd.go) (and analogously in [`cmd/opencodereview/scan_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/shared_flags.go) enforcing these values at runtime. When set to `agent`, the `newQuietHandle` function in [`cmd/opencodereview/shared.go`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/internal/result/result.go), then rebuild the binary. This method alters the fundamental output structure that `emitRunResult` produces in [`review_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/review_cmd.go) and [`scan_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/scan_cmd.go).
- **Use `--audience agent`** to suppress progress bars and UI noise via `newQuietHandle` in [`shared.go`](https://github.com/alibaba/open-code-review/blob/main/shared.go), producing clean stdout for automation.
- **Reference [`internal/result/result.go`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/shared.go), producing a pure data stream without ANSI color codes, progress indicators, or other terminal formatting artifacts.