neuroflow

<div align="center"> <img src="logo-full.svg" alt="neuroflow" width="80%" /> <h1>neuroflow</h1> <p><strong>The agentic operating system for neuroscience research.</strong></p> <p> <a href="#whats-new">What's new</a> · <a href="#why-neuroflow">Why</a> · <a href="#commands">Commands</a> · <a href="#skills">Skills</a> · <a href="#agents">Agents</a> · <a href="#hooks">Hooks</a> · <a href="#project-memory">Project memory</a> · <a href="#installation">Install</a> · <a href="#contributing">Contribute</a> </p> </div>

What's new in 0.2.20

• •autoresearch rebuilt around a per-loop wiki — `neuroflow:autoresearch` is now a single managing agent (no worker/evaluator fan-out) whose brain is a scoped wiki/: it reads the wiki before every move and records every attempt — wins and failures — after. That's what lets an infinite single-agent loop compound instead of going in circles.
• •Loop lives next to the artifact — folder named {name}_autoresearch/ beside the tracked files (overridable), with a pointer registry in .neuroflow/{phase}/autoresearch-loops.md. Multiple loops per phase now work.
• •Configurable depth + human steering — agent-decided branching, literature search when stuck, self vs fresh-eval, and a report.md with a non-blocking Q&A channel (answer in-session or via answers.md); the dashboard renders the report and open questions next to the trend charts.

What's new in 0.2.19

• •New [`neuroflow:bids`](skills/bids/SKILL.md) skill — comprehensive Brain Imaging Data Structure reference: full folder hierarchy for all modalities (MRI/EEG/MEG/iEEG/PET/DWI/NIRS/motion), entity ordering rules, JSON sidecar fields, derivatives structure, and tool guides for bids-validator, pybids, MNE-BIDS, fMRIPrep, and dcm2niix/HeuDiConv conversion pipelines
• •BIDS integrated into data phases — `phase-data`, `phase-data-preprocess`, and `phase-data-analyze` now reference the BIDS skill; invoked automatically when structure, validation, or loading is relevant
• •`mind.js` updated — sk-bids node added to the pipeline cluster, linked to c-data

What's new in 0.2.18

