Remogram

Generic SCM/forge boundary CLI and MCP server. Emits provider-attributed JSON facts with SHA fields where applicable — git-resolved refs from local git (refs compare, sync plan) vs forge-reported PR SHAs from forge APIs (pr view, pr checks) — and no workflow or planning-tool concepts in output.

PR-by-number reconciliation: When pr view or pr checks is invoked with --number, Remogram compares the forge-reported forge_source_sha to the locally resolved git rev for forge_source_branch_ref (typically <remote>/<forge_source_branch_ref>). If they diverge, the packet is ok: false with error_code: stale_head and portable head refs — treat that as a signal to git fetch, not a forge outage.

Planning tools interpret intent and workflow authority outside Remogram — Remogram supplies forge facts only.

Install (beta)

See docs/public-beta.md for adoption, tiers, operator overlay, and MCP parity.

npm install -g @remogram/cli@beta @remogram/mcp@beta

From a git checkout (development):

git clone https://github.com/attebury/remogram.git
cd remogram
npm ci
./scripts/npm-link.sh

Default branch: main.

Beta limitations

• Read/plan by default — write_commands in .remogram.json (or a bound operator overlay — see below) opts in to Remogram CLI/MCP writes (cr_open on Gitea; status_set on Gitea/GitHub/GitLab; merge for Gitea merge execute). Unlisted writes → write_not_configured → use forge/CI on your system.
• Payload-size smoke compare is monorepo dev tooling only (not shipped in npm beta). For live cross-forge checks, use the remogram-smoke fixture repos.

Providers

Set "provider" in .remogram.json. Beta supports three forge backends — all use forge HTTP APIs (GitHub also uses GraphQL for PR view). You do not need official forge CLIs (gh, tea, or glab) installed.

Self-hosted Gitea/GitLab: add "baseUrl" to your forge root (see example patterns in provider notes below).

Check what your config enables:

remogram provider capabilities --json
remogram doctor --json

Provider capability tiers (Tier A v1)

Remogram reports an honest provider_tier on provider capabilities and in doctor --json when configured writes exceed what the provider tier supports:

When write_commands lists a Tier A write on a Tier B provider (for example cr_open on github-api), doctor --json emits a provider_tier_insufficient advisory. Tier metadata is also exported via remogram contract --json.

CLI wrapper providers (not supported in beta)

Each forge also has an official command-line tool. Remogram may eventually support optional wrapper providers that shell out to those binaries and normalize their JSON into the same typed packets as the API providers:

Do not use wrapper IDs in .remogram.json today. Only github-gh and gitea-tea exist as reserved placeholders; both return:

• ok: false
• error_code: "provider_unsupported"
• error_message: "Provider not implemented in v1"

There is no gitlab-glab provider ID in config yet — use gitlab-api.

The npm packages @remogram/provider-github-gh and @remogram/provider-gitea-tea exist only so the CLI can list those IDs honestly in provider capabilities (implemented: false). You never install or configure them separately.

Why wrappers are not supported yet

Beta focused on direct forge HTTP because it is the best fit for Remogram's constraints:

1. Agent-safe packets — Remogram caps forge ingest at 8192 bytes and selects fields explicitly (e.g. GitHub PR view uses GraphQL instead of full REST). Wrapper CLIs often emit large, version-dependent JSON that is harder to cap and normalize reliably.
2. Headless and CI-friendly — API providers need only a token env var. Wrappers require gh / tea / glab on PATH, their own login flows, and subprocess handling with the same trust rules as git.
3. One backend per forge for v1 — github-api, gitea-api, and gitlab-api implement the shared read/plan command surface with normalized packet shapes. Wrappers would duplicate that surface without adding new commands in beta.
4. Maintenance surface — CLI output changes between tool versions; each wrapper is an ongoing compatibility contract on top of the API adapters.

When or if wrappers will ship

Not in beta. There is no committed release date.

Wrapper providers are post-beta, demand-driven:

