Remogram

Name: Remogram
Author: attebury

Local

github.com/atteburyVersion Control0Updated 16w ago

About Remogram

Remogram is an SCM CLI and MCP server for Gitea, GitLab, and GitHub, intended for agents and tools that need structured forge data. It distinguishes locally resolved Git refs from PR details reported by forge APIs, and does not handle workflow planning or authority.

Key features

01Support Gitea, GitLab, and GitHub APIs
02Emit provider-attributed JSON facts
03Inspect repositories, PRs, checks, and refs
04Compare PR commits with local branch revisions
05Default to read and planning operations

Use cases

01Read repository data consistently across forges
02Check whether a PR head matches the local branch
03Create a merge plan and inspect blockers
04Provide structured forge facts to an agent

MCP support

Its stdio MCP server delegates requests to the Remogram CLI and returns the same JSON as `remogram … --json`. Set `REMOGRAM_CWD` to the consumer repository root.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config

{
  "mcpServers": {
    "attebury-remogram": {
      "command": "npx",
      "args": [
        "-y",
        "@remogram/mcp"
      ],
      "env": {
        "GITHUB_TOKEN": "<GITHUB_TOKEN>",
        "GH_TOKEN": "<GH_TOKEN>",
        "GITLAB_TOKEN": "<GITLAB_TOKEN>",
        "GITEA_TOKEN": "<GITEA_TOKEN>",
        "REMOGRAM_CWD": "<REMOGRAM_CWD>",
        "REMOGRAM_OPERATOR_CONFIG": "<REMOGRAM_OPERATOR_CONFIG>"
      }
    }
  }
}

Run commandnpx -y @remogram/mcp

Environment variables to set

GITHUB_TOKENSecretGitHub API token for github-api repositories.

GH_TOKENSecretAlternative GitHub API token for github-api repositories.

GITLAB_TOKENSecretGitLab API token for gitlab-api repositories.

GITEA_TOKENSecretGitea API token for gitea-api repositories.

REMOGRAM_CWDRepository root for Remogram to inspect when the MCP host launches from another working directory.

REMOGRAM_OPERATOR_CONFIGOptional path to a local operator write-command overlay.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages

npm@remogram/mcp0.2.0-beta.4stdio

Tools

Saved tool list · updated 2w ago

Parameter	Type	Required	Description
live	boolean	No	When true, perform a bounded live forge API reachability probe

Details

From the project README

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.

Quick start

Copy .remogram.json.example → .remogram.json (set provider, owner, repo; add baseUrl for self-hosted Gitea/GitLab).
Export token: GITEA_TOKEN, GITHUB_TOKEN / GH_TOKEN, or GITLAB_TOKEN.
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

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.

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.

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.

Boundary and trust

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.

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

Package	Role
`@remogram/cli`	CLI
`@remogram/mcp`	MCP adapter
`@remogram/core`	Envelope, config, caps
`@remogram/provider-{gitea,github,gitlab}-api`	Supported forge backends

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.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

Read the getting-started guide

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.

Remogram

About Remogram

Key features

Use cases

MCP support

Configuration

Tools

Details

Remogram

Install

Quick start

Providers

Configuration

Boundary and trust

MCP

Live verification

Testing

Coverage policy

Packages

Agent skills

Contributing

Comments

New to MCP?

What is MCP (Model Context Protocol)?

How do MCP servers differ from clients?

Should I use a local or a remote server?

How do I install a server in Claude, Cursor and others?

Are listed projects reviewed? What does “Verified” mean?

My project is listed. How do I claim it?