Reference · Configuration

Configuration

.rei/config.json: checks, GitHub Issues integration, viewer and exit codes.

checks · GitHub Issues · viewer · codes 0/1/2

The file

.rei/config.json is the project configuration for the harness: it declares the quick checks that rei check runs, the optional GitHub Issues integration and the viewer's behavior. It lives at the root of .rei/ and is written by rei init; afterwards it is edited by hand or with the commands that modify it.

.rei/config.json
{
  "checks": [
    {
      "id": "V1",
      "description": "ESLint del proyecto",
      "command": ["pnpm", "lint"]
    },
    {
      "id": "V4",
      "description": "Tests de lógica y datos",
      "command": ["pnpm", "test"]
    }
  ],
  "integrations": {
    "github": {
      "enabled": true,
      "repo": "owner/name",
      "base": "main",
      "mergeStrategy": "squash"
    }
  },
  "viewer": {
    "autoOpenOnReady": true
  }
}

The three keys are independent: you can declare checks without GitHub Issues and configure the viewer without checks. The absence of integrations.github means the integration is disabled.

checks

checks is an array of quick checkpoints. rei check runs them, in addition to its own harness checks, and reflects the result in its exit code.

FieldContent
idStable identifier of the checkpoint, such as V1 or V4.
descriptionWhat the check validates, in one sentence.
commandArray of the command's arguments. It runs without an intermediate shell.
  • command does not interpret redirections, pipes or shell variables: each element of the array is a literal argument.
  • Only quick checks go here. The full build, e2e or integration are documented in .rei/docs/project/verification.md and run when the Work Item is closed.
  • The ids and commands must match the checkpoints declared in the project documentation.

integrations.github

The GitHub Issues integration is optional and is configured under integrations.github. The CLI never calls GitHub: the commands only write this configuration and the agent runs the actions with gh and git.

FieldValue
enabledtrue enables the integration; false disables it and keeps repo, base, mergeStrategy and the local links.
repoTarget repository in owner/name format. It has no default value: without a flag or previous value it is detected from the origin remote.
baseFallback base branch. It uses main when there is no previous value or detection from origin/HEAD.
mergeStrategyPR merge strategy: squash, merge or rebase. It uses squash by default.

base is only the fallback: the effective base is decided per Work Item at the gate and lives in links.json, not in .rei/config.json. rei github status is offline and does not know the effective base of each Work Item.

viewer

viewer.autoOpenOnReady is a boolean. With true, the Leader opens the viewer with rei view <id> --open at the approval gate, without blocking the conversation. With false or without the key, it runs nothing and the flow is identical.

  • rei view --enable turns on viewer.autoOpenOnReady in .rei/config.json.
  • rei view --disable turns it off.
  • Both flags only change that key and keep the rest of the file.
  • The viewer is read-only: it does not approve and does not modify documents, meta.json or the state of the Work Item.

Value precedence

rei github enable resolves each value with the same precedence: explicit flag > previous value of integrations.github > detection from git > default value. An enable without flags does not overwrite values that are already configured.

  1. The explicit flag wins: --repo owner/name, --base <rama> or --strategy squash|merge|rebase.
  2. If it is missing, the previous value of integrations.github is kept.
  3. If that does not exist either, it is detected from git: origin for repo and origin/HEAD for base.
  4. If detection fails, base uses main and mergeStrategy uses squash; repo has no default and requires a resolvable origin.

An unknown, repeated, valueless or invalid flag is incorrect usage (code 2) and does not write the configuration. Operational failures —invalid configuration, unresolvable remote or write error— exit with 1.

Exit codes

CodeMeaning
0The operation finished correctly, also when there were only warnings.
1A check failed or the command could not complete.
2Incorrect usage: unknown, repeated, valueless or invalid flag.

In checks, 0 means everything passed and 1 means there is at least one [FAIL] or a project check failed. rei test reports and exits 0 when no checks are configured. The exit code is the signal the workflow uses: a check is not disabled to make it pass.

Planning approval

Pending

A human sign-off releases the sheet. Silence is not approval.

Approval is recorded from the CLI; the viewer does not replace it.