https://github.com/flonat/claude-research
Shareable Claude Code infrastructure for PhD researchers — skills, agents, hooks, and rules for academic workflows
https://github.com/flonat/claude-research
academic-research ai-tools claude claude-code latex phd research-workflow
Last synced: 3 months ago
JSON representation
Shareable Claude Code infrastructure for PhD researchers — skills, agents, hooks, and rules for academic workflows
- Host: GitHub
- URL: https://github.com/flonat/claude-research
- Owner: flonat
- License: mit
- Created: 2026-02-20T10:45:59.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-23T21:19:36.000Z (3 months ago)
- Last Synced: 2026-03-24T19:54:57.778Z (3 months ago)
- Topics: academic-research, ai-tools, claude, claude-code, latex, phd, research-workflow
- Language: Python
- Size: 1.41 MB
- Stars: 16
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: docs/agents.md
Awesome Lists containing this project
- awesome-research-agents - Claude Code for an Academic Researcher - native])* — Full Claude Code infrastructure for academics with 48 skills, 6 agents, 9 hooks, rules, context libraries, LaTeX, bibliography tooling, Notion integration, and reviewer roles (domain reviewer, paper critic, peer reviewer, referee). (Skills, Workflow Packs, and Reusable Procedures)
README
# Claude Code for an Academic Researcher
Made by a humble PhD student. A complete Claude Code infrastructure for researchers — skills, agents, hooks, and rules for academic workflows. Built for researchers who write papers in LaTeX, manage bibliographies, run experiments, and want AI assistance that understands academic conventions.
Works on **macOS, Linux, and Windows**. Use Claude Code from the [terminal CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code](https://marketplace.visualstudio.com/items?itemName=anthropics.claude-code), [JetBrains IDEs](https://plugins.jetbrains.com/plugin/27189-claude-code), [the web](https://claude.ai/code), or the [desktop app](https://claude.ai/download) — all share the same skills, agents, and rules.
[](https://www.npmjs.com/package/flonat-research)
[](https://github.com/flonat/claude-research/releases)
## Installation
### Quick Install (npm)
```bash
npx flonat-research
```
This downloads the package and runs the setup script, which symlinks skills, agents, hooks, and rules into `~/.claude/`.
### Full Install (recommended for customisation)
#### macOS / Linux
```bash
git clone https://github.com/flonat/claude-research.git
cd claude-research
./scripts/setup.sh
```
#### Windows (PowerShell)
```powershell
git clone https://github.com/flonat/claude-research.git
cd claude-research
.\scripts\setup.ps1
```
The git clone gives you a local copy you can fully customise — edit `.context/profile.md`, `CLAUDE.md`, and workflows to match your research.
### Update
```bash
# macOS/Linux: pull latest, then re-link without overwriting settings
git pull && ./scripts/setup.sh --update
# Windows (PowerShell):
git pull; .\scripts\setup.ps1 -Update
```
Then customise `.context/profile.md`, `.context/current-focus.md`, and `CLAUDE.md` with your details. See [`docs/getting-started.md`](docs/getting-started.md) for the full guide (includes Windows-specific setup, Python install, and troubleshooting).
### Related Packages
| Package | Install | Description |
|---------|---------|-------------|
| [`llm-council`](https://github.com/flonat/llm-council) | `pip install llm-council` | Multi-model council via OpenRouter API |
| [`cli-council`](https://github.com/flonat/cli-council) | `pip install cli-council` | Multi-model council via local CLI tools |
## What's Included
| Component | Count | Description |
|-----------|-------|-------------|
| **Skills** | 38 | Slash commands for common tasks (`/proofread`, `/latex-autofix`, `/literature`, etc.) |
| **Agents** | 6 | Specialised reviewers (peer review, referee 2, paper critic, domain review, fixer) |
| **Hooks** | 8 | Automated guardrails (destructive git protection, context monitoring, etc.) |
| **Rules** | 9 | Always-on policies (plan before implementing, scope discipline, etc.) |
| **Context library** | — | Structured files that give Claude persistent memory across sessions |
| **Research Vault** | — | Obsidian-style markdown vault for tasks, pipeline, submissions, venues, people |
| **Bibliography MCP** | — | Multi-source scholarly search (OpenAlex + Scopus + WoS) — [setup guide](docs/biblio-setup.md) |
| **Council mode** | — | Multi-model deliberation (3 reviewers + synthesis) — [setup guide](docs/council-mode.md) |
| **CLI tools** | — | Vault task management from the terminal — [docs](docs/scripts.md) |
## Architecture
```
┌──────────────────────────────────────────────────────────────┐
│ Claude Code (Terminal) Claude Desktop (GUI) │
│ │ │ │
│ CLAUDE.md + Rules MCP Server (load-context) │
│ │ │ │
│ ┌────┴──────────────┬──────────────┐ │ │
│ │ │ │ │ │
│ Context ◄───────── Skills ◄──────┼─────┘ │
│ Library │ │ │
│ CLI Scripts Research Vault │
│ │
│ MEMORY.md ◄─────── Hooks & │
│ + Logs Permissions │
└──────────────────────────────────────────────────────────────┘
```
The MCP server's `load-context` tool gives Claude Desktop access to the context library and MEMORY.md — the same files Claude Code reads automatically.
## Components
**Context Library** (`.context/`) — Markdown files that give Claude persistent memory about you, your projects, and your workflows. Instead of re-explaining your research every session, Claude reads these files automatically.
**Skills** (`skills/`) — Slash commands invoked with `/` or natural language.
38 skills available. Key examples: `/proofread`, `/latex-autofix`, `/literature`, `/bib-validate`, `/code-review`, `/session-recap`, and more.
See [`docs/skills.md`](docs/skills.md) for the full catalogue.
**Agents** (`.claude/agents/`) — Specialised personas for complex review tasks, spawning sub-agents for parallel work.
| Agent | Use case |
|-------|----------|
| `domain-reviewer` | Research-focused substantive correctness agent |
| `fixer` | Generic fix implementer for any critic report |
| `paper-critic` | Read-only adversarial auditor for LaTeX papers |
| `peer-reviewer` | Use this agent when you need to review someone else's paper — as a peer reviewer, discussant, or for reading group preparation |
| `proposal-reviewer` | Use this agent when you need to review a research proposal, extended abstract, conference submission outline, or pre-paper plan — either his own or someone else's |
| `referee2-reviewer` | Use this agent when the user wants a rigorous, adversarial academic review of their work — including papers, manuscripts, research designs, code, or arguments |
See [`docs/agents.md`](docs/agents.md) for detailed descriptions.
**Hooks** (`hooks/`) — Automated guardrails that run at specific points in a session.
| Hook | Trigger | What it does |
|------|---------|-------------|
| `block-destructive-git.sh` | Before Bash | catches dangerous git/shell commands |
| `context-monitor.py` | After tool use | tracks tool call count as a heuristic for context usage |
| `postcompact-restore.py` | After compact | restores state after context compression |
| `precompact-autosave.py` | Before compact | saves state before context compression |
| `promise-checker.sh` | Session stop | catches "performative compliance": Claude says it remembered/noted/saved |
| `protect-source-files.sh` | Before edit/write | prompts confirmation for files outside |
| `resume-context-loader.sh` | Session resume | surfaces current focus and latest session log |
| `startup-context-loader.sh` | Session start | auto-detects and surfaces project documentation |
See [`docs/hooks.md`](docs/hooks.md) for full documentation.
**Rules** (`.claude/rules/`) — Always-on policies enforcing good research practices. See [`docs/rules.md`](docs/rules.md).
**Research Vault** — Obsidian-style markdown vault (`~/Research-Vault`) for tasks, pipeline, submissions, venues, people, and themes. Accessed via the `taskflow` MCP server.
**Biblio MCP** — Multi-source scholarly search server (OpenAlex + optional Scopus & Web of Science). See [`docs/bibliography-setup.md`](docs/bibliography-setup.md).
**Flonat-Papers MCP** — Zotero library management server (search, PDF extraction, semantic retrieval, BibTeX export). Lives in `packages/flonat-papers/` with bundled `bib-validate` and `bib-parse` skills.
**Council Mode** — Multi-model deliberation with 3 LLM providers, anonymised cross-review, and chairman synthesis. See [`docs/council-mode.md`](docs/council-mode.md).
## Workflows
| Command | What happens |
|---------|-------------|
| "Plan my day" | Reads context, queries vault, asks questions, creates Must Do / Should Do / Could Do plan |
| "Extract actions from my meeting with [name]" | Finds transcript, extracts tasks with full context, creates in vault |
| "Weekly review" | 4-part reflection: clear the decks, review, plan, project check |
| "What's overdue?" | Queries vault and summarises |
| "Proofread my paper" | 7-category academic check (report only) |
| "Validate my bibliography" | Cross-references `\cite{}` keys against `.bib` |
## Session Continuity
Each session builds on previous ones:
- `current-focus.md` — updated at session end with progress and next steps
- `log/` — timestamped session logs
- `log/plans/` — saved implementation plans
- `MEMORY.md` — accumulated `[LEARN]` tags (notation, citation, code, method, domain corrections)
The recovery protocol reads the latest plan, session log, and current focus to resume seamlessly.
## Project Structure
```
claude-research/
├── CLAUDE.md # Main instruction file (customise this)
├── README.md # This file
├── MEMORY.md # Accumulated knowledge (auto-populated)
├── .claude/
│ ├── agents/ # 6 specialised review agents
│ ├── rules/ # 9 auto-loaded policy rules
│ └── settings.json # Permissions, hooks, model config
├── skills/ # 38 slash commands
│ ├── shared/ # Shared utilities (palettes, scoring, rhetoric)
│ ├── proofread/ # Academic proofreading
│ ├── latex-autofix/ # LaTeX compilation + auto-fix
│ ├── literature/ # Literature search + synthesis
│ └── ... # See docs/skills.md for full list
├── hooks/ # 8 automated guardrails
├── .context/ # AI context library
│ ├── profile.md # Your identity and background
│ ├── current-focus.md # What you're working on NOW
│ ├── projects/ # Project metadata
│ ├── preferences/ # Workflow preferences
│ ├── workflows/ # Process guides (daily review, etc.)
│ └── resources/ # Reference data (journal rankings, etc.)
├── .scripts/ # CLI tools for vault task management
├── mcp-bibliography/ # Multi-source scholarly search (OpenAlex + Scopus + WoS)
├── packages/
│ ├── cli-council/ # Multi-model council via local CLI tools
│ ├── llm-council/ # Multi-model council via OpenRouter API
│ └── mcp-bibliography/ # mcp-bibliography
├── docs/ # Component documentation
├── log/ # Session logs (auto-created)
└── scripts/
└── setup.sh # Initial setup script
```
## Design Principles
1. **Lazy prompting** — Context files eliminate repetitive explanations
2. **Hybrid local + cloud** — Markdown (versioned) + Research Vault (dynamic)
3. **Question-driven** — AI asks questions before dumping lists
4. **Read-only audits** — Proofread, validate, review — never auto-edit source
5. **Session continuity** — Every session makes the next one better
6. **Permission governance** — Global settings propagate automatically
## Requirements
| Tool | Why you need it | macOS | Linux | Windows |
|------|----------------|-------|-------|---------|
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | The AI engine — runs skills, agents, hooks | `curl -fsSL https://claude.ai/install.sh \| bash` | same | `winget install Anthropic.ClaudeCode` |
| [Python 3.11+](https://www.python.org/) | Hooks and MCP servers | `brew install python@3.12` | `apt install python3.12` | `winget install Python.Python.3.12` |
| [uv](https://docs.astral.sh/uv/) | Fast Python package manager — isolates dependencies, replaces `pip` | `brew install uv` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` | `winget install astral-sh.uv` |
| [Git](https://git-scm.com/) | Version control | Included | `apt install git` | `winget install Git.Git` |
| [TeX Live](https://tug.org/texlive/) | LaTeX compilation (`/proofread`, `/latex-autofix`) | `brew install --cask mactex` | `apt install texlive-full` | [install guide](https://tug.org/texlive/windows.html) |
Also available as a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropics.claude-code), [JetBrains plugin](https://plugins.jetbrains.com/plugin/27189-claude-code), [web app](https://claude.ai/code), or [desktop app](https://claude.ai/download).
See [`docs/getting-started.md`](docs/getting-started.md) for Fedora/Arch commands, Windows-specific setup, Python version guidance, and troubleshooting.
## Credits
This infrastructure draws on design patterns from several open-source workflows.
### Academic Researchers
- **[Scott Cunningham](https://github.com/scunning1975/MixtapeTools)** (MixtapeTools) — session logs, rhetoric-driven presentations, "health inspector" model for code audits, cross-language replication, author/reviewer separation
- **[Pedro Sant'Anna](https://github.com/pedrohcgs/claude-code-my-workflow)** — specialist agents, plan-first protocol, quality gates, critic-fixer loops, [LEARN] tags
- **[Jared Black](https://github.com/Black-JL/Research-Project-Flow)** — "break the glass" protocol for infrastructure changes, data sensitivity rules, reproducible project templates
- **[Antonio Mele](https://github.com/meleantonio/awesome-econ-ai-stuff)** — curated AI-for-economists resources, programmatic Claude Code controller, scientific skills reference
- **[Hugo Sant'Anna](https://github.com/hsantanna88/clo-author)** (CLO-Author) — open-source Claude Code workflow for applied econometrics, agents, 29 slash commands
- **[Chris Blattman](https://github.com/chrisblattman/claudeblattman)** — academic AI workflows guide, non-developer-friendly skill and agent patterns
### General Resources
- **[Andrej Karpathy](https://github.com/karpathy/llm-council)** — multi-model council with peer review and synthesis (our fork: [llm-council](https://github.com/user/llm-council), [cli-council](https://github.com/user/cli-council))
- **[rtk-ai](https://github.com/rtk-ai/rtk)** — RTK rewrite hook for 60–90% token savings on CLI output
- **[NPC Worldwide](https://github.com/npc-worldwide/npcsh)** (npcsh) — knowledge graph sleep/dream cycles, inspiring the memory consolidation skill
- **[Boris Cherny](https://github.com/AugmendTech/ChernyCode)** (ChernyCode) — AI coding assistant configuration patterns
- **[Jim Christian](https://github.com/aplaceforallmystuff)** (aplaceforallmystuff) — creation-guard pre-flight checks, lessons-learned retrospective, ecosystem health diagnostics
- **[blader](https://github.com/blader/Claudeception)** (Claudeception) — skill description optimization, post-match action table, solution pattern for skill creation, learning nudge hook
- **[Anthropic](https://github.com/anthropics/claude-code)** — Claude Code platform, 8 adopted skill patterns (docx, xlsx, pptx, pdf, frontend-design, mcp-builder, webapp-testing, skill-creator)
System created January 2026.
## Star History
[](https://star-history.com/#flonat/claude-research&Date)
## License
MIT