rrp-agentic-research-framework

rrp-agentic-research-framework

A Claude Code multi-agent research framework. Give it a topic; it researches the public web and (optionally) a local document corpus (PDF/EPUB/Markdown/ text/HTML) in parallel, and writes Obsidian-ready markdown notes. It also has a strict true-copy mode that reproduces one public source verbatim via a deterministic, non-LLM conversion pipeline with a mandatory word-for-word fidelity check.

All content extraction (web fetches, PDF/EPUB/HTML parsing) runs inside a locked-down Docker sandbox -- non-root, read-only root filesystem, dropped capabilities, no unbounded network -- so nothing it downloads or parses can touch the host beyond the specific output directory you point it at. Every fetch is checked against a safety blocklist (a maintained malware/phishing feed + a small curated piracy list + your own live-editable custom list) before it happens.

Requirements

• Docker (daemon running, usable without needing sudo for your user)
• uv (curl -LsSf https://astral.sh/uv/install.sh | sh)
• Claude Code

Install

git clone <this-repo-url> rrp-agentic-research-framework
cd rrp-agentic-research-framework
./install.sh

This builds the sandbox image, refreshes the safety blocklist, and activates the plugin at ~/.claude/skills/rrp-agentic-research-framework/ (auto-loads as rrp-agentic-research-framework@skills-dir on your next Claude Code session). It also additively patches ~/.claude/settings.json so /research doesn't nag you for permission on every web fetch or Bash call -- only three narrowly-scoped entries are added (WebSearch, WebFetch, and Bash restricted to this framework's own wrapper scripts), and the original file is backed up first.

This is a global install (~/.claude/... and ~/.local/share/..., not anything project-local) -- once installed, /research is available from any project directory on this machine, not just this repo checkout.

Re-running install.sh any time (e.g. after git pull) is safe -- it's idempotent, and it never overwrites your data/blocklist/custom-blocklist.txt.

Use

/research "history of the CAP theorem"
/research "topic" --corpus ~/Documents/my-papers
/research "topic" --output ~/work/notes/obsidian-vaults/SoftwareEngineeringResources
/research --true-copy https://www.gutenberg.org/cache/epub/1342/pg1342.txt

/research always asks where to save output unless you pass --output -- press Enter to default to your home directory. Nothing is hardcoded to a specific vault; point it at any folder, Obsidian vault or not.

Adding to your own blocklist

Edit this file any time you personally spot something fishy -- it takes effect on the very next request, no reinstall or restart needed:

~/.local/share/rrp-agentic-research-framework/data/blocklist/custom-blocklist.txt

One domain per line (blocks it and all subdomains), or re:<pattern> for a regex against the hostname.

Using it from another agent framework (not just this Claude Code plugin)

The deterministic tool layer -- blocklist checks, web fetch, PDF/EPUB/HTML conversion, true-copy, corpus search -- is also exposed as an MCP server, so any MCP-compatible framework can call it directly, independent of Claude Code's plugin/subagent system:

uv run --project ~/.local/share/rrp-agentic-research-framework rrp-agentic-research-framework-mcp

Point any MCP client (Claude Desktop, another Claude Code instance, LangChain/AutoGen with MCP support, etc.) at that stdio command.

For local development/testing without running install.sh at all, this repo's own .mcp.json registers the same server directly from the checkout (uv run --project . rrp-agentic-research-framework-mcp) -- useful for iterating on the MCP tools themselves.

Uninstall

./uninstall.sh            # removes the plugin, sandbox image, and support
                           # runtime; keeps your custom blocklist + audit log
./uninstall.sh --purge-all  # also removes those

Reverses exactly what install.sh added to ~/.claude/settings.json -- never touches any other setting, and never touches any research notes you've already generated in whatever output directory you pointed it at.

Architecture