• •Global `~/.neuroflow/` structure — flowie and hive caches move from per-project .neuroflow/flowie/ to a single global ~/.neuroflow/flowie/ (one clone per user); hive caches at ~/.neuroflow/hives/{org-repo}/; integrations.json lives in flowie globally; team.md and linked_flows.md removed from project structure; collaborators now in project_config.md
• •Global auto-sync on session start — `neuroflow-core` pulls ~/.neuroflow/flowie/ and all hive caches at the start of every command session; always start with fresh knowledge
• •Cross-wiki ambient search — ambient pre-query now searches all initialized wikis in parallel (~/.neuroflow/flowie/wiki/, ~/.neuroflow/hives/*/wiki/, .neuroflow/wiki/); answers cite source wiki by level
• •Wiki crystallization hook — `neuroflow-core` detects decisions/hypotheses/insights at end of every command and offers wiki ingest with smart level routing; per-command wiki nudges removed from /data-analyze, /paper, /notes
• •Docs + consistency fixes — missing docs mirrors created, dead agent rows removed, mind.js updated, version badge fixed

What's new in 0.2.16

• •`flowie_profiles` list — replaces the redundant flowie_project + hive_member scalar fields in project_config.md with a single extensible flowie_profiles: list; each entry has handle and repo; first entry = project owner, additional entries added when collaborators run /flowie --link; backward-compatible (one entry = old behavior)
• •Global user identity config (`/setup`) — new Step 6 saves your GitHub username to ~/.neuroflow/user.yaml; /neuroflow Step 1b reads it to pre-fill the flowie handle so you never have to enter it again on a new project
• •Sentinel migration guard — sentinel now flags legacy flowie_project: and hive_member: scalar fields and suggests running /neuroflow to migrate

What's new in 0.2.15

• •[`/meeting`](commands/meeting.md) — first-class meeting command: schedule meetings from recurring templates, prepare agendas with active task context, send Google Calendar invites, and auto-create tasks from action items at project/flowie/hive level
• •3-tier task model (`/flowie --tasks --level`) — tasks now exist at three levels: personal flowie (private), project (git-tracked, shared with collaborators), and hive (team-wide); kanban rendering mandatory on all displays
• •`.neuroflow/flowie/` gitignored — flowie is personal and excluded from shared project repos; each collaborator keeps their own private flowie; collaborator join flow documented in `phase-hive`

What's new in 0.2.14

• •Personal wiki (`/flowie --wiki-*`) — Karpathy-style LLM-maintained knowledge base inside your flowie repo; ingest sources, query your accumulated knowledge, lint for orphan/stale pages, and build a compounding synthesis; every page is tagged to flowie projects; integrates with /notes, /ideation, /data-analyze, and /paper via closing prompts
• •New [`neuroflow:wiki`](skills/wiki/SKILL.md) skill — full wiki behavior: page types and frontmatter schema, ingest/query/lint/add/schema workflows, project tagging (always prompted), ideas.md sync, profile.md evolution, fails integration for method pages, and sentinel health checks

What's new in 0.2.13

• •[`/autoresearch`](commands/autoresearch.md) — infinite improvement loop for any research artifact: point it at any file(s), and a single managing agent runs indefinitely (one focused change per iteration, keep or revert, never stops until interrupted), using a per-loop wiki as its memory; the loop folder lives next to the artifact; optional branching, literature search, and a human report.md with a non-blocking Q&A channel; live dashboard at localhost:8765 rendering the report and trend charts; triggers via /autoresearch or any phase command with the word autoresearch in the prompt
• •Agent cleanup — removed 16 unused phase agent files that were never spawned by commands; commands follow phase skills directly; the 8 agents that are actually spawned (paper-writer, paper-critic, poster-critic, literature-review, scholar, sentinel, sentinel-dev, flowie) remain unchanged

What's new in 0.2.12

• •Notes → flowie sync (`/notes`) — after every notes session, Claude offers to copy the formatted note to .neuroflow/flowie/notes/ for GitHub sync (default: yes); a local config.json stores per-project defaults for type, speaker, and project relation
• •Daily wellbeing tracking (`/flowie --assess`) — opt-in daily self-assessment for anxiety, energy, and happiness on a 1–10 scale (5=neutral); stored in flowie/wellbeing/; Claude prompts on any sync operation if today's entry is missing; enabled via /flowie --init or /flowie --assess

What's new in 0.2.11

• •Removed broken `pubmed-mcp-server` — replaced by paper-search-mcp-nodejs (the biorxiv server), which already includes search_pubmed and requires no credentials; PUBMED_EMAIL is no longer needed

What's new in 0.2.10

• •Global device config (`/setup`) — credentials can now be saved to ~/.neuroflow/integrations.json (global, shared by all projects on the machine) instead of per-project; per-project still takes precedence and overrides global; Step 0 of the wizard asks which scope to use
• •Windows support in setup — `/setup`, `neuroflow:setup`, and the e-INFRA reference now include Windows-specific paths and PowerShell env var syntax throughout
• •Proxy model-name fix (`proxy.mjs`) — the proxy now restores the original claude-* model name in every response chunk, preventing Claude Code's "unexpected model" error when using custom LLM providers; `flowie` now enforces that integrations.json is gitignored in the flowie sync repo

What's new in 0.2.8

• •Session logging overhaul — removed the noisy [tool] PostToolUse hook; Claude now owns all session logging and writes entries broadly (most actions, not just milestones); neuroflow-core logging rules are now marked MUST and non-negotiable
• •flow.md purity rule — flow.md is now explicitly a pure index table; narrative content, figure maps, and cross-references must go in dedicated .md files in the phase subfolder
• •mind.js consistency check — sentinel-dev Check 11 audits that every skill, command, and agent has a node in docs/javascripts/mind.js; missing humanizer node added; neuroflow-develop release workflow now flags this as a blocking step
• •[`scholar`](agents/scholar.md) sequential search + batch downloads — searches now run PubMed → bioRxiv → fallbacks one at a time (was simultaneous); paper downloads processed in batches of 2 to reduce concurrency pressure and make failures easier to diagnose

What's new in 0.2.6

• •Scholar agent: download reporting fixes — .pdf/.txt files now correctly marked ⏭️ already downloaded; .md-only stubs re-attempt download unless reason: unavailable; ✅ downloaded is gated on a confirmed .pdf or .txt write; download summary counter now labelled ✅ [n] downloaded (PDF/text) with a new ⏭️ [n] unavailable (metadata cached) bucket
• •Scholar agent: search coverage fixes — Semantic Scholar 429 rate-limit triggers a 3 s wait + retry then falls back to CrossRef/arXiv with a visible warning; PubMed query-overlap detection auto-generates 2–3 diversified queries when < 15 unique results or > 80% overlap; arXiv keyword fallback added when bioRxiv returns 0 results; mandatory coverage summary table printed before results, with any ⚠️/❌ row also surfaced as an inline warning block

What's new in 0.2.5

• •[`/poster`](commands/poster.md) — generate a LaTeX conference poster from project memory; five templates (A0/A1 portrait, A0 landscape, 90×120 cm, 48×36 in); QR code support via the qrcode package; iterative poster-critic review loop (up to 3 cycles) before the .tex file is saved
• •New [`poster-critic`](agents/poster-critic.md) agent — audits every poster draft across five areas (content accuracy, visual balance, scientific communication, QR code, LaTeX correctness); returns [STATUS: APPROVED] or [STATUS: REJECTED] with specific, actionable feedback; never rewrites content
• •New [`neuroflow:phase-poster`](skills/phase-poster/SKILL.md) skill — full LaTeX template catalogue with embedded QR code blocks, template selection guide, content extraction logic, and compilation instructions

What's new in 0.2.4

• •Sentinel Check 3b — sentinel now validates that .claude-plugin/marketplace.json version matches plugin.json; the marketplace version was silently stuck at 0.1.0 with no existing check to catch it
• •Hardened release checklist — both `neuroflow-developer.md` and `neuroflow-develop/SKILL.md` now require docs/changelog.md entry, one-liner review, and marketplace.json bump on every release; SKILL.md synced to match neuroflow-developer.md (was missing mkdocs.yml and sentinel-dev steps)
• •Internal consistency fixes — dead neuroflow:scholar skill ref in `phase-paper` corrected; `/hive` docs page created; `neuroflow-developer.md` and `orchestrator` synced to full repo structure (22 phases, all 4 workflows, scripts/automation/)

What's new in 0.2.3

• •PDF download resume and retry logic — the scholar agent now checks which papers are already present in .neuroflow/ideation/papers/ before downloading; interrupted runs are safely retried without duplicating work
• •Four-source fallback chain — downloads now try Unpaywall → PubMed Central → bioRxiv direct → journal OA page in sequence; each source is attempted before moving to the next
• •Per-paper retry — if all four sources fail, the agent waits 2 seconds and retries the full chain once more before marking a paper as unavailable
• •`⚠️ failed` vs `❌ unavailable` distinction — transient network failures are now reported separately from confirmed no-OA-copy papers, with a named list of papers to retry and instructions to re-run the agent to resume
• •Removed `/paper-write` and `/paper-review` — superseded by `/paper`, which covers the full write→critique loop; nothing is lost
• •New [`/review`](commands/review.md) command — for when YOU are the reviewer reading a colleague's paper; produces a structured referee report calibrated to the target journal by delegating to neuroflow:review-neuro
• •New [`review`](agents/review.md) agent and [`neuroflow:phase-review`](skills/phase-review/SKILL.md) skill — autonomous peer reviewer agent and phase orientation skill for the referee workflow

What's new in 0.2.2

• •Unified [`/paper`](commands/paper.md) command — combines paper-write and paper-review into a single command and phase; every section draft goes through a brutal paper-writer → paper-critic loop (up to 3 iterations per section) before anything is saved; nothing reaches disk without critic approval or explicit user acceptance
• •New [`paper-writer`](agents/paper-writer.md) and [`paper-critic`](agents/paper-critic.md) agents — the writer drafts section-by-section from upstream project memory; the critic applies the full six-area neuroflow:review-neuro methodology to every draft with zero tolerance for overclaims, statistical errors, or underreported methods
• •New [`neuroflow:phase-paper`](skills/phase-paper/SKILL.md) skill — unified phase guidance covering journal recommendation, the write→critique loop protocol, critic standards, and output paths for the paper phase

What's new in 0.2.1

• •ASCII welcome logo in [`/neuroflow`](commands/neuroflow.md) — the main entry command now greets with a full ASCII logo for "neuroflow", the current version number, and the tagline agentic neuroscience research, from hypothesis to publication, followed by one of the three witty one-liners

What's new in 0.2.0

• •Auto-issue consent gate — auto-issue now checks auto_issue_reporting: in project_config.md before filing any issue; issues are only sent if the user explicitly opted in during project setup; missing or no value silently suppresses all automatic filing
• •Consent question in [`/neuroflow`](commands/neuroflow.md) — project setup now asks whether the user allows anonymous issue reporting to the developers and saves the answer as auto_issue_reporting: yes/no in project_config.md
• •Cognitive probe embedded on home page — simple static self-assessment block replaces the separate probe page

What's new in 0.1.9

• •Worker-critic agentic loop — new `orchestrator` and `critic` agents coordinate up to 3 revision cycles for any phase output; the orchestrator routes to the correct phase worker, the critic returns [STATUS: APPROVED] or [STATUS: REJECTED] with specific actionable feedback, and the loop halts cleanly with a logged critique if approval is not reached
• •New [`neuroflow:worker-critic`](skills/worker-critic/SKILL.md) skill — defines the full loop protocol, worker modes (Initial Draft / Revision), rubric construction, critic output format, and critic-log.md state tracking
• •Loop integrates with all 15 existing phase agents — the orchestrator auto-selects the right worker for the active phase from project_config.md, covering 18 phases (preregistration, finance, and slideshow share workers with ideation, grant-proposal, and write-report respectively)

What's new in 0.1.8

• •Target journal clarification in [`/neuroflow`](commands/neuroflow.md) — on startup, if paper-write or paper-review is the active phase or in recommended_phases and no target journal is set, neuroflow asks whether the user wants a recommendation. If yes: searches PubMed and bioRxiv via the scholar agent, ranks 3–5 candidate journals by scope alignment, paper type, OA requirements, length, and prestige vs. speed, then writes the chosen journal to project_config.md (and paper-write/flow.md if it already exists).
• •Journal recommendation guidance in `neuroflow:phase-paper-write` — new ## Journal recommendation section: same search-and-rank workflow available when the skill is invoked directly via /paper-write, with explicit recency (past 3 years) and recurrence (≥3 of top 20 results) thresholds.
• •[`/flowie`](commands/flowie.md) — personal research OS: link a private GitHub repository as a three-layer personal system — identity profile (stances, writing style, methodological preferences), a Kanban task board (tasks/ with configurable columns, --tasks --add/--move/--done/--archive), and a project registry (projects/ with ASCII phase timelines, --projects --add); supports --init, --sync, --link, --view, --identify, --tasks, and --projects modes; phase changes auto-sync to the project registry
• •[`neuroflow:phase-flowie`](skills/phase-flowie/SKILL.md) — phase skill covering how to read and apply the flowie profile in every other phase, write rules for ~/.neuroflow/flowie/, and a privacy-conscious GitHub sync protocol (always pull before push, diffs before applying, conflicts shown side by side)
• •[`flowie` agent](agents/flowie.md) — autonomous personalization agent that reads the user's profile at session start, surfaces active tasks for the current project, and shapes all assistance to their documented intellectual fingerprint; never exposes profile data in external-facing outputs
• •New fixed quote — added "I will jump to version 1.0.0 once I manage to publish the first paper" to the homepage quote bubbles
• •Two new fixed quotes added to the homepage hero — "We will probably be the first ones to understand the brain." and "When I said we, I meant you as well, are you in?" appended as adjacent entries in the `overrides/main.html` quotes rotation
• •[`/output`](commands/output.md) — renamed from /export to avoid conflict with Claude's built-in /export command (which exports conversations); functionality is identical; skill renamed to `neuroflow:phase-output`
• •New quote — added "Can you collect some brain data for me?" to the homepage quote carousel in `overrides/main.html`
• •[Cognitive Development Probe](docs/probe.html) — a self-contained interactive diagnostic: 7 neuroscience-inspired yes/no questions (prediction error, model update, uncertainty, decision monitoring, self-model, global integration, subjective experience); Q7 locked until Q1–Q6 are all YES; color-coded status indicators, "Cognitive Level" progress bar, reset button; includes a read-only Claude's honest self-assessment section where the model answers each question as of this version — no hedging, no performance
• •[`/grant-proposal`](commands/grant-proposal.md) dramatically improved — auto-discovers ideation outputs, fetches funder calls from URLs, supports NIH/ERC/Wellcome/MRC/GAČR/DFG/Horizon Europe with built-in review criteria, and drafts section by section with word-count tracking and quality checklists
• •[`grant-proposal` agent](agents/grant-proposal.md) upgraded — autonomous funder call parsing, neuroscience-aware Approach drafting (EEG/fMRI/iEEG/eye-tracking), and per-section confirmation loop
• •[`phase-grant-proposal` skill](skills/phase-grant-proposal/SKILL.md) expanded — deep funder knowledge base, review criteria alignment table, common fatal weaknesses guide, and neuroscience-specific power analysis and preprocessing standards

What's new in 0.1.7

• •[`neuroflow-developer`](.github/agents/neuroflow-developer.md) — superspecialized GitHub agent for developing and maintaining the neuroflow plugin; merges neuroflow-core lifecycle rules and neuroflow-develop guidance into one repo-aware agent; reads the live state of every skill, command, agent, and hook at the start of each session so it is always operating on what the repo actually contains

What's new in 0.1.6

• •[Neuroflow Mind](https://stanislavjiricek.github.io/neuroflow/mind/) — interactive mind map visualization of the entire neuroflow universe; every command, skill, agent, and concept rendered as a force-directed graph with phase clustering; click any node to explore its connections and open its docs; colored receptor dots on each node surface reveal its domain tags (EEG, fMRI, brain-sim, stats, ML, writing, literature, memory, code, human); accessible from the homepage hero button
• •Visual phase map in [`/phase`](commands/phase.md) — the phase command now renders a full phase map with four distinct markers: ● current phase, ◉ visited (.neuroflow/{phase}/ subfolder exists), → recommended by neuroflow after the interview, ○ not started; phases are grouped so active and visited appear first, followed by recommended, then the rest
• •Phase sequence suggestion in [`/neuroflow`](commands/neuroflow.md) — after the initial interview (new Step 2b), neuroflow now derives and prints a recommended ordered phase sequence tailored to the project, and saves it as recommended_phases in project_config.md; /phase reads this field to render the → markers in the phase map
• •Phase outlook in [`/interview`](commands/interview.md) — at the end of any interview session, neuroflow suggests which neuroflow phases are most relevant to where the user is heading, based on the session content and the existing project config

What's new in 0.1.5

• •[`/git`](commands/git.md) — context-aware git utility with smart shorthand aliases (p, pl, ps, a, c, ac, acp, b, pr); reads repo state to decide push vs pull, suggests commit messages, and can open PRs via gh CLI
• •[`/output`](commands/output.md) — new utility command and `neuroflow:phase-output` skill: export project memory or the whole project as a zip archive or folder copy; always excludes sessions and credentials; logs each export run to .neuroflow/output/
• •Slash command availability in all skills — when any phase skill is invoked directly without its slash command, it now runs the full workflow and mentions the corresponding /neuroflow:<command> at the end; behavior defined in `neuroflow:neuroflow-core` and declared in each phase skill's ## Slash command section
• •[`neuroflow:neuroflow-core`](skills/neuroflow-core/SKILL.md) — added Default agent behavior section: scientific honesty (no sugar-coating), dry English humor, and conservative-by-default mode (follow neuroflow-core; only add new functionality when explicitly asked)
• •[`/neuroflow`](commands/neuroflow.md) greeting — on start, neuroflow now greets with Hi, neuroflow here (v0.1.5) followed by a randomly chosen line (let's do some magic today, let's go hack some stuff, or I heard HARKing is fun)
• •15 phase agents — `ideation`, `grant-proposal`, `experiment`, `tool-build`, `tool-validate`, `data`, `data-preprocess`, `data-analyze`, `notes`, `write-report`, `brain-build`, `brain-optimize`, `brain-run` — each agent is a specialist autonomous subprocess scoped to its phase, with a plan-first / confirm-before-executing discipline
• •[`/preregistration`](commands/preregistration.md) — new command and `neuroflow:phase-preregistration` skill: draft OSF, AsPredicted, or registered-report pre-registrations; review for completeness; log deviations; link registered reports
• •[`/finance`](commands/finance.md) — new command and `neuroflow:phase-finance` skill: budget planning, expense logging, funder-facing financial reports, and grant compliance checks
• •[`/pipeline`](commands/pipeline.md) — define and run a multi-step research pipeline across any sequence of neuroflow phases; interactive by default (pauses for approval between steps), or pass --executor for brutal mode (runs straight through without stops); supports resuming from a saved plan and graceful error handling
• •Behavioral flags — three prompt-level personality modes added to `neuroflow:neuroflow-core`: executor (aggressive evaluation loop — reruns and self-critiques until high-quality threshold is met), teacher (clarify-first mode — asks targeted questions before each step, proceeds incrementally), and critic (interrogates assumptions, surfaces hard questions first). Include any mode keyword in a prompt and it activates for the full command session.

What's new in 0.1.4

• •[`/quiz`](commands/quiz.md) — neuroscience quiz command with three modes: flashcards (saveable A4 printable layout), pub quiz (with neuroscience-themed house rules), and rapid-fire throw questions (default)
• •[`/fails`](commands/fails.md) — new utility command and `neuroflow:phase-fails` skill: log dissatisfaction (core behavior, science quality, or interaction UX) to .neuroflow/fails/, with optional one-click GitHub issue reporting
• •[`/idk`](commands/idk.md) — a small easter egg: a personal support companion for when you're burned out, overwhelmed by deadlines, or just need to think out loud; breaks down impossible task lists and lets you decompress mid-research
• •[`/interview`](commands/interview.md) — interview preparation from either side of the table; generates tailored questions grounded in your research context, runs practice Q&A, and optionally evaluates your readiness
• •Brain simulation commands — `/brain-build`, `/brain-optimize`, and `/brain-run` for assembling, fitting, and running computational brain models (NEURON, Brian2, NetPyNE, NEST, tvb-library)

What's new in 0.1.3

• •`/start` renamed to [`/neuroflow`](commands/neuroflow.md) — the main entry point is now /neuroflow:neuroflow; all commands, docs, and agents updated
• •Behavioral improvements — lifecycle hardened based on real-session feedback: continuous session logging, live `flow.md` updates, phase transition prompts, utility scripts routed to .neuroflow/{phase}/tools/, local .claude/CLAUDE.md creation enforced in project root

What's new in 0.1.2

• •12 phase skills — `neuroflow:phase-ideation` through `neuroflow:phase-write-report` — each loaded automatically by its corresponding command to orient agent approach, relevant skills, and workflow hints

What's new in 0.1.1

• •Full research pipeline — commands from `/neuroflow` through /paper and /review, each writing to .neuroflow/ project memory
• •`neuroflow:neuroflow-core` — shared lifecycle and .neuroflow/ folder spec that every command and agent follows; commands now automatically append significant decisions to .neuroflow/reasoning/{phase}.json
• •`scholar`, `sentinel`, `sentinel-dev` agents
• •sentinel checks plugin version against project_config.md and flags when the plugin has been updated; both sentinels clear their report to "All clear" after fixing issues
• •project_config.md now tracks plugin_version — kept in sync with plugin.json by /neuroflow and /sentinel
• •MCP servers declared in plugin.json: PubMed, bioRxiv, Miro, Context7

Why neuroflow

Most neuroscience software solves one problem at a time — a preprocessing library, a stats package, a reference manager. You still have to stitch everything together yourself, re-explain context at every step, and manually translate between tools and phases.

neuroflow is different. It is not a toolbox. It is the agentic operating system for neuroscience research — orchestrating every phase from the first hypothesis all the way to a manuscript draft.

You work in your editor. Claude works alongside you — reading your data, writing analysis code, reviewing your paper, auditing your statistics — guided by skills and agents that understand neuroscience domain conventions.

Focused on:

• •EEG, iEEG, fMRI, eye tracking, ECG, and other physiological signals
• •Cognitive, clinical, and preclinical research
• •Experimental paradigm development and real-time systems
• •From hypothesis formulation to paper draft

Commands

Run /neuroflow:<command> in any project folder. Start with /neuroflow:neuroflow.

Entry point

Research pipeline

Brain simulation

Utility

Skills

Skills are invoked by Claude automatically when relevant, or triggered explicitly.

Agents

Agents are autonomous subprocesses launched by commands when deeper, focused work is needed.

Hooks

Hooks fire automatically on tool use events.

Pre-session orientation is handled via .claude/CLAUDE.md injection — /neuroflow writes a neuroflow block there so Claude always knows the active phase and where to find project context.

Project memory

Every neuroflow command writes its output to .neuroflow/ at the root of your project repo. This is the shared memory of your project — readable by every command and agent, across sessions.

.neuroflow/
├── project_config.md       ← current phase, research question, tools, plugin_version — read by every command
├── flow.md                 ← index of all subfolders
├── sentinel.md             ← sentinel audit report
├── linked_flows.md         ← paths to other .neuroflow/ folders (optional)
├── team.md                 ← project members and roles (optional)
├── timeline.md             ← milestones and deadlines (optional)
├── sessions/               ← one .md per day — add to .gitignore
├── reasoning/              ← structured per-phase decision logs (JSON: statement, source, reasoning)
├── ethics/                 ← IRB documents, consent forms
├── preregistration/        ← OSF / AsPredicted documents
├── finance/                ← grant documents, expense tracking
├── ideation/               ← research questions, proposals, literature reviews
├── grant-proposal/         ← grant application drafts
├── experiment/             ← paradigm scripts, recording setup docs
├── tool-build/             ← tool specs and build notes
├── tool-validate/          ← validation plans and results
├── data/                   ← data inventory and intake reports
├── data-preprocess/        ← preprocessing configs and QC reports
├── data-analyze/           ← analysis plans and result summaries
├── paper/                  ← manuscript drafts and critic logs
├── notes/                  ← structured notes from meetings and talks
└── write-report/           ← project reports
└── fails/                  ← dissatisfaction log: core.md, science.md, ux.md
└── output/                 ← output log: one .md per export run

Installation

Claude Code:

claude plugin marketplace add stanislavjiricek/neuroflow
claude plugin install neuroflow@neuroflow

Or from within Claude Code:

/plugin marketplace add stanislavjiricek/neuroflow
/plugin install neuroflow@neuroflow

GitHub Copilot CLI:

copilot plugin install stanislavjiricek/neuroflow

Or from within an interactive Copilot session:

/plugin install stanislavjiricek/neuroflow

For local development (Claude Code):

git clone https://github.com/stanislavjiricek/neuroflow
claude --plugin-dir ./neuroflow

Once installed, run /neuroflow:neuroflow in any project folder to get started.

MCP server credentials

neuroflow uses four MCP servers that are launched automatically via npx. One requires credentials:

neuroflow also supports an optional Google Workspace CLI (gws) for Gmail, Calendar, Drive, Sheets, and more. It is separate from the MCP servers and must be installed manually:

Note: gws auth setup requires the gcloud CLI. If gcloud is not installed, use the manual OAuth path: create credentials in Google Cloud Console, download client_secret.json, place it at ~/.config/gws/client_secret.json, and run gws auth login.

Setup wizard

Run /neuroflow:setup (or answer Y when prompted during /neuroflow:neuroflow) to enter a guided wizard:

1. Miro — paste a personal access token from your Miro developer settings. Skippable.
2. Google Workspace CLI — checks if gws is installed; offers to install via npm if not; guides through the manual OAuth credential path (no gcloud required). Skippable.

Credentials are saved to `.neuroflow/integrations.json` in your project folder. This file is excluded from git (see .gitignore) so it is never committed.

Activating credentials

After running /setup, export the env vars in your shell before starting Claude Code:

export MIRO_ACCESS_TOKEN="eyJ..."
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE="$HOME/.config/gws/client_secret.json"

Add these to your shell profile (~/.zshrc, ~/.bashrc) so they load automatically on every session.

Alternatively, you can set the env vars directly without running the wizard — the plugin will use whichever values are present in the environment.

What is automatic vs manual

Reminder behavior

• •If you mention Miro during ideation and MIRO_ACCESS_TOKEN is missing, a reminder to run /neuroflow:setup appears.
• •You can always re-run /neuroflow:setup to add or update credentials.

Contributing

neuroflow is intentionally small right now — and that's the point. It is designed to grow with the community.

If you work in neuroscience and have a workflow that Claude could help with, contributions are very welcome:

• •New skills — domain knowledge for a modality, analysis method, or writing task
• •New commands — multi-step pipelines for common research workflows
• •New agents — autonomous subprocesses for focused tasks

See `neuroflow:neuroflow-develop` for the development guide, or open an issue to discuss an idea before building.

License

MIT © Stanislav Jiricek