https://github.com/flonat/flonat-research
Shareable Claude Code + Codex infrastructure for PhD researchers — skills, agents, hooks, and rules for academic workflows
https://github.com/flonat/flonat-research
academic-research ai-tools claude claude-code codex latex phd research-workflow
Last synced: 2 days ago
JSON representation
Shareable Claude Code + Codex infrastructure for PhD researchers — skills, agents, hooks, and rules for academic workflows
- Host: GitHub
- URL: https://github.com/flonat/flonat-research
- Owner: flonat
- License: mit
- Created: 2026-02-20T10:45:59.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-07-15T11:28:41.000Z (3 days ago)
- Last Synced: 2026-07-15T12:27:56.232Z (3 days ago)
- Topics: academic-research, ai-tools, claude, claude-code, codex, latex, phd, research-workflow
- Language: Python
- Homepage:
- Size: 6.16 MB
- Stars: 118
- Watchers: 0
- Forks: 21
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# flonat-research: a dual-client research framework
> **Repository transition complete:** this project moved from the Claude-only
> `claude-research` name to the client-neutral `flonat-research` framework for
> both Claude Code and Codex. Existing checkouts remain supported during the
> migration; use the [transition guide](docs/transitioning-to-flonat-research.md)
> to replace legacy home-directory links safely and verify the new managed-copy
> installation before removing any backup.
A client-neutral research infrastructure with skills, agents, rules,
files-first context, and optional Claude hooks. It is
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** with Claude Code, Codex, or both. Both
clients read the same project files; adapters expose only the skills and agents
their client can execute accurately.
This public repository and `flonat-research-friends` are alternative managed
distributions, not layers to install on top of each other. Both own overlapping
paths under `~/.claude/`, `~/.agents/`, and `~/.codex/`; choose one checkout as
the installer source on a machine. The private Task Management control plane is
a separate upstream and is not required for the public installation.
See [Building a Client-Neutral AI Control Plane](docs/dual-client-ai-control-plane.md)
for the architecture, trade-offs, staged adoption process, and implementation
checklist behind the dual-client design.
The generated [AI surface availability table](docs/availability.md) shows
exactly which skills, agents, rules, hooks, MCP registrations, and CLIs are
available to each client and why an exclusion exists.
[](https://www.npmjs.com/package/flonat-research)
[](https://github.com/flonat/flonat-research/releases)
## Installation
### Install from the repository
The currently published npm release (`0.2.1`) predates the dual-client
managed-copy installer. Until `0.3.0` is published, use the repository install
below rather than `npx flonat-research`.
#### macOS / Linux
```bash
git clone https://github.com/flonat/flonat-research.git flonat-research
cd flonat-research
./scripts/setup.sh --client both
```
#### Windows (PowerShell)
```powershell
git clone https://github.com/flonat/flonat-research.git flonat-research
cd flonat-research
.\scripts\setup.ps1 -Client both
```
The git clone gives you a local copy you can fully customise. Edit the neutral
`AI.md`, `.context/profile.md`, and workflows; `CLAUDE.md` and `AGENTS.md` are
generated client entry points.
### Update
```bash
# macOS/Linux: pull latest, then reconcile managed copies
git pull --ff-only && ./scripts/setup.sh --client both
# Windows (PowerShell):
git pull --ff-only; .\scripts\setup.ps1 -Client both
```
Then customise `AI.md`, `.context/profile.md`, and `.context/current-focus.md`
with your details. See [`docs/getting-started.md`](docs/getting-started.md) for
the full guide (including Windows-specific setup and troubleshooting).
### Bundled package
| Package | Install | Description |
|---------|---------|-------------|
| [`council-api`](https://github.com/flonat/council-api) | Clone and use `uv` | Multi-model council via OpenRouter-compatible APIs |
## What's Included
| Component | Count | Description |
|-----------|-------|-------------|
| **Skills** | 93 | Portable workflows for common tasks (`proofread`, `latex`, `literature`, etc.) |
| **Agents** | 15 | Specialised reviewers (peer review, referee 2, paper critic, domain review, fixer) |
| **Hooks** | 3 | Standalone optional Claude safeguards; shared context does not depend on them |
| **Rules** | 18 | Always-on policies (plan before implementing, scope discipline, etc.) |
| **Context library** | — | Structured files shared by Claude Code and Codex across sessions |
| **Bundled package source** | 1 | `council-api`; install separately with `uv` when required |
| **Optional integrations** | — | Notion, bibliography CLIs, MCP adapters, and provider CLIs are not installed — [boundary](docs/scripts.md) |
## Architecture
```text
AI.md + .context/ + MEMORY.md + skills/ + agents/ + rules/
|
capability contract
/ \
Claude Code adapter Codex adapter
optional hooks and MCPs CLI fallbacks
\ /
managed-copy installer
```
Both clients use the same durable files. MCP and hook integrations are
client-specific adapters, not the source of context.
### Distribution and privacy
This repository is a curated public distribution, not a mirror of its richer
upstream workspace. `config/ai-contracts.yaml` records every included asset and
the clients it supports. Before publication, generated content is anonymised
and a fail-closed guard rejects personal identity, affiliations, credential
material, machine-specific paths, internal repository references, and
secret-bearing filenames. Passing that guard establishes the configured
disclosure boundary; it does not make excluded workflows part of the public
product.
## Components
**Context Library** (`.context/`) — Markdown files that give compatible AI
clients durable context about you, your projects, and your workflows.
**Skills** (`skills/`) — Client-neutral workflows invoked with
`/` in Claude, `$` in Codex, or natural language.
93 skills available. Key examples: `proofread`, `latex`, `pre-submission-report`, and more. Use `/name` in Claude, `$name` in Codex, or natural language; see [`docs/availability.md`](docs/availability.md).
See [`docs/skills.md`](docs/skills.md) for the full catalogue.
**Agents** (`agents/`) — Neutral specialised reviewer definitions rendered to
Claude Markdown and Codex TOML adapters.
| Agent | Use case |
|-------|----------|
| `artifact-coherence-auditor` | Audits coherence between paper prose and replication outputs — catches\ \ hallucinated results, missing scripts, mismatched numbers, and unverifiable claims.\ \ Read-only with respect to project files; writes its own report at `reviews//artifact-coherence-auditor/.md`.\ \ Complements code-paper-auditor (which maps numbers to code) by checking whether\ \ the replication package *actually produces* what the paper 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` | Rigorous adversarial reviewer for papers, manuscripts, research designs, code, and arguments |
| `reproducibility-auditor` | Reviews research workflows for reproducibility gaps — hidden dependencies,\ \ absolute paths, undocumented prerequisites, environment assumptions, and output\ \ traceability |
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 |
| `handoff-read.sh` | SessionStart | surface the shared project handoff when it targets Claude |
| `promise-checker.sh` | Session stop | catches "performative compliance": Claude says it remembered/noted/saved |
See [`docs/hooks.md`](docs/hooks.md) for full documentation.
**Rules** (`rules/`) — Canonical policies rendered into client-appropriate
guidance. See [`docs/rules.md`](docs/rules.md).
**External task and research systems** — Optional vaults, Notion workspaces,
and task CLIs can enrich workflows, but none is bundled or registered by this
repository. Files-first project context remains the baseline.
**Scholarly search** — Compatible bibliography CLIs or a Claude MCP adapter may
be configured separately. A personal Paperpile/RefPile setup is likewise an
external service, not part of a successful base install. See
[`docs/bibliography-setup.md`](docs/bibliography-setup.md).
**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.
## Remote & Persistent Sessions
You don't have to run Claude Code on your laptop. A productive setup is to run it on an **always-on machine** — a headless Mac mini, an old desktop, or a small VPS — and reach it from anywhere. Long tasks keep running, sessions survive network drops, and you can start work at your desk and pick it up later from a phone or a train.
The stack:
- **[Tailscale](https://tailscale.com)** — a zero-config WireGuard VPN. Reach the host by a stable name from any device, without opening ports or exposing anything to the public internet.
- **[tmux](https://github.com/tmux/tmux)** — a terminal multiplexer. Run one named tmux session per project, with Claude Code or Codex inside. The work keeps running when you disconnect; reattach later with `tmux attach`.
- **[mosh](https://mosh.org)** — a roaming-friendly SSH replacement. It survives IP changes, laptop sleep, and high-latency mobile links, so a flaky connection never kills your shell. Pair it with tmux: mosh keeps the *connection* alive, tmux keeps the *work* alive.
Typical loop:
```bash
# on the always-on host — one persistent session per project:
tmux new -s myproject
cd ~/path/to/project # start Claude Code or Codex; detach with Ctrl-b then d
# from any device, over Tailscale:
mosh my-host
tmux attach -t myproject # right back where you left off
```
**One caveat worth knowing.** Client transcripts and resume state are local to
the machine that ran them and do not automatically follow a synced project.
Keep durable context in `AI.md`, `MEMORY.md`, `.context/`, and
`.context/ai-handoff.md`. A persistent tmux session can stay on an always-on
host; a deliberate cross-machine or cross-client transfer should use the
handoff file rather than depending on either client's transcript history.
## Project Structure
```
flonat-research/
├── AI.md # Neutral guidance (customise this)
├── CLAUDE.md # Generated Claude Code adapter
├── AGENTS.md # Generated Codex adapter
├── README.md # This file
├── MEMORY.md # Accumulated knowledge (auto-populated)
├── agents/ # 15 neutral agent definitions
├── rules/ # 18 canonical policy rules
├── .claude/ # Generated Claude adapters
│ ├── agents/
│ ├── commands/
│ ├── rules/
│ └── settings.json
├── .codex/
│ └── agents/ # Codex-compatible agent adapters
├── config/
│ ├── ai-contracts.yaml # Explicit client/capability policy
│ └── install-manifest.json # Managed-copy installation plan
├── skills/ # 93 client-neutral workflows
│ ├── shared/ # Shared utilities (palettes, scoring, rhetoric)
│ ├── proofread/ # Academic proofreading
│ ├── latex/ # LaTeX compilation and diagnostics
│ ├── literature/ # Literature search + synthesis
│ └── ... # See docs/skills.md for full list
├── hooks/ # 3 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.)
├── packages/
│ └── council-api/ # Multi-model council via OpenRouter API
├── docs/ # Component documentation
├── log/ # Session logs (auto-created)
└── scripts/
├── install.py # Content-addressed managed-copy installer
├── setup.sh # macOS/Linux launcher
└── setup.ps1 # Windows PowerShell launcher
```
## 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) | Optional client with hooks and MCP support | `curl -fsSL https://claude.ai/install.sh \| bash` | same | `winget install Anthropic.ClaudeCode` |
| [Codex](https://developers.openai.com/codex/) | Optional client using AGENTS.md, compatible skills, agents, and CLIs | See official installer | See official installer | See official installer |
| [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` |
| [Node.js 18+](https://nodejs.org/) | Optional npm launcher after the `0.3.0` release | `brew install node` | Use your distribution package | `winget install OpenJS.NodeJS.LTS` |
| [TeX Live](https://tug.org/texlive/) | LaTeX compilation (`proofread`, `latex`) | `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/council-api)** — multi-model council with peer review and synthesis (public derivative: [council-api](https://github.com/flonat/council-api))
- **[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.
## Stars
[](https://star-history.com/#flonat/flonat-research&Date)
## License
MIT