Türkçe / English

A self-critical AI research colleague for scientists.

Objectivity Guardrails release: proposal-file workflow, structured search intent planning, neutral assumption framing, and Stage 9 objectivity review.

Proposal-first research, grounded in evidence.

Terminal-first today. Full end-to-end web interface coming soon.

ScholarClaw helps you turn a research proposal into a better-grounded experiment plan and paper draft.

You give it a short research proposal in proposal.md. It searches the literature, checks whether the idea looks novel, finds weak spots, plans experiments, and writes structured research artifacts you can inspect.

Use it when you want a research assistant that challenges the idea before writing the final paper.

ScholarClaw helps researchers:

• search the literature that actually matters for the field
• see whether an idea is novel, crowded, or still unclear
• strengthen proposals before time is spent on execution
• keep the work grounded in evidence from the start
• carry the work forward through execution, review, revision, and publication when the foundation is strong

Step-by-step guide (recommended): English · Türkçe

That guide explains, in plain language, how to run ScholarClaw, what each phase produces, and where to open your results.

ScholarClaw runs in your Terminal (the command-line app on Mac or Linux). You do not need to write code. You copy a few commands, press Enter, and then read the HTML reports it creates.

What you do:

1. Install ScholarClaw once (setup below).
2. Edit proposal.md with your research idea.
3. Open the HTML files in your web browser and read the reports.

How the work is organized:

The five buckets (run these in order):

Buckets vs single stages: Use a bucket when you want a whole phase (for example, everything up to the experiment plan). Use one stage only when you need to rerun a single step after fixing something.

Your first run (copy-paste):

# 1. Use the sample proposal, or edit proposal.md with your own research idea

# 2. Proposal phase — literature, hypotheses, experiment plan
scholarclaw run -c config.yaml --topic-file proposal.md --bucket proposal

# 3. After you approve Stage 9 (see below), run experiments
scholarclaw run -c config.yaml --output artifacts/<your-run-folder> --bucket execution

The repository includes a sample proposal.md. Read it first to see the kind of input ScholarClaw expects: a researcher-style brief with a problem, research questions, hypotheses, scope, candidate datasets, method, metrics, expected contribution, and reproducibility notes.

Replace the contents of proposal.md with your own proposal when you are ready. Replace artifacts/<your-run-folder> with the folder ScholarClaw printed when the first run finished (for example artifacts/rc-20260523-153055-23e65e).

Where to read results: Open these files in your browser (double-click, or drag into Chrome/Safari):

• artifacts/<your-run-folder>/stage-01/goal.html — research goal
• stage-08/hypotheses.html — hypotheses
• stage-09/experiment_plan.html — experiment plan (review this before continuing)

Before Stage 10: ScholarClaw pauses at Stage 9 for your approval. Read experiment_plan.html, including the Objectivity Review. If it looks good, either rerun Stage 9 with --auto-approve, or approve manually.

Use plain research language. You do not need to write code.

Good proposal input usually includes:

• the research problem
• why the problem matters
• research questions
• hypotheses or claims you want tested
• scope and limits
• candidate datasets or sources
• proposed methods or comparison groups
• metrics for success
• risks, limitations, and reproducibility requirements

It is okay if your wording is optimistic, skeptical, or incomplete. ScholarClaw now treats the proposal as claims to test, not conclusions to confirm. It creates objectivity artifacts such as proposal_objectivity.json, proposal_assumption_frame.json, and objectivity_contract.json, then shows plain-language objectivity warnings in the HTML reports.

For literature search, ScholarClaw also converts your proposal into short, inspectable search intents in proposal_search_intent.json. Long prose, numbered comparison lists, and full-sentence sections stay in the proposal for context, but they are not pasted directly into browser search URLs.

• A Mac or Linux computer (Windows via WSL also works)
• Python 3.11 or newer (download)
• An AI API key — we recommend OpenRouter (sign up, create a key, paste it below)
• Optional: Playwright, only if you want browser-based paper search

On Mac: open Terminal, then:

cd path/to/AutoResearchClaw

Replace path/to/AutoResearchClaw with where you downloaded the project.

This keeps ScholarClaw’s dependencies isolated. Run once:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

After this, your Terminal prompt may show (.venv) — that means the environment is active.

Standard install (enough for most users):

pip install -e .

Optional — only if you want automated browser paper search:

pip install -e ".[browser]"
playwright install

cp my.config.yaml config.yaml

Open config.yaml in any text editor. For OpenRouter (easiest start), it should look like:

llm:
  mode: "openrouter"
  provider: "openrouter"
  api_key_env: "OPENROUTER_API_KEY"
  primary_model: "anthropic/claude-sonnet-4"

Set your API key in Terminal (replace with your real key):

export OPENROUTER_API_KEY="your-key-here"

You must run this export command in the same Terminal window each time you open a new session, or add it to your shell profile.

For a local AI server (LM Studio) instead of OpenRouter:

llm:
  mode: "lmstudio"
  provider: "lmstudio"
  base_url: "http://127.0.0.1:1234/v1"
  primary_model: "local-model-name"

scholarclaw validate -c config.yaml
scholarclaw doctor -c config.yaml

If both commands finish without errors, you are ready to run.

Recommended — proposal bucket only (stages 1–9):

