Remogram
attebury/remogram
Interface uniforme para GitHub/GitLab/Gitea com fatos JSON otimizados para agentes
Ver no GitHubServidor MCP e CLI que conecta agentes Claude a sistemas SCM/forge (GitHub, GitLab, Gitea) emitindo fatos JSON tipados e atribuídos a commits. Abstrai diferenças entre provedores mantendo payloads compactos (máx 8KB) próprios para agentes, sem conceitos de workflow ou ferramentas de planejamento.
Instalação
npx convez-ai attebury/remogram1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Consultar PRs, branches e commits de múltiplas plataformas SCM com uma API única
- Integrar operações de repositório em fluxos de agentes Claude mantendo payloads compactos
- Abstrair diferenças entre GitHub, GitLab e Gitea self-hosted em uma camada consistente
Veredito

Solução bem-arquitetada para agentes precisarem consultar SCM com segurança de payload. Beta limitada (leitura apenas), mas conceito é sólido e implementação é técnica e agnóstica a plataforma. Útil para automação de CI/CD e auditorias de repositório via Claude.
README
A tradução para o português deste README ainda está na fila.
Remogram
Generic SCM/forge boundary CLI and MCP server. Emits provider-attributed, SHA-bound JSON facts only — no workflow or planning-tool concepts in output.
Remogram was developed by and for Topogram. Topogram is not required to install or use Remogram.
Install (beta)
npm install -g @remogram/cli@beta @remogram/mcp@beta
From a git checkout (development):
git clone https://github.com/attebury/remogram.git
cd remogram
npm ci
./scripts/npm-link.sh
Default branch: main.
Beta limitations
- Read/plan v1 only — no PR create, merge execute, or push.
- Payload-size smoke compare is monorepo dev tooling only (not shipped in npm beta). For live cross-forge checks, use the remogram-smoke fixture repos.
Providers
Set "provider" in .remogram.json. Beta supports three forge backends — all use forge HTTP APIs (GitHub also uses GraphQL for PR view). You do not need official forge CLIs (gh, tea, or glab) installed.
| Your forge | "provider" value | Token env | Official CLI (not required) |
|---|---|---|---|
| Gitea (incl. self-hosted) | gitea-api | GITEA_TOKEN | tea |
| GitHub (incl. Enterprise) | github-api | GITHUB_TOKEN or GH_TOKEN | gh |
| GitLab (incl. self-managed) | gitlab-api | GITLAB_TOKEN | glab |
Self-hosted Gitea/GitLab: add "baseUrl" to your forge root (see example patterns in provider notes below).
Check what your config enables:
remogram provider capabilities --json
remogram doctor --json
CLI wrapper providers (not supported in beta)
Each forge also has an official command-line tool. Remogram may eventually support optional wrapper providers that shell out to those binaries and normalize their JSON into the same typed packets as the API providers:
| Forge | Supported today | Reserved wrapper ID | Would wrap |
|---|---|---|---|
| GitHub | github-api | github-gh | gh |
| Gitea | gitea-api | gitea-tea | tea |
| GitLab | gitlab-api | (none yet — likely gitlab-glab if added) | glab |
Do not use wrapper IDs in .remogram.json today. Only github-gh and gitea-tea exist as reserved placeholders; both return:
ok: falseerror_code: "provider_unsupported"error_message: "Provider not implemented in v1"
There is no gitlab-glab provider ID in config yet — use gitlab-api.
| If you use… | Set "provider" to… | Not… |
|---|---|---|
| GitHub | github-api | github-gh |
| Gitea | gitea-api | gitea-tea |
| GitLab | gitlab-api | (no CLI wrapper exists yet) |
The npm packages @remogram/provider-github-gh and @remogram/provider-gitea-tea exist only so the CLI can list those IDs honestly in provider capabilities (implemented: false). You never install or configure them separately.
Why wrappers are not supported yet
Beta focused on direct forge HTTP because it is the best fit for Remogram's constraints:
- Agent-safe packets — Remogram caps forge ingest at 8192 bytes and selects fields explicitly (e.g. GitHub PR view uses GraphQL instead of full REST). Wrapper CLIs often emit large, version-dependent JSON that is harder to cap and normalize reliably.
- Headless and CI-friendly — API providers need only a token env var. Wrappers require
gh/tea/glabon PATH, their own login flows, and subprocess handling with the same trust rules as git. - One backend per forge for v1 —
github-api,gitea-api, andgitlab-apialready implement all six read/plan commands with shared packet shapes. Wrappers would duplicate that surface without adding new commands in beta. - Maintenance surface — CLI output changes between tool versions; each wrapper is an ongoing compatibility contract on top of the API adapters.
When or if wrappers will ship
Not in beta. There is no committed release date.
Wrapper providers are post-beta, demand-driven:
- If users need Remogram to reuse an existing
gh/tea/glablogin instead of managing API tokens, or policy blocks direct API access but allows official CLIs, we would implement wrappers behind the reserved IDs (and addgitlab-glabfor parity withglab). - Likely order if built: shared subprocess + JSON ingest helper in
@remogram/core, thengithub-ghfirst (gh --jsonis the most stable), thengitea-teaandgitlab-glab. - Until then: use the
*-apiproviders above. They are the supported path for CLI, MCP, and agents.
If wrapper support matters for your setup, open a GitHub issue describing forge, CLI version, and whether API tokens are unavailable — that helps prioritize.
Consumer config
Copy .remogram.json.example to your repo root and set provider, owner, repo, and remote to match your project.
Example for GitHub:
{
"version": "1",
"provider": "github-api",
"remote": "origin",
"owner": "your-org",
"repo": "your-repo"
}
Example for self-hosted Gitea:
{
"version": "1",
"provider": "gitea-api",
"remote": "origin",
"owner": "your-org",
"repo": "your-repo",
"baseUrl": "https://forge.example.com"
}
Commands (v1 — read/plan only)
remogram provider capabilities --json
remogram doctor --json
remogram repo status --json
remogram refs compare --base main --head feature/x --json
remogram pr view --number 1 --json
remogram pr checks --number 1 --json
remogram merge plan --number 1 --json
remogram sync plan --remote origin --json
Inspect and verify packets
You do not need smoke compare to see Remogram output. Every command supports --json and returns the same typed packet as MCP tools.
- Sanity check first:
remogram doctor --json— config, provider, remote, and auth env presence. - CLI: run any command with
--json, for example:remogram repo status --json remogram pr view --number 1 --json remogram pr checks --number 1 --json remogram refs compare --base main --head feature/x --json - MCP: tools
doctor,provider_capabilities,repo_status,ref_compare,pr_status,pr_checks,merge_plan,sync_planreturn the same JSON. See examples/mcp/README.md. - Verify envelope fields: every packet includes
type,schema_version,provider_id,remote_name,repo_id,observed_at, andok. Whenokisfalse, read theerrorfield.
Live smoke fixtures (remogram-smoke)
remogram-smoke is a separate, minimal repository used to exercise Remogram against real forges — not your application repo. It is mirrored on GitLab, GitHub, and Gitea so you can run the same v1 read/plan commands everywhere with predictable fixture data.
| Forge | Clone URL |
|---|---|
| GitLab (source of truth) | https://gitlab.com/attebury/remogram-smoke.git |
| GitHub | https://github.com/attebury/remogram-smoke.git |
| Gitea.com | https://gitea.com/attebury/remogram-smoke.git |
Self-hosted Gitea mirrors use the same git content; see the smoke repo README for local localhost setup.
Why it exists
- Safe sandbox — open PR/MR #1, branch compares, and checks without touching product repos like remogram.
- Cross-forge parity — same
main+feature/smoke-1branches and open PR/MR #1 on each host. - Ready-made config — copy
config/remogram.*.json.example→.remogram.jsonper forge (tokens in env only). - Full v1 battery — scripts run
doctor,repo status,refs compare,pr view,pr checks, andmerge plan(CLI and MCP captures).
Quick start
git clone https://gitlab.com/attebury/remogram-smoke.git
cd remogram-smoke
cp config/remogram.github.json.example .remogram.json # or gitlab / gitea example
export GITHUB_TOKEN=... # or GITLAB_TOKEN / GITEA_TOKEN
remogram doctor --json
remogram pr view --number 1 --json
Multi-forge capture (requires tokens; skips hosts without auth):
./scripts/run-smoke-all.sh
Results land under runs/<timestamp>/ with a human-readable REPORT.md. See the remogram-smoke README for auth scopes, mirror publishing, and expected forge facts (e.g. check_conclusion: "missing" on Gitea without CI statuses).
Note: Payload-size smoke compare (npm run smoke:compare-*) lives in the Remogram developer monorepo only and is not shipped in npm beta. For live verification after install, use remogram-smoke and --json packets instead.
MCP
Remogram MCP (remogram-mcp) is a stdio MCP server (agent-agnostic). Each host has its own config file format.
./scripts/npm-link.sh # remogram-mcp on PATH
./scripts/install-project-mcp.sh # Cursor only: .cursor/mcp.json.example → .cursor/mcp.json
Labeled examples for Cursor, Claude Desktop, OpenAI Codex, and Claude Code: examples/mcp/README.md.
Set the provider-specific token in your environment. In consumer repos, set REMOGRAM_CWD to the repo root (see examples).
Testing
npm test # full suite
npm run test:coverage # remogram-core coverage report
npm run security:secrets -- --full-history
Optional local pre-push gate: ./scripts/install-pre-push-hook.sh.
| Layer | Location | What runs |
|---|---|---|
| Core unit | tests/core/ | Envelope, caps, HTTP, packet contracts |
| Provider | tests/provider/ | API adapters with mocked fetch + fixtures |
| CLI integration | tests/cli/ | Read-only commands via runCli with mock provider |
| MCP | tests/mcp/ | Tool listing, offline callTool, packet shaping |
- Tests live under
tests/**/*.test.mjsonly. - Coverage (
npm run test:coverage) reportspackages/remogram-coreonly. ref_compareon API providers requires a forge auth env var even though comparison uses local git;sync_plandoes not.- CI: GitHub Actions on push/PR to
main(.github/workflows/).
Packages
| Package | Role |
|---|---|
@remogram/core | Envelope, config, caps, HTTP utils |
@remogram/cli | CLI surface |
@remogram/mcp | MCP stdio adapter (delegates to CLI) |
@remogram/provider-gitea-api | Gitea REST — use with "provider": "gitea-api" |
@remogram/provider-github-api | GitHub REST/GraphQL — use with "provider": "github-api" |
@remogram/provider-gitlab-api | GitLab REST — use with "provider": "gitlab-api" |
@remogram/provider-gitea-tea, @remogram/provider-github-gh | Reserved CLI-wrapper placeholders (not implemented; see CLI wrapper providers) |
Provider capabilities
remogram provider capabilities --json returns structured provider facts: which commands are implemented, auth env names, check source support, mergeability confidence, host-binding mode, and write_support: false for v1.
For stub providers (github-gh, gitea-tea), every command shows "implemented": false. GitLab has no wrapper stub yet — use gitlab-api.
Doctor
remogram doctor --json reports config presence/schema validity, git remote parsing, owner/repo matching, trusted host binding, auth env presence, and provider capabilities. It never returns token values.
GitHub normalization notes
For pr view / MCP pr_status, github-api uses GraphQL field selection instead of full REST pull JSON because large REST bodies often exceed Remogram's 8192-byte forge HTTP ingest cap.
GitHub commit statuses and check-runs merge into statuses[] with normalized state. mergeable reduces to clean, conflicted, or unknown. Public github.com uses https://api.github.com; GitHub Enterprise derives https://<host>/api/v3.
GitLab normalization notes
gitlab-api maps merge requests to the shared PR vocabulary (iid → pr_number). Commit statuses and pipelines merge into statuses[]. Public gitlab.com uses https://gitlab.com/api/v4; self-managed hosts derive https://<host>/api/v4.
Agent skills
Canonical skills live under tools/remogram-agent-support/skills/ (remogram-consumer, remogram-core). See tools/remogram-agent-support/README.md for details.
GitHub vs npm: Agent skills are not in the @remogram/* npm packages (those ship CLI/MCP only). npx skills add … clones from the GitHub repo github.com/attebury/remogram — the owner/repo shorthand is GitHub notation, not an npm scope.
Option A — npx skills (recommended for npm/GitHub users)
Uses the open Agent Skills CLI (vercel-labs/skills). Skills install to agent-specific paths (project: .agents/skills/; global Cursor: ~/.cursor/skills/, global Codex: ~/.codex/skills/).
# Consumer — any repo with .remogram.json (install once, global)
npx skills add attebury/remogram --skill remogram-consumer -g -a cursor,codex -y
# Contributor — this repo (project scope)
npx skills add attebury/remogram --skill remogram-core -a cursor -y
# List available skills without installing
npx skills add attebury/remogram --list
Explicit subpath (same skills, narrower source):
npx skills add attebury/remogram/tree/main/tools/remogram-agent-support --skill remogram-consumer -g -y
npx skills does not install Cursor rules (.cursor/rules/) or the Claude Code plugin adapter — those stay in-repo or use Option B.
Option B — install script (Remogram repo checkout)
From a clone of this repository — syncs .cursor/skills/, Codex global skills, and optional Claude plugin:
./scripts/install-agent-skills.sh --all
| Flag | Target |
|---|---|
--cursor | .cursor/skills/ in this repo (remogram-core) |
--codex | ~/.codex/skills/ (remogram-consumer + remogram-core) |
--claude PATH | copy Claude Code plugin adapter |
--consumer-only | With --codex, install only remogram-consumer |
--dogfood | Also install remogram-dogfood (private maintainer checkout only; hidden from public GitHub) |
--all | --cursor and --codex (default when no flags) |
Private remo maintainers with Topogram dogfood: ./scripts/install-agent-skills.sh --cursor --dogfood.
Contributing
See CONTRIBUTING.md.