• If users need Remogram to reuse an existing gh / tea / glab login instead of managing API tokens, or policy blocks direct API access but allows official CLIs, we would implement wrappers behind the reserved IDs (and add gitlab-glab for parity with glab).
• Likely order if built: shared subprocess + JSON ingest helper in @remogram/core, then github-gh first (gh --json is the most stable), then gitea-tea and gitlab-glab.
• Until then: use the *-api providers above. They are the supported path for CLI, MCP, and agents.

If wrapper support matters for your setup, open a GitHub issue describing forge, CLI version, and whether API tokens are unavailable — that helps prioritize.

Consumer config

Copy .remogram.json.example to your repo root and set provider, owner, repo, and remote to match your project.

Example for GitHub:

{
  "version": "1",
  "provider": "github-api",
  "remote": "origin",
  "owner": "your-org",
  "repo": "your-repo"
}

Example for self-hosted Gitea:

{
  "version": "1",
  "provider": "gitea-api",
  "remote": "origin",
  "owner": "your-org",
  "repo": "your-repo",
  "baseUrl": "https://forge.example.com",
  "write_commands": ["cr_open", "status_set", "merge"]
}

Optional merge_policy relaxes check blockers on merge plan, merge execute, and cr inventory for repos with no CI. Production repos with CI should keep waivers off — remogram doctor --json fails when either flag is true in strict maintainer checkouts:

"merge_policy": {
  "allow_missing_checks": true,
  "allow_pending_checks": true
}

Env overrides: REMOGRAM_ALLOW_MISSING_CHECKS=1, REMOGRAM_ALLOW_PENDING_CHECKS=1. Doctor fails when enabled (not advisory). checks_conclusion remains observational; blockers[] is authoritative.

Operator write overlay (local, outside git)

Operators can grant write_commands without dirtying tracked .remogram.json using a bound local overlay. Copy .remogram.operator.json.example to a path outside the product repo (not committed by default).

Discovery order (highest wins):

1. CLI global flag --operator-config <path>
2. Env REMOGRAM_OPERATOR_CONFIG
3. Default: $XDG_CONFIG_HOME/remogram/operator/<provider>-<owner>-<repo>.json (fallback ~/.config/remogram/operator/…)

The overlay bind block must match the resolved forge identity (provider, remote, owner/repo, optional baseUrl). Mismatch → config_invalid and writes fail closed. Repo-only behavior is unchanged when no overlay is present. remogram doctor --json adds an operator_config check and per-command source attribution (repo | operator | both | none) under write_config.

Write opt-in: Remogram defaults to read/plan. To enable writes, add write_commands in .remogram.json or a bound operator overlay. cr open (Gitea first) requires "cr_open". merge execute (Gitea first, --method merge only) requires "merge". Without opt-in, write commands fail closed with write_not_configured. Use CLI or MCP for writes — direct provider package imports bypass the consumer gate (maintainer/tests only). merge execute re-reads view/checks/plan, cross-checks view/checks/forge head SHAs, verifies the live forge head branch tip matches --expected-head-sha, and requires --expected-base-sha / --expected-head-sha before forge POST; the Gitea merge POST includes head_commit_id pinned to the expected head SHA (forge 409 → head_ref_moved if the branch moved after preflight). For fork PRs, branch tip reads use pull.head.repo (Gitea pull payloads must include head.repo for fork detection); the forge token must have access to the head repository or preflight fails closed with head_ref_unreadable. When head.repo is absent, merge execute reads the configured repository branch instead. Emits cr_merged or cr_merge_blocked. Re-run with a fresh reviewed SHA if preflight or forge POST blocks. For cr open, read idempotency scan limits from remogram provider capabilities --json (idempotency_scan.max_pages, page_size, ingest_backoff) before opening CRs.

