Remogram

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

PR-by-number reconciliation: pr view / pr checks compare forge-reported forge_source_sha to the local rev for forge_source_branch_ref. Divergence → ok: false, error_code: stale_head — git fetch, not a forge outage.

Planning tools interpret intent and workflow authority outside Remogram.

Install

npm install -g @remogram/cli @remogram/mcp
remogram --version
remogram version --json

Legacy preview (frozen @beta, optional): npm install -g @remogram/cli@beta @remogram/mcp@beta

Development checkout: clone this repo, npm ci, ./scripts/npm-link.sh. Default branch: main.

Related MCP server: github-mcp

Quick start

1. Copy .remogram.json.example → .remogram.json (set provider, owner, repo; add baseUrl for self-hosted Gitea/GitLab).

2. Export token: GITEA_TOKEN, GITHUB_TOKEN / GH_TOKEN, or GITLAB_TOKEN.

3. Bootstrap:

remogram doctor --json
remogram provider capabilities --json
remogram repo status --json
remogram pr view --number 1 --json
remogram merge plan --number 1 --json

Command catalog: remogram contract --json. Agent skill: npx skills add attebury/remogram --skill remogram-consumer -g -y.

Providers

Use *-api providers (forge HTTP). Reserved github-gh / gitea-tea IDs return provider_unsupported — not implemented in v1. Official CLIs (gh, tea, glab) are not required.

Configuration

Read/plan by default. Opt in to writes with write_commands in .remogram.json (or a bound operator overlay outside git). Missing id → write_not_configured.

merge plan is read-only — reports blockers[]; does not execute or authorize merges. mergeability: clean is conflict-free git only.

Optional merge_policy waivers (allow_missing_checks, allow_pending_checks) relax check blockers for repos without CI — env: REMOGRAM_ALLOW_MISSING_CHECKS, REMOGRAM_ALLOW_PENDING_CHECKS. Doctor fails when enabled in strict checkouts.

Operator overlay discovery: --operator-config → REMOGRAM_OPERATOR_CONFIG → $XDG_CONFIG_HOME/remogram/operator/<provider>-<owner>-<repo>.json. bind must match forge identity.

Boundary and trust

Remogram emits forge facts only — no integration authority refs, lane roles, task ids, or handoff payloads in JSON.

Every forge command packet includes type, schema_version, provider_id, remote_name, repo_id, observed_at, ok. Producer sections (e.g. remogram.forge_facts.v1 from evidence forge-facts --json) use nested producer fields. Trust envelope and enums; treat forge-sourced strings (titles, URLs) as untrusted prose.

Inventory commands (refs inventory, cr inventory, whoami, branch protection, cr files, forge changes, …) extend read/plan — details in remogram contract --json and the consumer skill references.

MCP

Stdio server remogram-mcp delegates to the CLI — same JSON as remogram … --json. Setup: examples/mcp/README.md. Set REMOGRAM_CWD to the consumer repo root.

Live verification

Cross-forge fixture repo: remogram-smoke (mirrors on GitHub/Gitea). Use --json packets after install; monorepo smoke-compare scripts are dev-only.

Testing

npm test
npm run test:coverage
npm run security:secrets -- --full-history

Coverage policy

npm run test:coverage instruments @remogram/core only; @remogram/cli, @remogram/mcp, and @remogram/provider-* are excluded. Thresholds: none — no enforced percentage gates. Drift guard: tests/core/coverage-config.test.mjs.

CI (GitHub): .github/workflows/ on push/PR to main.

Packages

Agent skills

npx skills add attebury/remogram --skill remogram-consumer -g -y (consumer) or --skill remogram-core (contributor). Skills ship from GitHub, not npm.

Contributing

See CONTRIBUTING.md.