Review

Validate files against your standards — source code, documents, CSVs, and more.

orkai review runs an LLM-driven check against standards you declare in .orkai.yaml. It started as a developer tool for repos, but the same mechanism works for any text file — markdown reports, CSV exports, investigation drafts — as long as you point the process at your standard and the files to validate.

Each run writes a JSON report under .orkai/reports/ and exits non-zero on failure — useful for pre-commit hooks, local CI, or a final check before you submit work.

Setup

1. Activate orkai, run first-run setup with orkai serve, then keep the daemon up with orkai start (Daemon).
2. Register a chat provider: orkai review setup (writes chat.providers[] in ~/.orkai/config.yaml — see Configuration § chat).
3. In your project folder: orkai init, then orkai review init (merges a starter review: block into .orkai.yaml).
4. Write your standard as a markdown file (or reference a saved document ID) in knowledge_base.
5. Set include globs to the files you want checked, and pick the right mode (see below).
6. Run: orkai review or orkai review --process <name>.

Review modes

Every process picks one mode. Choose based on what you are validating, not only whether the file is code.

Important: diff and full both depend on git — they only review files that appear in a diff. For a CSV, report, or essay you want validated as a whole, use mode: project only. That is the mode that reads the entire file and checks it against your standard.

Review documents and data files

Save your rules once (column names, required sections, citation format, university layout), then re-run review whenever the file changes. Same workflow as code review — different include globs and mode: project.

Example — data analyst (CSV structure)

You maintain a standard for how export CSVs must look (headers, types, null handling). Review every file under exports/ before sharing with the team.

review:
  processes:
    - name: csv-exports
      mode: project
      strict: true
      knowledge_base:
        files:
          - standards/csv-export-schema.md
      include:
        - "exports/**/*.csv"

orkai review --process csv-exports

Example — student (investigation draft)

Your department publishes formatting rules (sections, word limits, citation style). Validate the draft before submission — the whole document, not a git diff.

review:
  processes:
    - name: thesis-draft
      mode: project
      strict: false
      knowledge_base:
        files:
          - standards/university-report-format.md
      include:
        - "drafts/investigation.md"

orkai review --process thesis-draft

strict: false is often enough for writing — only high-severity issues fail the run; style nits stay advisory. Use orkai review report --latest to read findings.

Review code (git workflows)

For day-to-day development, keep the default diff mode on staged changes:

orkai review                      # all processes, staged diff
orkai review --process arch       # one process
orkai review --base main --head HEAD
orkai review --silent --process arch   # CI-friendly summary only

Exit codes

• 0 — all processes passed (or advisory-only issues in non-strict mode)
• 1 — one or more failures or errors
• 2 — bad CLI usage or missing config

Report commands

orkai review history              # list past reports
orkai review history --failures
orkai review stats                # pass/fail rates, top issues
orkai review stats --by-standard
orkai review report <id>          # pretty-print one report
orkai review report --latest
orkai review tokens               # token usage rollup
orkai review clean --force        # delete saved reports

Config helpers

orkai review init     # starter review: block in .orkai.yaml
orkai review setup    # interactive LLM provider wizard
orkai review size --pattern 'exports/**/*.csv'   # token estimate before project mode

Knowledge base

Each process declares standards as local markdown/text files and/or saved document IDs:

review:
  processes:
    - name: arch
      mode: diff
      strict: true
      knowledge_base:
        files:
          - docs/architecture/standards.md
        documents:
          - 9a666a30-8bc1-41e6-8176-f3b92c1ce616
      include:
        - "internal/**"
      exclude:
        - "**/*_test.go"

Multiple standards in one process run as sequential sub-passes — one report per standard. Per-process model: selects which daemon-registered chat provider reviews that process.

Strict vs advisory

• strict: true (default) — any issue fails the run
• strict: false — only high-severity issues fail; medium/low are advisory

External process files: a process can use path: .orkai/review/csv-exports.yaml instead of an inline block. Run orkai review --help for the full flag list.