Write command boundaries: Each write id is a separate opt-in. Enabling cr_open alone does not enable merge execution — add merge for merge execute. Inspect configured vs supported writes with remogram provider capabilities --json and remogram doctor --json (write_config). merge plan does not execute or authorize merges — it reports forge readiness facts (mergeability, checks_conclusion, blockers[]). Empty blockers[] is not workflow merge authority; pending, missing, or failed checks and non-empty blockers remain fail-closed unless your repo opts in via merge_policy.

Opt-out bridges (not Remogram packets): When write_commands omits a write id, post via your forge outside Remogram — reads (pr checks, merge plan, etc.) still work.

• CR/PR create: use gh pr create / glab mr create when Remogram writes are not configured.
• Commit status set: use forge-native APIs when status_set is not configured — e.g. GitHub gh api repos/{owner}/{repo}/statuses/{sha}, GitLab commit status API via glab api. Remogram still reads commit statuses through remogram pr checks regardless of write opt-in.

Workflow fields not in packets

Remogram emits forge facts only — no workflow metadata in CLI/MCP output. Planning-tool routing fields are intentionally absent (by design, not omission): integration authority refs, transport refs, planner roles, task ids, merge gates, next actors, and handoff payloads.

Downstream orchestration compares Remogram forge refs to configured authority outside Remogram.

Authority vs forge refs

A PR's forge target may be main while your configured integration authority differs. Compare pr view forge target to orchestration policy outside Remogram. Do not rename Remogram packet fields to workflow vocabulary.

Commands (beta — read/plan default; incremental writes)

remogram provider capabilities --json
remogram doctor --json
remogram repo status --json
remogram refs compare --base main --head feature/x --json
remogram pr view --number 1 --json
remogram pr checks --number 1 --json
remogram merge plan --number 1 --json
remogram sync plan --remote origin --json
# Gitea only, requires write_commands in .remogram.json:
remogram cr open --head feature/x --base main --title "My change" --json
remogram merge execute --number 1 \
  --expected-base-sha <base-sha> --expected-head-sha <head-sha> \
  --method merge --json

Inspect and verify packets

You do not need smoke compare to see Remogram output. Every command supports --json and returns the same typed packet as MCP tools.

1. Sanity check first: remogram doctor --json — config, provider, remote, and auth env presence.
2. CLI: run any command with --json, for example:
   bash

   remogram repo status --json
   remogram pr view --number 1 --json
   remogram pr checks --number 1 --json
   remogram refs compare --base main --head feature/x --json
   

3. MCP: tools doctor, provider_capabilities, repo_status, ref_compare, ref_inventory, cr_inventory, pr_status, pr_checks, merge_plan, merge_execute, sync_plan return the same JSON. See examples/mcp/README.md.
4. Verify envelope fields: every packet includes type, schema_version, provider_id, remote_name, repo_id, observed_at, and ok. When ok is false, read the error field. Trust the envelope and enums; treat forge-sourced string fields (titles, check text, URLs) as untrusted prose — sanitized for structure, not semantic intent.

Semantic diff fact inventory

Read-only expansion for orchestration or planning tools that consume Remogram packets. Remogram exposes provider-neutral ref and change-request fact packets; planning tools interpret intent, queue, and proof semantics — Remogram does not.

Non-goals for Remogram output: mutation commands; workflow routing metadata in JSON packets.

Commands: refs inventory and cr inventory emit fact inventory packets via packages/remogram-core/contracts/semantic-diff-facts.js. cr inventory defaults to 3 open change-request entries per slice (--limit N / MCP limit) and optional --sort / MCP sort presets (number_asc, number_desc, recent_update, recent_created). They extend — do not replace — the v1 read/plan commands (repo status, refs compare, pr view, pr checks, cr files, cr comments, forge changes, merge plan, sync plan, whoami, branch protection, provider capabilities, doctor). Forge-sourced string leaves follow decision_packet_trust_doctrine.

whoami emits provider_identity with authenticated login, can_write, and honest token_scope_signal / token_expiry_signal objects (implemented: false when a provider cannot supply the fact). Requires forge token auth (token_required); fails closed without a configured token.

