RForge Plugin
R package ecosystem orchestrator for Claude Code — 44 commands, R-aware hooks, validation skills.
Self-contained R package analysis for Claude Code. As of v1.3.0 the plugin is fully self-sufficient — pure-Python lib/ modules handle discovery, dependencies, status, and init. No MCP server required.
Codex personal plugin
The native rforge-openai adapter 0.1.1 provides two skills:
$rforge-check for package validation and $rforge-docs-check for static
README/vignette API audits. Both reuse the Rforge engines and have been verified
in fresh sessions on isolated medfit copies. The adapter is integrated on dev
(PR #92); it is not a published
adapter release or a port of the Claude command catalog and hooks.
Start with the Codex installation and checks guide. Claude
marketplace and Homebrew installation below do not install these Codex skills.
What's new in v2.22.1
- 🔢
--run-examples compares short integers exactly. A documented whole number of up to six digits must match the real output ([1] 100 against [1] 101 is now a mismatch). Decimals, scientific notation and longer integers keep their tolerance. See the Docs audit guide.
What's new in v2.22.0
- 🌐
/rforge:docs:check --site URL [--ref REF] audits a deployed pkgdown site over HTTP and --run-examples [--examples-budget-seconds 300] replays README examples in a guarded R process. Both are opt-in; the default stays offline. Incomplete stages exit 2 with either enabled threshold, and --site reports pkgdown development-mode sites and .qmd articles as incomplete rather than clean. Accepted on ubuntu-24.04 and macos-14 (662 required checks each). See the Docs audit guide.
What's new in v2.21.0
- 🔎
/rforge:docs:check is a real docs audit — lib/docaudit.py checks the calls and signatures in your README and vignettes against the package exports: signature-named-arg (error), signature-names / signature-arity (warn), scannability (info), --since coverage. --eco, --detailed, --fail-on none|warn|error, docs.allowlist. Reports end INCOMPLETE / NOT AUDITED instead of no findings when it could not finish. Opt-in A2 stages add --site URL [--ref REF] and --run-examples [--examples-budget-seconds 300]; the default stays offline. README execution is partial coverage and runs package code. Completed A2 discrepancies are warnings; incomplete stages exit 2 with either enabled threshold. See the Docs audit guide.
- 🐛
/rforge:finish keeps .STATUS version annotations and still adds version: when missing (#84).
- 📚 New Ecosystem analysis guide, a "Fix a docs:check finding" tutorial, corrected command cards, one Quick Start.
What's new in v2.20.1
- 🐛
.STATUS parsing fixes — lib.status (behind /rforge:status and /rforge:health) now reads the key: value frontmatter dialect every mediationverse package uses (#75) and takes phase only from a phase: key, not from old history lines in the prose (#82).
- 🐛
/rforge:restore NEWS count — entries grouped under ## subsections are counted again (#78).
- 📚 MediationVerse doctrine in the CRAN-submission, dev-cycle and S7-review Command Guides (#76).
What's new in v2.20.0
- 🔖
/rforge:restore + /rforge:finish (PR #71) — R-package session-boundary commands: recap a single package's state (DESCRIPTION/NEWS.md/git/.STATUS) and sync .STATUS from what actually happened, dry-run by default with a redundant-edit guard and a version-drift check against DESCRIPTION.
- 🛡️ Backed by a new
lib/rstatus.py reader/differ, with an apply_updates() helper closing a data-loss trap (a bare RStatus(...) construction silently defaulted every untouched field to None) found in a 4-agent adversarial review before merge.
What's new in v2.19.0
- 🔍
r:urlcheck evidence-based 403 triage (#67) — replaces the hardcoded doi.org heuristic with root-then-URL probing, classifying dead/real_403 (gate) vs bot_blocked/transient (advisory).
- 🐛
r:rhub dispatch bugfix (#66) — rhub::rhub_check()'s first param is gh_url, not a local path; fixed via setwd().
- 🧹
r:tidy command + r:lint --tidy (#65) — tidyverse-conventions audit: lint preset, DESCRIPTION normalization, roxygen completeness, NEWS.md header currency.
Full release history: CHANGELOG.md.
Quick Start
# Quick analysis (< 30 seconds)
/rforge:analyze "Update RMediation bootstrap algorithm"
# Ultra-fast (< 10 seconds)
/rforge:quick
# CRAN submission gate (per-package)
/rforge:r:cran-prep
# Ecosystem rollup (2-5 minutes)
/rforge:thorough "Prepare for CRAN release"
Features
✨ Auto-delegation - Recognizes task patterns, selects appropriate tools
⚡ Parallel execution - Invokes multiple lib/ modules simultaneously
📊 Live progress - Real-time updates as tools complete
🎯 Smart synthesis - Combines results into actionable summary
🧠 ADHD-friendly - Fast feedback, clear structure, visual progress
🐍 Pure-Python lib/ - lib/discovery.py, lib/deps.py, lib/status.py, lib/init.py, lib/cranlint.py (pure Python, no R); lib/rcmd.py runs R engines for the r:* dev-cycle + CRAN commands. No MCP server, no Node.js. See docs/lib-modules.md.
How It Works
User Request
↓
Pattern Recognition (CODE_CHANGE, BUG_FIX, etc.)
↓
Tool Selection (impact, tests, docs, health)
↓
Parallel `lib/` invocations (python3 -m lib.* in subprocess)
↓
Results Synthesis (impact + quality + maintenance + next steps)
↓
Actionable Summary
Skills
/rforge:analyze
Balanced analysis with recommendations (< 30 seconds)
/rforge:analyze "Update code"
/rforge:quick
Ultra-fast status check (< 10 seconds)
/rforge:quick
/rforge:thorough
Comprehensive analysis with R CMD check (2-5 minutes)
/rforge:thorough "Prepare for CRAN"
Requirements
- Python 3.10+ (the
lib/ modules run via python3 -m lib.<tool>)
- R Environment
- R >= 4.0.0
- devtools package (optional, for
/rforge:thorough)
- testthat package (optional)
- covr package (optional, for coverage analysis)
- Claude Code CLI or Claude Desktop
- Plugin works in both environments
Migrating from v1.2.x? If you have an mcpServers.rforge entry in
~/.claude/settings.json, you can remove it — v1.3.0 no longer needs the
MCP server. See docs/migration/rforge-mcp-deprecation.md.
Installation
Option 1: Claude Code Marketplace (Recommended)
From inside Claude Code:
/plugin marketplace add Data-Wise/rforge
/plugin install rforge
The marketplace install reads .claude-plugin/marketplace.json from the
repository, fetches the plugin into ~/.claude/plugins/rforge, and wires
it up automatically. Works on macOS, Linux, and Windows. Update later with
/plugin update rforge.
Option 2: Homebrew (macOS)
# Add the Data-Wise tap
brew tap data-wise/tap
# Install rforge plugin
brew install rforge
The Homebrew formula automatically:
- Installs the plugin to
~/.claude/plugins/rforge
- Makes it available in Claude Code CLI and Claude Desktop
Option 3: Manual Installation (Local Development)
For Claude Code CLI and Claude Desktop:
# Clone the repository
git clone https://github.com/Data-Wise/rforge.git
cd rforge
# Install in development mode (symlink - changes reflected immediately)
ln -s $(pwd) ~/.claude/plugins/rforge
# Or install in production mode (copy - stable)
cp -r . ~/.claude/plugins/rforge
Installation locations:
- Plugin directory:
~/.claude/plugins/rforge
- Commands:
~/.claude/plugins/rforge/commands/
- Agent:
~/.claude/plugins/rforge/agents/orchestrator.md
- Lib:
~/.claude/plugins/rforge/lib/
Verify Installation
Step 1: Check plugin
# Check plugin directory exists
ls -la ~/.claude/plugins/rforge
# Verify plugin.json
cat ~/.claude/plugins/rforge/.claude-plugin/plugin.json
Step 2: Check Python
python3 --version # Expect 3.10+
Step 3: Test end-to-end
# Navigate to an R package
cd ~/projects/r-packages/active/RMediation
# Start Claude Code
claude
# Test a command
/rforge:status
Expected output:
📊 RMediation - Single Package
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Version: 2.4.0
Tests: 187 passing
Health: 87/100 (B+)
Using in Claude Code CLI
After installation, commands are immediately available:
# Navigate to any R package
cd ~/my-r-package
# Start Claude Code
claude
# Use rforge commands
/rforge:analyze "Update bootstrap algorithm"
/rforge:status
/rforge:quick
Using in Claude Desktop App
RForge automatically loads when you open Claude Desktop. Commands work the same way:
- Open Claude Desktop app
- Navigate conversation to an R package directory (or specify path)
- Use slash commands:
/rforge:analyze, /rforge:status, etc.
Migration
- From v1.2.x: the
mcpServers.rforge entry in ~/.claude/settings.json is no longer needed in v1.3.0. Remove it manually (we don't auto-edit user settings). See docs/migration/rforge-mcp-deprecation.md for the full migration table.
Migration from rforge-orchestrator (historical, pre-v1.3.0)
Only relevant if you skipped v1.2.x and are coming from a much older
rforge-orchestrator setup. v1.3.0 doesn't use any MCP server, so the
end state is just: remove these entries entirely.
If your ~/.claude/settings.json has either an rforge-orchestrator or rforge-mcp entry under mcpServers, delete it:
// Delete BOTH of these patterns if present:
{
"mcpServers": {
"rforge-orchestrator": { ... },
"rforge-mcp": { ... }
}
}
In v1.3.0+ the plugin runs entirely in-process via lib/ modules — there's no MCP server to configure. The plugin loads via /plugin install rforge; no settings.json entries are required.
For the full transition narrative, see docs/migration/rforge-mcp-deprecation.md.
Pattern Recognition
The orchestrator automatically detects what you're doing:
| Your Request | Pattern | Tools Used |
|---|
| "Update algorithm" | CODE_CHANGE | impact, tests, docs, health |
| "Add function" | NEW_FUNCTION | detect, tests, docs |
| "Fix bug" | BUG_FIX | tests, impact |
| "Update docs" | DOCUMENTATION | docs, detect |
| "Release 2.1.0" | RELEASE | health, impact, tests, docs |
Example Outputs
Quick Analysis
⚡ Quick analysis running...
✅ Done! (8.2 seconds)
📊 QUICK SUMMARY:
✅ Impact: 2 packages (MEDIUM)
✅ Tests: 187/187 passing
⚠️ Docs: NEWS.md needs update
✅ Health: 87/100 (B+)
Full Analysis
🎯 IMPACT: MEDIUM
• 2 packages affected (mediate, sensitivity)
• Estimated cascade: 4 hours
✅ QUALITY: EXCELLENT
• Tests: 187/187 passing (94% coverage)
• CRAN: Clean
📝 MAINTENANCE: 2 items
• NEWS.md needs entry
• Vignette example outdated
📋 NEXT STEPS:
1. Implement changes (3 hours)
2. Auto-fix documentation
3. Run cascade for dependents
Architecture
┌─────────────────────────────────────┐
│ Claude Code Session │
│ │
│ ┌───────────────────────────────┐ │
│ │ RForge Orchestrator Plugin │ │
│ │ │ │
│ │ • Pattern Recognition │ │
│ │ • Tool Selection │ │
│ │ • Parallel Execution │ │
│ │ • Progress Display │ │
│ │ • Results Synthesis │ │
│ └───────┬───────────────────────┘ │
│ │ │
└──────────┼──────────────────────────┘
│ Parallel python3 -m lib.* calls
↓
┌──────┴──────┬──────┬──────┐
↓ ↓ ↓ ↓
[discovery] [deps] [status] [init]
↓ ↓ ↓ ↓
(8s) (5s) (3s) (7s)
│ │ │ │
└─────────────┴──────┴──────┘
│
↓
Results synthesized
by orchestrator
Performance
| Mode | Tools | Time | Use Case |
|---|
| Quick | 4 quick tools | ~10s | Status check |
| Analyze | 4 quick + synthesis | ~30s | Daily dev |
| Thorough | Background R | 2-5m | Pre-release |
Time savings: Parallel execution = 4x faster than sequential!
ADHD-Friendly Design
- Fast feedback - Results in seconds, not minutes
- Clear structure - Consistent output format
- Visual progress - See what's happening
- Actionable - Always provides next steps
- Interruptible - Can cancel/resume anytime
- Incremental - Results stream as they complete
Troubleshooting
"python3: command not found"
# Verify Python 3.10+ is on PATH
python3 --version
# macOS: install via Homebrew
brew install [email protected]
"Package not detected"
# Run from package directory
cd /path/to/package
# Or specify path explicitly
/rforge:analyze --package /path/to/package
"Analysis too slow"
- Use
/rforge:quick for fast status
- Use
/rforge:analyze for balanced speed/depth
- Only use
/rforge:thorough when needed
Configuration
Plugin settings in plugin.json:
{
"settings": {
"default_mode": "quick", // quick, analyze, or thorough
"parallel_execution": true, // Run tools in parallel
"show_progress": true, // Show progress bars
"auto_synthesize": true // Auto-generate summary
}
}
Development
Plugin structure:
~/.claude/plugins/rforge/
├── .claude-plugin/
│ ├── plugin.json # Plugin manifest (v2.21.0)
│ ├── marketplace.json # Marketplace install metadata
│ ├── config.json # User-tunable options (CRAN mirror, etc.)
│ ├── hooks/
│ │ └── pretooluse.py # R-aware Write/Edit guard (4 rules)
│ └── skills/
│ └── validation/
│ └── description-sync.md # DESCRIPTION ↔ NEWS.md drift check
├── commands/ # 44 slash commands (/rforge:*)
├── agents/
│ └── orchestrator.md # Pattern recognition + delegation
├── lib/ # Pure-Python analysis modules
│ ├── discovery.py # Package detection + ecosystem layout
│ ├── deps.py # Dependency graph + impact
│ ├── status.py # DESCRIPTION + .STATUS health snapshot
│ ├── init.py # ~/.rforge/context.json initializer
│ ├── rcmd.py # R dev-cycle + quality + CRAN-submission engines (v2.7.0)
│ ├── cranlint.py # CRAN-incoming linter — DESCRIPTION + build-hygiene (v2.3.0)
│ └── formatters.py # Output formatting helpers
└── docs/ # User-facing docs
Contributing
Ideas for improvement:
License
MIT
Links
Version: 2.22.1
Status: Active development
Compatibility: Claude Code 0.1.0+
