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, VS Code, JetBrains IDEs, the web, or the desktop app — all share the same skills, agents, and rules.

Installation

Quick Install (npm)

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

git clone https://github.com/flonat/claude-research.git
cd claude-research
./scripts/setup.sh

Windows (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

# 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 for the full guide (includes Windows-specific setup, Python install, and troubleshooting).

Related Packages

| Package | Install | Description | |---------|---------|-------------| | llm-council | pip install llm-council | Multi-model council via OpenRouter API | | 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 | | Council mode | — | Multi-model deliberation (3 reviewers + synthesis) — setup guide | | CLI tools | — | Vault task management from the terminal — docs |

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 /<skill-name> or natural language.

38 skills available. Key examples: /proofread, /latex-autofix, /literature, /bib-validate, /code-review, /session-recap, and more.

See 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 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 for full documentation.

Rules (.claude/rules/) — Always-on policies enforcing good research practices. See 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.

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.

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 | The AI engine — runs skills, agents, hooks | curl -fsSL https://claude.ai/install.sh \| bash | same | winget install Anthropic.ClaudeCode | | Python 3.11+ | Hooks and MCP servers | brew install [email protected] | apt install python3.12 | winget install Python.Python.3.12 | | 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 | Version control | Included | apt install git | winget install Git.Git | | TeX Live | LaTeX compilation (/proofread, /latex-autofix) | brew install --cask mactex | apt install texlive-full | install guide |

Also available as a VS Code extension, JetBrains plugin, web app, or desktop app.

See 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 (MixtapeTools) — session logs, rhetoric-driven presentations, "health inspector" model for code audits, cross-language replication, author/reviewer separation
• Pedro Sant'Anna — specialist agents, plan-first protocol, quality gates, critic-fixer loops, [LEARN] tags
• Jared Black — "break the glass" protocol for infrastructure changes, data sensitivity rules, reproducible project templates
• Antonio Mele — curated AI-for-economists resources, programmatic Claude Code controller, scientific skills reference
• Hugo Sant'Anna (CLO-Author) — open-source Claude Code workflow for applied econometrics, agents, 29 slash commands
• Chris Blattman — academic AI workflows guide, non-developer-friendly skill and agent patterns

General Resources

• Andrej Karpathy — multi-model council with peer review and synthesis (our fork: llm-council, cli-council)
• rtk-ai — RTK rewrite hook for 60–90% token savings on CLI output
• NPC Worldwide (npcsh) — knowledge graph sleep/dream cycles, inspiring the memory consolidation skill
• Boris Cherny (ChernyCode) — AI coding assistant configuration patterns
• Jim Christian (aplaceforallmystuff) — creation-guard pre-flight checks, lessons-learned retrospective, ecosystem health diagnostics
• blader (Claudeception) — skill description optimization, post-match action table, solution pattern for skill creation, learning nudge hook
• Anthropic — 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

License

MIT