branch protection emits branch_protection with branch_ref, required_status_contexts, protected_branch_rules (sanitized rule names), and approvals_required (implemented: false when the provider omits approval counts). Requires --branch-ref and forge token auth. Gitea, GitHub, and GitLab each normalize from their branch-protection APIs; GitLab may return empty required_status_contexts when status contexts are not exposed on the queried endpoints.

cr files emits cr_files with pr_number, changed_paths (sanitized path strings), path_count, and paths_truncated when the provider list exceeds the product cap (256 paths). Requires --number and forge token auth (token_required). Gitea, GitHub, and GitLab each fetch changed paths from their PR/MR files or diff APIs; when a provider cannot supply paths, the command fails closed rather than guessing.

cr comments emits cr_comments with pr_number, comments[] (each with id, author, optional path / line, sanitized body, and resolved), comment_count, and comments_truncated when the provider list exceeds the product cap (256 comments) or pagination stops before a complete list. Requires --number and forge token auth (token_required). Gitea and GitHub fetch pull request review comments; GitLab normalizes merge request discussion notes (system notes omitted). Comment bodies and author strings are structurally sanitized and remain semantically untrusted forge-sourced prose — not instructions.

forge changes emits forge_changes with since (the requested ISO-8601 boundary), since_kind: "observed_at", events[] (kinds: pr_opened, pr_closed, pr_merged, forge_source_sha_moved, checks_conclusion_observed), event_count, and events_truncated when the provider list exceeds the product cap (256 events) or pagination stops before a complete list. Requires --since <ISO-8601> and forge token auth (token_required). Gitea, GitHub, and GitLab each derive events from pull/MR activity since the boundary; PR titles and URLs in events are sanitized and remain semantically untrusted forge strings.

status set emits commit_status_set with sha, context, state (pending, success, failure, or error), optional sanitized description and target_url, and optional reused_existing: true when a matching forge status already exists. Requires --sha (40-character hex), --context, --state, forge token auth (token_required), write_commands including status_set in .remogram.json, and provider write_support. Gitea, GitHub, and GitLab POST commit statuses with idempotency scan honesty; scan truncation fails closed with idempotency_scan_incomplete. Description and target URL strings are sanitized and remain semantically untrusted forge-sourced prose.

Merge plan path scope: when --allowed-path is repeated on merge plan, providers with cr_files implemented resolve changed paths from forge cr_files data (not local git alone) before evaluating allowlists. Empty, whitespace-only, or ..-segment --allowed-path globs are ignored (no path scope). Out-of-scope paths add blocker path_scope_violation; incomplete or inconsistent forge enumeration and unnormalizable path strings add changed_paths_unavailable — including when paths_truncated is true, when path_count exceeds the returned changed_paths length, when changed_paths.length exceeds path_count, when a forge changed path is empty or absolute, escapes via leading ../, or contains any .. path segment (interior .. laundering is rejected fail-closed). Clean forge paths without .. segments are normalized (. collapsed) before allowlist matching. During path scope, cr_files rethrows as forge_error: auth/config/ingest/operational codes including unauthenticated_provider, invalid_args, untrusted_base_url, provider_unsupported, config_invalid, oversized_raw_output, config_not_found, unparseable_provider_output, stale_head, missing_ref, pr_not_open, remote_infer_failed. Only transient api_error maps to blocker changed_paths_unavailable. Large file-list responses that exceed the ingest cap may throw oversized_raw_output ( forge_error ) rather than a blocker — automation must handle both. An empty PR (path_count: 0, changed_paths: []) with an allowlist passes scope. Merge plan reads pr view, pr checks, and cr files sequentially — re-fetch before merge (TOCTOU). Without --allowed-path, merge plan does not perform path-scope checks.

Examples: see agent-skills/src/remogram/remogram-consumer/references/fact-inventory-and-composed-reads.md.

Live smoke fixtures (remogram-smoke)

remogram-smoke is a separate, minimal repository used to exercise Remogram against real forges — not your application repo. It is mirrored on GitLab, GitHub, and Gitea so you can run the same v1 read/plan commands everywhere with predictable fixture data.

