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.

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 for the architecture, trade-offs, staged adoption process, and implementation checklist behind the dual-client design.

The generated AI surface availability table shows exactly which skills, agents, rules, hooks, MCP registrations, and CLIs are available to each client and why an exclusion exists.

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

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 the neutral AI.md, .context/profile.md, and workflows; CLAUDE.md and AGENTS.md are generated client entry points.

Update

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

Bundled package

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.

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 /<skill-name> in Claude, $<skill-name> 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.

See docs/skills.md for the full catalogue.

Agents (agents/) — Neutral specialised reviewer definitions rendered to Claude Markdown and Codex TOML adapters.

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 (rules/) — Canonical policies rendered into client-appropriate guidance. See 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.

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, with Claude Code or Codex 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                 # 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

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 (public derivative: council-api)
• 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