scholarclaw run -c config.yaml --topic-file proposal.md --bucket proposal

Skip approval prompts (useful for unattended runs):

scholarclaw run -c config.yaml --topic-file proposal.md --bucket proposal --auto-approve

Run one specific step only (after a prior run exists):

scholarclaw run -c config.yaml --output artifacts/your-run-folder --only-stage EXPERIMENT_DESIGN

Continue after interruption:

scholarclaw run -c config.yaml --output artifacts/your-run-folder --resume --bucket proposal

When a run finishes, ScholarClaw prints a folder path like artifacts/rc-20260523-153055-23e65e/.

Open the HTML files below in your browser. You do not need to understand JSON or YAML unless you are debugging.

scholarclaw report artifacts/<your-run-folder>

Most useful reports to open first:

Proposal bucket stages 1–9 (sample run):

Stage 1: Goal	Stage 2: Problem Tree	Stage 3: Search Strategy

Stage 4: Literature Collect	Stage 5: Literature Screen	Stage 6: Knowledge Extract

Stage 7: Synthesis	Stage 8: Hypotheses	Stage 9: Experiment Design

• 22-stage research pipeline from idea to proposal, experiments, paper draft, review, and revision
• Literature retrieval through APIs and optional browser automation
• LLM-assisted connector routing with probe validation, prior-run source feedback, and deterministic OpenAlex/Semantic Scholar/arXiv fallback
• Evidence quality checks so weak or off-topic papers are easier to spot
• Novelty checking, citation verification, and citation relevance pruning
• Objectivity guardrails that treat proposal wording as claims to test, not truth to confirm
• Structured proposal search intent planning with source-safe browser queries and quality gates
• Neutral assumption frames and objectivity contracts before hypotheses and experiment design
• Experiment planning, benchmark planning, and result analysis
• BenchmarkAgent experiment-task gating (structured evaluation signals, not ML-only keywords) so off-domain datasets and baselines are rejected before injection
• DatasetVerifier provenance and accessibility checks for benchmark candidates (curated registry, HuggingFace Hub, or explicit metadata)
• Stage 9 validation warnings, Objectivity Review, and gate readiness surfaced in experiment_plan.html and proposal_decision_state.json
• Stage-specific model routing and checkpoint/resume support
• Single-file HTML reports for important review surfaces, with humanized metric and ablation labels
• Data-shape driven figure planning — chart families follow result structure (conditions, training history, matrices), not topic keywords

Three-way view against upstream AutoResearchClaw and ScienceClaw.

Legend: ✅ supported · ❌ not first-class today · ⚠️ partial or different model · ⭐ ScholarClaw differentiator · 🔬 ScienceClaw differentiator

_{Comparison reflects the public feature surfaces of AutoResearchClaw and ScienceClaw at the time of this release.}

ScholarClaw is for researchers who want help thinking more clearly before they commit to a research direction.

From early idea to proposal, and from execution to publication, the focus is not just speed.

The focus is better research judgment, earlier in the process.

Each run writes to artifacts/<run-id>/ (or your --output path). Every stage gets its own folder: stage-01/, stage-02/, …

How to read outputs

Legend: 🛑 approval gate · 📄 HTML report · 📦 machine-readable only

Open these after scholarclaw run --bucket proposal:

Also check stage-09/proposal_decision_state.json for gate readiness and validation warnings.

HTML reports are self-contained (inline CSS). JSON, YAML, and Markdown remain the source of truth for downstream stages.

Generate a navigable index from any completed run:

scholarclaw report artifacts/<run-id>

Too many research workflows jump straight from idea to output. They summarize quickly, generate confidently, and move on before the core questions have been tested:

• Has this already been done?
• Is the idea truly different, or just phrased differently?
• What would make the contribution stronger?
• What would a serious reviewer challenge?

ScholarClaw is designed to stay with those questions longer, because that is where better research begins.

It is also designed to ask those questions in the right research context, so ideas are judged against the literature that actually matters for the field.

• scholarclaw run for full or bucket-scoped execution
• scholarclaw list-stages to inspect the pipeline before running it
• scholarclaw validate to validate config early
• scholarclaw doctor for environment and configuration health checks
• scholarclaw report to generate a readable summary from a completed run

ScholarClaw is not meant to be just another paper generator.

It is shaped as a research partner that challenges ideas, surfaces evidence, and helps build stronger work from the beginning.

It is especially useful when you want to:

• map ideas against the literature that matters for the field
• identify novelty risks before time is spent on execution
• suggest stronger positioning when an idea is too close to prior work
• surface weak spots, missing comparisons, and likely reviewer objections early
• help shape proposals with clearer positioning and higher ambition
• keep the work grounded in evidence instead of confident but unsupported claims
• support the path from proposal to experiments and paper when the foundation is strong

ScholarClaw is currently in active development.

The direction is clear: better research judgment earlier, stronger evidence throughout, and more defensible work by the time a paper is written.

• Full-featured web interface that starts with entering a research idea and carries the workflow all the way to a produced paper.
• End-to-end UI for configuring runs, monitoring stage progress, browsing artifacts, and managing long-running review, revision, and approval workflows without living in the terminal.

ScholarClaw builds on the foundation of AutoResearchClaw and is evolving into its own more focused, evidence-grounded research product.