rrp-agentic-research-framework/
├── agents/                     # Claude Code subagents (LLM-reasoning layer)
│   ├── web-researcher.md
│   ├── offline-researcher.md
│   └── true-copy-extractor.md
├── commands/
│   └── research.md             # /research orchestrator: resolves output
│                                # location, dispatches subagents in parallel
├── bin/                        # host-side wrapper scripts -> run inside Docker
│   ├── ra-fetch-web.sh
│   ├── ra-convert-pdf.sh / -epub.sh / -html.sh
│   ├── ra-true-copy.sh
│   ├── ra-index-corpus.sh / ra-search-corpus.sh
│   ├── ra-blocklist-check.sh
│   ├── ra-resolve-output-path.sh
│   ├── ra-refresh-blocklist.sh
│   ├── ra-build-image.sh
│   └── _lib.sh                 # shared shell helpers
├── docker/
│   └── Dockerfile              # locked-down sandbox image (non-root,
│                                # read-only rootfs, dropped capabilities)
├── src/research_agent/         # deterministic Python toolkit (import name
│   │                           # kept underscored; console scripts are
│   │                           # rrp-agentic-research-framework[-mcp])
│   ├── blocklist/              # blocklist checker (base feed + custom + heuristics)
│   ├── convert/                # PDF/EPUB/HTML -> Markdown, true-copy
│   ├── fetch/                  # web fetcher + paywall detection
│   ├── fidelity/               # true-copy word-for-word diff check
│   ├── frontmatter/            # Obsidian frontmatter schema + writer
│   ├── indexing/                # local corpus search index
│   ├── pathresolve/            # output path resolution
│   ├── audit/                  # audit logger
│   ├── cli.py                  # CLI entrypoint
│   ├── config.py
│   └── mcp_server.py           # MCP server exposing the toolkit
├── data/blocklist/
│   ├── static-supplement.txt   # framework-maintained piracy list
│   └── custom-blocklist.txt    # yours; created empty on install, never
│                                # overwritten by re-installs
├── .claude-plugin/
│   └── plugin.json             # plugin manifest
├── .mcp.json                   # local-dev MCP server registration
├── pyproject.toml              # package + console-script definitions
├── .python-version             # pinned to 3.12 (see note below)
├── install.sh
├── uninstall.sh
└── README.md

• agents/web-researcher.md, agents/offline-researcher.md, agents/true-copy-extractor.md -- Claude Code subagents (the LLM-reasoning layer: search, synthesize, cite -- never used for the true-copy conversion itself).
• commands/research.md -- the /research orchestrator: resolves the output location, dispatches the two research subagents in parallel, synthesizes their notes.
• src/research_agent/ -- the deterministic Python toolkit (blocklist checker, web fetcher, PDF/EPUB/HTML converters, fidelity checker, frontmatter writer, corpus search index, CLI, MCP server). Deliberately kept as the internal import package name (research_agent, underscored) even after the project itself was renamed -- it's never typed by a user, and a distribution name differing from its import path is normal (e.g. pip install scikit-learn imports as sklearn). Its own console-script names are rrp-agentic-research-framework / rrp-agentic-research-framework-mcp, set in pyproject.toml.
• docker/Dockerfile + bin/ra-*.sh -- the sandbox: every wrapper script (ra-fetch-web.sh, ra-convert-{pdf,epub,html}.sh, ra-true-copy.sh, ra-{index,search}-corpus.sh, ra-blocklist-check.sh, ra-resolve-output-path.sh, ra-refresh-blocklist.sh, ra-build-image.sh, and the shared _lib.sh) runs the CLI inside a --read-only, --cap-drop=ALL, --security-opt no-new-privileges container with only the bind mounts it actually needs.
• data/blocklist/static-supplement.txt -- framework-maintained piracy list; data/blocklist/custom-blocklist.txt -- yours, created empty on install.
• .python-version (pinned to 3.12) -- keeps uv from picking whatever newest Python it finds on the host, which on a bleeding-edge interpreter can lack prebuilt wheels for lxml and break the host-side MCP server.

See .claude-plugin/plugin.json for the plugin manifest, .mcp.json for the local-dev MCP registration, and LICENSE (MIT) for licensing.