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
to replace legacy home-directory links safely and verify the new managed-copy
installation before removing any backup.

Made by a humble PhD student. 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.

Installation

Quick Install (npm)

npx flonat-research

This downloads the package and runs the managed-copy installer for both clients.

Full Install (recommended for customisation)

macOS / Linux

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

Windows (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 .context/profile.md, CLAUDE.md, and workflows to match your research.

Update

# macOS/Linux: pull latest, then reconcile managed copies
git pull && ./scripts/setup.sh --client both --update

# Windows (PowerShell):
git pull; .\scripts\setup.ps1 -Client both -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

What's Included

Architecture

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.

Components

Context Library (.context/) — Markdown files that give compatible AI
clients durable context about you, your projects, and your workflows.

Skills (skills/) — Slash commands invoked with /<skill-name> or natural language.

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

See docs/agents.md for detailed descriptions.

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

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 (~/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

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 — 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 — a terminal multiplexer. Run one named tmux session per project, each with claude inside. The work keeps running when you disconnect; reattach later with tmux attach.
• mosh — 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:

# on the always-on host — one persistent session per project:
tmux new -s myproject
cd ~/path/to/project && claude       # work as normal; 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. Claude Code stores each session transcript under ~/.claude/projects/<cwd-as-key>/ on the machine it ran on, keyed by the working directory's absolute path. So a resumable session does not automatically follow a Dropbox/Syncthing-synced folder to another machine — the transcript isn't in the folder, and the path key differs per machine. The clean pattern is to keep persistent sessions on the one always-on host and reach it remotely, rather than trying to --resume the same session on two machines. For deliberate cross-machine handoff, write a short state note into the synced project folder for the next session to read.

Project Structure

flonat-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/                      # 109 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/                       # 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/
│   ├── 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

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

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.

Stars

License

MIT