<!-- Governed by: skills/shared/project-documentation.md -->

# 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.

[![npm version](https://img.shields.io/npm/v/flonat-research)](https://www.npmjs.com/package/flonat-research)
[![GitHub release](https://img.shields.io/github/v/release/flonat/claude-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-TABLE:START -->
<!-- auto-generated by generate-public-docs.py — do not edit manually -->
| Component | Count | Description |
|-----------|-------|-------------|
| **Skills** | 61 | 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](docs/notion-setup.md) |
| **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** | — | Notion task management from the terminal — [docs](docs/components/scripts.md) |
<!-- COMPONENT-TABLE:END -->

## Architecture

<!-- ARCHITECTURE:START -->
<!-- synced from private README — do not edit manually -->
```
┌──────────────────────────────────────────────────────────────┐
│  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.
<!-- ARCHITECTURE:END -->

## 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.
<!-- SKILLS-SUMMARY:START -->
<!-- auto-generated — do not edit manually -->
61 skills available. Key examples: `/proofread`, `/latex-autofix`, `/literature`, `/bib-validate`, `/code-review`, `/init-project-research`, and more.
<!-- SKILLS-SUMMARY:END -->
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.

<!-- AGENTS-TABLE:START -->
| 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 |

<!-- AGENTS-TABLE:END -->

See [`docs/agents.md`](docs/agents.md) for detailed descriptions.

**Hooks** (`hooks/`) — Automated guardrails that run at specific points in a session.

<!-- HOOKS-TABLE:START -->
| 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 |

<!-- HOOKS-TABLE:END -->

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

<!-- WORKFLOWS:START -->
<!-- synced from private README — do not edit manually -->
| 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` |
<!-- WORKFLOWS:END -->

## Session Continuity

<!-- SESSION-CONTINUITY:START -->
<!-- synced from private README — do not edit manually -->
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.
<!-- SESSION-CONTINUITY:END -->

## Project Structure

<!-- FILE-TREE:START -->
```
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/                      # 61 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
```
<!-- FILE-TREE:END -->

## Design Principles

<!-- DESIGN-PRINCIPLES:START -->
<!-- synced from private README — do not edit manually -->
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
<!-- DESIGN-PRINCIPLES:END -->

## 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

<!-- CREDITS:START -->
<!-- synced from private README — do not edit manually -->
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/council-api)** — multi-model council with peer review and synthesis (our fork: [council-api](https://github.com/user/council-api), [council-cli](https://github.com/user/council-cli))
- **[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) — skill-preflight pre-flight checks, postmortem 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.
<!-- CREDITS:END -->

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=flonat/claude-research&type=Date)](https://star-history.com/#flonat/claude-research&Date)

## License

MIT
