SCM & forge boundary MCP: normalized, typed JSON from attributed Gitea, GitLab, and GitHub providers
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.
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.
.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.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.
| 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 test
npm run test:coverage
npm run security:secrets -- --full-history
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.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y @remogram/mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-attebury-remogram": {
"command": "npx",
"args": [
"-y",
"@remogram/mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup reference@remogram/mcpnpmRemogram works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.