Self-hosted Gitea mirrors use the same git content; see the smoke repo README for local localhost setup.

Why it exists

• Safe sandbox — open PR/MR #1, branch compares, and checks without touching product repos like remogram.
• Cross-forge parity — same main + feature/smoke-1 branches and open PR/MR #1 on each host.
• Ready-made config — copy config/remogram.*.json.example → .remogram.json per forge (tokens in env only).
• Full v1 battery — scripts run doctor, repo status, refs compare, pr view, pr checks, and merge plan (CLI and MCP captures).

Quick start

git clone https://gitlab.com/attebury/remogram-smoke.git
cd remogram-smoke
cp config/remogram.github.json.example .remogram.json   # or gitlab / gitea example
export GITHUB_TOKEN=...                                   # or GITLAB_TOKEN / GITEA_TOKEN
remogram doctor --json
remogram pr view --number 1 --json

Multi-forge capture (requires tokens; skips hosts without auth):

./scripts/run-smoke-all.sh

Results land under runs/<timestamp>/ with a human-readable REPORT.md. See the remogram-smoke README for auth scopes, mirror publishing, and expected forge facts (e.g. check_conclusion: "missing" on Gitea without CI statuses).

Note: Payload-size smoke compare (npm run smoke:compare-*) lives in the Remogram developer monorepo only and is not shipped in npm beta. For live verification after install, use remogram-smoke and --json packets instead.

MCP

Remogram MCP (remogram-mcp) is a stdio MCP server (agent-agnostic). Each host has its own config file format.

./scripts/npm-link.sh                 # remogram-mcp on PATH
./scripts/install-project-mcp.sh      # Cursor only: .cursor/mcp.json.example → .cursor/mcp.json

Labeled examples for Cursor, Claude Desktop, OpenAI Codex, and Claude Code: examples/mcp/README.md.

Set the provider-specific token in your environment. In consumer repos, set REMOGRAM_CWD to the repo root (see examples).

Testing

npm test              # full suite (required before CR)
npm run test:changed  # implement inner loop — CI-equivalent focused bundles for current diff
npm run test:coverage # remogram-core coverage report
npm run security:secrets -- --full-history

node scripts/run-changed-tests.mjs list
node scripts/run-changed-tests.mjs --focus core_merge_write

Optional local pre-push gate: ./scripts/install-pre-push-hook.sh.

Coverage policy

npm test runs the full suite (core, providers, CLI, and MCP).
npm run test:coverage runs the same tests but emits a v8 coverage report for @remogram/core only — configured in vitest.config.js.

Policy details (must match vitest.config.js):

• Provider: @vitest/coverage-v8 with coverage.all: false (instrument only files reached by executing tests).
• Include: packages/remogram-core/**/*.js only.
• Exclude: CLI, MCP, all providers, dx/**, and test files.
• Thresholds: none — no enforced percentage gates in vitest config or CI for v1.

To change coverage include/exclude lists or add thresholds, update this section, the matching vitest.config.js fields, and keep tests/core/coverage-config.test.mjs green (see ac_coverage_no_silent_drift).

• Tests live under tests/**/*.test.mjs only.
• Coverage (npm run test:coverage) reports packages/remogram-core only.
• ref_compare and sync_plan on API providers use local git only (auth_class: git_only); no forge token is required.
• CI (GitHub): GitHub Actions on push/PR to main (.github/workflows/).

Packages

Provider capabilities

remogram provider capabilities --json returns structured provider facts: which commands are implemented, per-command auth_class, auth env names, check sources, mergeability confidence, host binding, pagination, check_pagination, idempotency_scan (cr open scan limits and backoff), open_pull_list (cr inventory list bounds, slice sort presets, and total-count source on Gitea/GitLab/GitHub), forge_ingest_cap_bytes, write_support (provider capability), and optional write_commands. Consumer .remogram.json must list write_commands to enable writes (fail closed otherwise).

