Remogram

io.github.atteburyPublished by GitHub account atteburyv0.2.0-beta.4Updated Oct 24, 2026

SCM & forge boundary MCP: normalized, typed JSON from attributed Gitea, GitLab, and GitHub providers

VerifiedSTDIODesktop onlyDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

A local stdio MCP server that gives an assistant read-only, provider-attributed JSON facts about Gitea, GitHub and GitLab repositories, pull requests and refs.

What you can do
Inspect repositories and refs: repo status, refs inventory and compare, sync plans, whoami, branch protection, forge changes, and file lists for change requests, with git-resolved refs distinguished from forge-reported ones. View pull requests by number: PR details and checks, reconciling the forge-reported head SHA against the local revision and flagging stale heads. Plan merges read-only: merge plans report blockers without executing or authorizing a merge. Optionally perform writes when explicitly enabled in configuration: open or close change requests, execute merges with expected base and head SHAs, push branches, and set commit statuses. Emit typed JSON packets with a schema version, a
When to use it
Use it when an assistant needs trustworthy, structured facts about a Gitea, GitHub or GitLab repository — PR state, checks, refs, branch protection — rather than free-form CLI output, and when you want merge and write actions gated behind explicit configuration.
Requirements
Runs as a local Node.js process installed from the npm package @remogram/mcp (the CLI package is installed alongside it). Needs a .remogram.json config with provider, owner and repo, plus baseUrl for self-hosted Gitea or GitLab. A forge token is required in GITEA_TOKEN, GITHUB_TOKEN or GH_TOKEN, or GITLAB_TOKEN. Set REMOGRAM_CWD to the repository root when the host launches elsewhere. Network access to the forge API.
Before you install
Write commands are off by default and must be enabled by id in .remogram.json or an operator overlay; enabled writes include opening and closing change requests, executing merges, pushing branches and posting commit statuses. Merge execution requires expected base and head SHAs. Policy waivers for missing or pending checks can relax CI blockers. Forge-sourced strings such as titles and URLs should be treated as untrusted prose. Tokens are read from environment variables and grant forge API scope

Installation

In SourceWeft

  1. Open Remogram in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

bash
npm install -g @remogram/cli @remogram/mcpremogram --versionremogram 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

  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:
bash
remogram doctor --jsonremogram provider capabilities --jsonremogram repo status --jsonremogram pr view --number 1 --jsonremogram 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
Giteagitea-apiGITEA_TOKEN
GitHubgithub-apiGITHUB_TOKEN or GH_TOKEN
GitLabgitlab-apiGITLAB_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 idCommandNotes
cr_opencr openSeparate from merge
cr_closecr closeGitea lifecycle
mergemerge executeRequires --expected-base-sha / --expected-head-sha; not implied by cr_open
publish_branchpublish executeGit push to configured remote
status_setstatus setCommit status POST
issue / cr_edit idsmatching commandsSee 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.

ConceptPacket fieldNotes
PR baseforge_target_branch_refForge-reported
PR headforge_source_branch_refEvidence only
Default branchdefault_branchNot 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

bash
npm testnpm run test:coveragenpm 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

PackageRole
@remogram/cliCLI
@remogram/mcpMCP adapter
@remogram/coreEnvelope, config, caps
@remogram/provider-{gitea,github,gitlab}-apiSupported 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.

Source: README.md at commit 9f99b93

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.0-beta.4LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts