The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Remogram listing page.
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.
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.
.remogram.json.example → .remogram.json (set provider, owner, repo; add baseUrl for self-hosted Gitea/GitLab).GITEA_TOKEN, GITHUB_TOKEN / GH_TOKEN, or GITLAB_TOKEN.Command catalog: remogram contract --json. Agent skill: npx skills add attebury/remogram --skill remogram-consumer -g -y.
| Forge | "provider" | Token env |
|---|---|---|
| Gitea | gitea-api | GITEA_TOKEN |
| GitHub | github-api | GITHUB_TOKEN or GH_TOKEN |
| GitLab | gitlab-api | GITLAB_TOKEN |
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.
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.
| Write id | Command | Notes |
|---|---|---|
cr_open | cr open | Separate from merge |
cr_close | cr close | Gitea lifecycle |
merge | merge execute | Requires --expected-base-sha / --expected-head-sha; not implied by cr_open |
publish_branch | publish execute | Git push to configured remote |
status_set | status set | Commit status POST |
issue / cr_edit ids | matching commands | See contract --json |
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.
Remogram emits forge facts only — no integration authority refs, lane roles, task ids, or handoff payloads in JSON.
| Concept | Packet field | Notes |
|---|---|---|
| PR base | forge_target_branch_ref | Forge-reported |
| PR head | forge_source_branch_ref | Evidence only |
| Default branch | default_branch | Not integration authority |
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.
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.
Cross-forge fixture repo: remogram-smoke (mirrors on GitHub/Gitea). Use --json packets after install; monorepo smoke-compare scripts are dev-only.
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.
| Package | Role |
|---|---|
@remogram/cli | CLI |
@remogram/mcp | MCP adapter |
@remogram/core | Envelope, config, caps |
@remogram/provider-{gitea,github,gitlab}-api | Supported forge backends |
npx skills add attebury/remogram --skill remogram-consumer -g -y (consumer) or --skill remogram-core (contributor). Skills ship from GitHub, not npm.
See CONTRIBUTING.md.