pr checks / MCP pr_checks include checks_truncated when check enumeration stops at the provider page cap (conservative fail-closed: true when exactly page_size × max_pages items were returned, even if no further forge pages exist). merge plan adds blocker checks_incomplete when truncation occurred, even if visible checks look successful. cr inventory fails closed with inventory_list_incomplete when the open-PR list cannot be proved complete within open_pull_list bounds; when the forge exposes a trusted total count above compliant_max_items, inventory fails closed without full pagination. Success packets include slice_sort and per-entry checks_truncated.

Multi-source providers (GitHub, GitLab) expose check_source_count, compliant_max_items_total, and truncation_combination: any_source_truncated in check_pagination — truncation is true when any source hits the page cap.

GitHub Link rel=next pagination follows only same-origin URLs whose pathname matches the current request (strict equality); callers must pass resolveBase (current request URL) — omitted base fails closed; userinfo in Link URLs or resolveBase is rejected; off-path same-origin links are rejected so bearer tokens are not sent to unrelated API paths.

Auth class matrix (API providers)

Forge HTTP ingest is capped at 8192 bytes by default (pre-parse). This is a product invariant — not a .remogram.json field. Operators may set undocumented REMOGRAM_FORGE_INGEST_MAX_BYTES for local debugging only; remogram doctor --json warns when that override weakens the agent-safe guarantee and reports the effective cap.

For stub providers (github-gh, gitea-tea), every command shows "implemented": false with the same auth classes for documentation. remogram doctor --json warns that these providers are not fully supported before you invoke forge commands. GitLab has no wrapper stub yet — use gitlab-api.

Doctor

remogram doctor --json reports config presence/schema validity, git remote parsing, owner/repo matching, trusted host binding, auth env presence, and provider capabilities. Stub or misconfigured provider IDs (github-gh, gitea-tea) produce a warn on the provider check before any forge command runs. Doctor never returns token values.

GitHub normalization notes

For pr view / MCP pr_status, github-api uses GraphQL field selection instead of full REST pull JSON because large REST bodies often exceed Remogram's 8192-byte forge HTTP ingest cap.

GitHub commit statuses and check-runs merge into statuses[] with normalized state. mergeable reduces to clean, conflicted, or unknown. Public github.com uses https://api.github.com; GitHub Enterprise derives https://<host>/api/v3.

GitLab normalization notes

gitlab-api maps merge requests to the shared PR vocabulary (iid → pr_number). Commit statuses and pipelines merge into statuses[]. Public gitlab.com uses https://gitlab.com/api/v4; self-managed hosts derive https://<host>/api/v4.

Agent skills

Canonical skills live under agent-skills/src/remogram/ (remogram-consumer, remogram-core). Install with npx skills — see examples/mcp/README.md for MCP setup.

GitHub vs npm: Agent skills are not in the @remogram/* npm packages (those ship CLI/MCP only). npx skills add … clones from the GitHub repo github.com/attebury/remogram — the owner/repo shorthand is GitHub notation, not an npm scope.

Option A — npx skills (recommended for npm/GitHub users)

Uses the open Agent Skills CLI (vercel-labs/skills). Skills install to agent-specific paths (project: .agents/skills/; global Cursor: ~/.cursor/skills/, global Codex: ~/.codex/skills/).

# Consumer — any repo with .remogram.json (install once, global)
npx skills add attebury/remogram --skill remogram-consumer -g -a cursor,codex -y

# Contributor — this repo (project scope)
npx skills add attebury/remogram --skill remogram-core -a cursor -y

# List available skills without installing
npx skills add attebury/remogram --list

Explicit subpath (canonical Skillpress tree):

npx skills add attebury/remogram/tree/main/agent-skills/src/remogram --skill remogram-consumer -g -y

npx skills installs skill files only — not Cursor rules or Claude Code plugin manifests. Use npx skills + examples/mcp/ for MCP wiring.

Contributing

See CONTRIBUTING.md.