flonat-research

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	50	Slash commands for common tasks (/proofread, /latex-autofix, /literature, etc.)
Agents	15	Specialised reviewers (peer review, referee 2, paper critic, domain review, fixer)
Hooks	9	Automated guardrails (destructive git protection, context monitoring, etc.)
Rules	18	Always-on policies (plan before implementing, scope discipline, etc.)
Context library	—	Structured files that give Claude persistent memory across sessions
Notion integration	—	Task management and research pipeline tracking — setup guide
Bibliography MCP	—	Multi-source scholarly search (OpenAlex + Scopus + WoS) — setup guide
Council mode	—	Multi-model deliberation (3 reviewers + synthesis) — setup guide
CLI tools	—	Notion 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.

50 skills available. Key examples: /proofread, /literature, /bib-validate, /init-project-research, /pre-submission-report, 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
artifact-coherence-auditor	Audits coherence between paper prose and replication outputs — catches hallucinated results, missing scripts, mismatched numbers, and unverifiable claims
blindspot	Peripheral vision audit for empirical output
claim-verify	Verify that cited claims in a paper accurately represent what the source papers actually say
code-paper-auditor	Use this agent when you need to verify code-paper consistency — mapping every quantitative claim in a paper to its source code and output files
code-review	Multi-persona orchestrator for adversarial review of R, Python, Julia, or Stata research scripts
codex-research	Code review and research agent that delegates to OpenAI Codex CLI in headless mode
domain-reviewer	Research-focused substantive correctness agent
fatal-error-check	Fast pre-review check for fatal errors in LaTeX papers
fixer	Generic fix implementer for any critic report
gemini-research	Web research agent that delegates to Gemini CLI in headless mode
paper-critic	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
reproducibility-auditor	Reviews research workflows for reproducibility gaps — hidden dependencies, absolute paths, undocumented prerequisites, environment assumptions, and output traceability

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
handoff-read.sh	SessionStart	if handoff.md exists in cwd, read it into additionalContext
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/                  # 15 specialised review agents
│   ├── rules/                   # 18 auto-loaded policy rules
│   └── settings.json            # Permissions, hooks, model config
├── skills/                      # 50 slash commands
│   ├── shared/                  # Shared utilities (palettes, scoring, rhetoric)
│   ├── proofread/               # Academic proofreading
│   ├── latex-autofix/           # LaTeX compilation + auto-fix
│   ├── literature/              # Literature search + synthesis
│   └── ...                      # See docs/components/skills.md for full list
├── hooks/                       # 9 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 Notion task management
├── packages/
│   ├── cli-council/             # cli-council
│   ├── council-api/             # Multi-model council via OpenRouter API
│   ├── council-cli/             # Multi-model council via local CLI tools
│   ├── mcp-scholarly/             # mcp-scholarly
│   └── scholarly/             # Multi-source scholarly search MCP (OpenAlex + Scopus + WoS)
├── docs/                        # Component documentation
├── log/                         # Session logs (auto-created)
└── scripts/
    └── setup.sh                 # Initial setup script

Design Principles

• Lazy prompting — Context files eliminate repetitive explanations
• Hybrid local + cloud — Markdown (versioned) + Research Vault (dynamic)
• Question-driven — AI asks questions before dumping lists
• Read-only audits — Proofread, validate, review — never auto-edit source
• Session continuity — Every session makes the next one better
• 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 python@3.12	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: council-api, council-cli)
• 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) — skill-preflight pre-flight checks, postmortem 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