Introducing *beta* Remogram: forge facts for agents, without the workflow baggage

If you've ever pointed an AI coding agent at a pull request and watched it confidently merge based on a stale title, a truncated API response, or prose that looked like instructions, you've hit a boundary problem. Git hosts know a lot. Agents need small, typed, trustworthy facts, not raw forge dumps and not your team's SDLC vocabulary mixed into SCM output.

Remogram is a generic SCM/forge boundary: a CLI and MCP server that turns GitHub, GitLab, and Gitea into provider-attributed JSON packets agents can reason about safely.

Remogram was developed by and for Topogram, but you don't need Topogram to use it. It stands on its own as open-source tooling for any repo that wants better agent–forge hygiene.

The problem

Modern agent workflows need answers to boring but critical questions:

• Is this PR mergeable, or only technically mergeable?


• What do CI checks actually say?


• Does the forge's head_sha still match what git has locally?


• How far is my branch behind integration?

You can answer these with gh, glab, tea, or REST calls, but each path has tradeoffs:

• 
  CLI output varies by tool version and is hard to cap reliably.


• 
  Raw API responses are huge and easy to over-ingest into an agent context window.


• 
  Forge strings are untrusted. PR titles, check descriptions, and error bodies can contain adversarial prose.


• 
  Workflow tools leak semantics. Goal branches, lanes, and task IDs belong in planning layers, not in SCM facts.

Agents need a thin, opinionated layer that says: here are the forge facts, here's what you can trust in the envelope, here's what you must treat as untrusted prose.

That layer is Remogram.

What Remogram does

Remogram reads your repo's .remogram.json and speaks to your forge over HTTP APIs. You don't need to install official forge CLIs.

Core read/plan commands include:

remogram doctor --json

remogram repo status --json

remogram pr view --number 42 --json

remogram pr checks --number 42 --json

remogram merge plan --number 42 --json

remogram refs compare --base main --head feature/x --json

The same packets are available through MCP tools, so Cursor, Codex, and other MCP clients get identical JSON whether they call the CLI or the server.

Every packet shares a trusted envelope: type, schema_version, provider_id, remote_name, repo_id, observed_at, and ok. That consistency matters. An agent (or orchestrator) can gate on structure instead of parsing ad hoc CLI text.

Designed for agent trust, not just convenience

Remogram makes a few deliberate choices:

Bounded ingest. Forge responses are capped (default 8192 bytes) and fields are selected explicitly, not dumped wholesale into agent context.

Sanitized strings. Error messages and forge-sourced text go through structural sanitization; secrets like ghp_, gho_, and ghs_ tokens are redacted before they reach packets.

Stale head detection. When you ask about a PR by number, Remogram compares the forge-reported head_sha to what git resolves locally. If they diverge, you get ok: false with stale_head. That's a signal to git fetch, not to merge.

No workflow metadata in output. Remogram emits SCM/forge facts only. Goal branches, lanes, SDLC tasks, and proof semantics stay in external planning tools that consume Remogram, not inside Remogram itself.

Multi-forge from one shape. github-api, gitlab-api, and gitea-api providers normalize into the same packet types, so tooling built on Remogram isn't locked to a single host.

Why it's useful

For agent authors and skill maintainers

You get a stable contract instead of re-implementing forge adapters in every skill. Install the consumer skill, configure .remogram.json, run remogram doctor, and teach agents to read packets, not web UI prose.

For teams on self-hosted forges

Gitea and self-managed GitLab are first-class. Remogram was dogfooded on a private Gitea integration branch before export to public GitHub main. If your forge isn't GitHub.com, you still get the same typed facts.

For review and merge guardrails

merge plan exposes blockers, not just mergeability. "Clean merge" and "safe to merge" are different things; Remogram is explicit about which checks are pending, missing, or failed. That's the difference between an agent that can merge and one that should wait.

For CI and headless environments

API providers need a token env var (GITHUB_TOKEN, GITLAB_TOKEN, GITEA_TOKEN), not an interactive CLI login. That fits servers, sandboxes, and lane worktrees cleanly.

Beta today, intentional scope

Remogram is in 0.1.0-beta: read/plan commands are mature; writes (starting with Gitea cr open) are opt-in via write_commands in config. Merge execute remains out of scope. Remogram informs decisions; humans and separate merge lanes still own the button.

Install:

npm install -g @remogram/cli@beta @remogram/mcp@beta

Copy .remogram.json.example, run remogram doctor --json, and try remogram pr view on an open change request. For a safe sandbox, use the remogram-smoke fixture repos mirrored on GitHub, GitLab, and Gitea.

The idea in one sentence

Remogram is the forge boundary layer agents should talk to: small packets, explicit trust, multi-forge parity, so your planning workflow, review policy, and merge authority can sit above SCM facts instead of leaking into them.