Semi-automated research assistant for academic research and software development, especially for computer science and AI researchers. Supports Claude Code, Codex CLI, Kimi Code CLI, and OpenCode across literature review, coding, experiments, reporting, writing, and project knowledge management.
Branch note: the main branch is the Claude Code workflow. If you use Codex CLI, please see the codex branch. If you use Kimi Code CLI, please see the kimi branch. If you use OpenCode, please see the opencode branch.
Sponsors
Sponsor
Description
Thanks to APIMart for sponsoring this project! APIMart is a low-cost API platform for AI image & video generation — GPT-Image-2 from $0.006/image, 160+ images per dollar. One async API covers both image and video: submit a task, get an ID, fetch results via polling or callback. Batch tens of thousands of images without timeouts, switch models without changing code. Pay-as-you-go with no monthly fee — sign up here to get started.
2026-06-03: Kimi Code CLI branch added with strong support from Kimi — added the kimi branch as the Kimi Code CLI edition of Claude Scholar and thank the Kimi team for their strong support of this project.
2026-05-14: expression-skill made the communication core, planning-with-files restored as the default persistence layer, and the Nature writing stack expanded — made expression-skill the explicit conclusion-first discipline for reporting, planning, file operations, and multi-step technical work; reintroduced planning-with-files as the default on-disk planning and progress-tracking workflow for complex tasks; introduced nature-writing for section drafting and argument construction; refreshed nature-polishing to the latest upstream article-pattern release; and kept nature-response plus nature-data in the journal-writing stack.
2026-05-13: Evidence-gated research workflow and Sources/Papers routing tightened — added a shared research-contract.md for Evidence Records, claim strength, and Claim Promotion Gates; connected research ideation, Zotero ingestion, literature synthesis, results reporting, writing, and rebuttal workflows to that contract; and clarified that project paper notes live under Sources/Papers before promoted claims move into Knowledge or Writing.
2026-04-24: Project-scoped Obsidian KB workflow consolidated — rebuilt Obsidian project knowledge management into a vault-first workflow, consolidated the older overlapping memory skills into four focused skills, kept repo-local project binding metadata as a runtime layer, and made project navigation human-first instead of a machine registry dump.
2026-04-22: Lean core, pruned default agents, safer install lifecycle, and cleaner paper discovery — replaced large always-on CLAUDE.md / AGENTS.md files with compact core instructions, pruned the default agent set to the retained core agents, added safe install-state based uninstall support, generalized daily-paper-generator to broader topics with arXiv / bioRxiv support and a fixed Top 10 -> Top 3 -> Top 1 selection flow.
2026-04-15: pubfig and pubtab introduced — introduced pubfig, a Python package for publication-grade scientific figures, and pubtab, a Python package for publication-ready tables and Excel↔LaTeX workflows. Together they provide a cleaner production stack for paper figures, benchmark tables, export control, and final artifact QA.
View older changelog
2026-04-15: publication-chart-skill integrated into Claude Scholar — wrapped pubfig + pubtab into publication-chart-skill, added the skill to the repository, and connected it to Claude Scholar's analysis and writing boundaries so publication-grade figure/table work now has an explicit handoff route instead of being mixed into general analysis or prose skills.
2026-03-31: Zotero smart-import workflow docs aligned — updated Claude Scholar's research-facing docs around the latest zotero-mcp public surface: zotero_add_items_by_identifier is now the default paper-import path, zotero_reconcile_collection_duplicates is the standard post-import cleanup step, source-aware PDF cascade behavior is documented more accurately, and public vs internal diagnostics are now clearly separated.
2026-03-31: README onboarding refreshed — clarified that Claude Scholar is especially well-suited to computer science and AI researchers, added practical getting-started scenarios after installation, improved prerequisite and branch guidance, and made the “existing local md files must be manually merged” expectation much more explicit.
2026-03-31: Installer and hook behavior tightened — the installer now preserves existing local CLAUDE.md while installing the repo-managed version as CLAUDE.scholar.md, and the default hook summaries were trimmed to reduce noisy temp-file / uncommitted-file output while keeping safer write-guard behavior.
2026-03-31: Japanese documentation added — added Japanese docs for the main README plus AGENTS, MCP_SETUP, and OBSIDIAN_SETUP, so the OpenCode branch now has a more complete multilingual documentation surface.
2026-02-25: Codex CLI support — added codex branch supporting OpenAI Codex CLI with config.toml, 40 skills, 14 agents, and sandbox security
2026-02-21: OpenCode support — Claude Scholar now supports OpenCode as an alternative CLI; switch to the opencode branch for OpenCode-compatible configuration
2026-02-20: Bilingual docs — maintained English and Chinese entry documents for broader readability
2026-02-15: Zotero MCP integration — added /zotero-review and /zotero-notes commands, updated research-ideation skill with Zotero integration guide, enhanced literature-reviewer agent with Zotero MCP support for automated paper import, collection management, full-text reading, and citation export
2026-02-14: Hooks optimization — restructured security-guard to two-tier system (Block + Confirm), skill-forced-eval now groups skills into 6 categories with silent scan mode, session-start limits display to top 5, session-summary adds 30-day log auto-cleanup, stop-summary shows separate added/modified/deleted counts; removed deprecated shell scripts (lib/common.sh, lib/platform.sh)
2026-02-11: Major update — added 10 new skills (research-ideation, results-analysis, citation-verification, review-response, paper-self-review, post-acceptance, daily-coding, frontend-design, ui-ux-pro-max, web-design-reviewer), 7 new agents, 8 research workflow commands, 2 new rules (security, experiment-reproducibility); restructured the main configuration docs; 89 files changed
2026-01-26: Rewrote all Hooks to cross-platform Node.js; completely rewrote README; expanded ML paper writing knowledge base; merged PR #1 (cross-platform support)
Cite Claude Scholar in papers, reports, or project docs.
Why Claude Scholar
Claude Scholar is not an end-to-end autonomous research system that tries to replace the researcher.
Its core idea is simple:
human decision-making stays at the center; the assistant accelerates the workflow around it.
That means Claude Scholar is designed to help with the heavy, repetitive, and structure-sensitive parts of research — literature organization, note-taking, experiment analysis, reporting, and writing support — while still keeping the key judgments in human hands:
which problem is worth pursuing,
which papers actually matter,
which hypotheses are worth testing,
which results are convincing,
and what should be written, submitted, or abandoned.
In other words, Claude Scholar is a semi-automated research assistant, not a “fully automated scientist.”
Who This Is For
Claude Scholar is especially well-suited to:
computer science researchers who move between literature review, coding, experiments, and paper writing,
AI / ML researchers who need one assistant workflow spanning ideation, implementation, analysis, reporting, and rebuttal,
research engineers and graduate students who want stronger workflow structure without giving up human judgment,
and software-heavy academic projects that benefit from Zotero, Obsidian, CLI automation, and reproducible project memory.
It can still help in other research settings, but its current workflow design is most aligned with computer science, AI, and adjacent computational research.
Core Workflow
Claude Scholar routes research work through a traceable path:
question -> evidence -> experiment -> analysis -> claim -> writing.
Each stage should preserve what is known, what is uncertain, and what decision should happen next.
Ideation: turn a vague topic into concrete questions, research gaps, and an initial plan.
Literature: search, import, organize, and read papers through Zotero collections.
Paper notes: convert papers into structured reading notes and reusable claims.
backs up overwritten files to ~/.claude/.claude-scholar-backups/<timestamp>/,
backs up settings.json to settings.json.bak,
preserves an existing ~/.claude/CLAUDE.md and installs the repo-managed version as ~/.claude/CLAUDE.scholar.md,
preserves an existing ~/.claude/CLAUDE.zh-CN.md and installs the repo-managed version as ~/.claude/CLAUDE.zh-CN.scholar.md,
preserves your existing env, model/provider settings, API keys, permissions, and current mcpServers values,
adds missing hook entries instead of replacing your entire hook set.
Important CLAUDE note: if you already maintain your own ~/.claude/CLAUDE.md or ~/.claude/CLAUDE.zh-CN.md, review ~/.claude/CLAUDE.scholar.md and ~/.claude/CLAUDE.zh-CN.scholar.md after installation and manually merge the Claude Scholar sections you want into your own files. Do not assume the sidecar files are applied automatically.
To update later:
cd /tmp/claude-scholar
git pull --ff-only
bash scripts/setup.sh
To uninstall later:
cd /tmp/claude-scholar
bash scripts/uninstall.sh
The installer now writes:
~/.claude/.claude-scholar-manifest.txt for the exact files managed by Claude Scholar
~/.claude/.claude-scholar-install-state for install ownership metadata used by safe uninstall
The uninstaller removes only files and settings entries recorded in that install state. It does not guess ownership from the current repo checkout.
Post-install: minimal/manual install does not auto-merge settings.json; copy only the hooks or MCP entries you want from settings.json.template. If you already have your own ~/.claude/CLAUDE.md or ~/.claude/CLAUDE.zh-CN.md, also merge the relevant sections from this repo's Claude files into yours instead of blindly overwriting them.
Post-install: selective/manual install does not auto-merge settings.json; copy only the hooks or MCP entries you actually want from settings.json.template. If you already have your own ~/.claude/CLAUDE.md or ~/.claude/CLAUDE.zh-CN.md, merge the relevant sections from this repo's Claude files into yours instead of blindly overwriting them.
This auto-loads all skills, commands, agents, and hooks. During installation, you can choose the scope: user (all projects) or project (single project).
Step 2: Install Rules (Required)
Claude Code plugins cannot distribute rules automatically. Install them manually:
Post-install: plugin installation does not auto-load CLAUDE.md or configure settings.json; if you already have your own ~/.claude/CLAUDE.md or ~/.claude/CLAUDE.zh-CN.md, merge the relevant Claude Scholar sections into yours instead of assuming the plugin applies them automatically. If you need Zotero MCP or other integrations, see the Integrations section for manual setup.
Getting Started Scenarios
After installation, the simplest way to begin is to describe your task in natural language. You do not need to memorize the whole system first. Below are a few realistic starting points.
1. Start a New Research Topic
You can say:
Help me start research on [your topic]. I want a literature-grounded plan, the key
What is this?Claude Scholar is a semi-automated research assistant for academic research and software development, built especially for computer science and AI researchers. It routes work through ideation, literature review, coding, experiments, reporting, and writing/publication, and plugs into Claude Code, Codex CLI, Kimi Code CLI, and OpenCode.
Is it a standalone app, or a set of skills I add to my coding agent?It is not a standalone app - it is a bundle of skills, agents, commands, hooks, and rules that an installer drops into your existing Claude Code (or Codex CLI / Kimi Code CLI / OpenCode) configuration folder.
What do I need installed first?You need Claude Code and Git at minimum. Python + uv, Zotero (with the zotero-mcp server), and Obsidian are optional, needed only for the Python tooling, literature import, or knowledge-base workflows.
Does it fully automate research for me?No - it is explicitly semi-automated. It handles the repetitive literature, note-taking, analysis, and writing-support work, but deciding which problems to pursue, which papers matter, and what to publish stays a human call.
Who is this built for?Mainly computer science and AI/ML researchers, research engineers, and grad students who move between literature review, coding, experiments, and paper writing; it's less tuned to non-CS research fields.
How does it connect to Zotero?Through the companion zotero-mcp server: commands like /zotero-review and /zotero-notes let agents import papers by identifier, read full text, manage collections, and export citations straight from Zotero.
Where do validated research findings end up?They get routed into a project-scoped Obsidian vault organized into Sources, Knowledge, Experiments, Results, Writing, Daily, and Maps folders, so durable claims move from paper notes into reusable knowledge before reaching a draft.
What are pubfig and pubtab?They are companion Python packages wrapped into the publication-chart-skill: pubfig produces publication-grade scientific figures and pubtab produces publication-ready tables with Excel/LaTeX export, covering the final figure/table QA stage of a paper.
Can I use it with Codex CLI or Kimi Code CLI instead of Claude Code?Yes - the main branch is the Claude Code workflow, and separate branches exist for Codex CLI, Kimi Code CLI, and OpenCode, each with its own setup docs.
Claude Scholar is a semi-automated research assistant for academic research and software development, built especially for computer science and AI researchers. It routes work through ideation, literature review, coding, experiments, reporting, and writing/publication, and plugs into Claude Code, Codex CLI, Kimi Code CLI, and OpenCode.