| name | persistent-analysis-session |
| description | Use when exploratory R or Python analysis repeatedly reloads large in-memory objects such as Seurat, AnnData, pickle, RDS, qs, h5ad, joblib, or parquet, or needs a long-running localhost backend on macOS, Linux, or Windows. |
Persistent Analysis Session
Core Rule
When a large object is expensive to load, do not run analysis scripts as fresh one-shot processes. Create or reuse a localhost persistent session that loads the object once, then send small analysis scripts to that session through an OS-appropriate launcher.
This is for exploratory work. Keep production pipelines, reproducible batch jobs, and CI scripts as normal process-per-run commands unless the user asks otherwise.
This skill only sets up the persistent execution backend. It does not provide domain-specific analysis, plotting, or figure-generation scripts. Those scripts are created later in the target project's analysis/ directory and are submitted to the running session through /run.
Workflow
- Identify the language, large object path, loader, and desired in-session object name.
- Check for existing project policy files (
AGENTS.md, Makefile, tools/, analysis/) before adding new tooling.
- Add a local server from
scripts/r_session_server.R or scripts/python_session_server.py, adapting only the loader defaults and dependency imports.
- Add OS-native launch/run helpers bound to
127.0.0.1: Makefile or shell helpers on macOS/Linux, PowerShell helpers on Windows.
- Put generated analysis and plotting scripts under
analysis/. They must assume the large object already exists in memory and must not reload it.
- Create or update an analysis record document such as
analysis/README.md or analysis/analysis-log.md.
- Verify with a skip-load or tiny fixture mode before loading the real large object.
Analysis Record
Keep a short project-local record of how the persistent session is used. The record should list:
- Session setup: language, object path, object name, loader, host, port, start command, log path, and PID file if backgrounded.
- Analysis scripts: each file under
analysis/, what question it answers, and how it is run through session-run.
- Outputs: generated tables, figures, logs, and result directories.
- Findings and decisions: brief notes that explain which exploratory outputs matter and what to try next.
Use references/analysis-record.md as a template when the project does not already have an analysis log.
Boundaries
- The server scripts are infrastructure for reusing memory, not analysis notebooks.
- Do not add generic plotting scripts to this reusable skill.
- Generate project-specific analysis or figure scripts only after the user asks for a concrete analysis.
- Store those scripts and their outputs in the target project, not in this skill bundle.
Expected Project Layout
tools/
r_session_server.R or python_session_server.py
start_session.ps1 if Windows needs reusable launch helpers
analysis/
README.md or analysis-log.md
exploratory_step_01.*
logs/
persistent-session.*.log
results/
...
Safety
- Bind only to
127.0.0.1; never use 0.0.0.0 unless the user explicitly accepts the risk.
- Treat
/run as arbitrary code execution. Do not expose it to a network.
- Do not kill a user-owned long-running session unless asked.
- If the object is huge, verify syntax and endpoint behavior with a mock or skip-load mode first.
Platform Launchers
Choose the launcher that matches the target workspace.
- macOS/Linux: use the project style, usually
Makefile, shell, tmux, or nohup, and call endpoints with curl.
- Windows PowerShell: prefer
Start-Process -PassThru for a durable background server, redirect stdout/stderr to logs/, and call endpoints with Invoke-RestMethod. Avoid Unix inline environment syntax like VAR=value command.
- WSL/Git Bash: treat as macOS/Linux only when the interpreter, server process, and analysis paths all live inside that environment. Do not mix Windows paths and WSL paths in one launcher.
Read references/windows.md when implementing Windows launch/run helpers.
R Pattern
Use the R template when files are loaded with qs::qread(), readRDS(), Seurat, Monocle, CellChat, WGCNA, or similar R workflows.
Read references/r.md only when implementing or adapting the R server.
Expected macOS/Linux project commands:
session-server:
R_SESSION_OBJECT_PATH="$(OBJECT_PATH)" R_SESSION_OBJECT_NAME="$(OBJECT_NAME)" Rscript tools/r_session_server.R
session-run:
curl -sS --data-binary @"$(FILE)" http://127.0.0.1:8787/run
For Windows, use the same tools/r_session_server.R but start it with PowerShell Start-Process; see references/windows.md.
Python Pattern
Use the Python template when files are loaded with scanpy.read_h5ad(), anndata.read_h5ad(), pickle, joblib, pandas, xarray, torch, or similar Python workflows.
Read references/python.md only when implementing or adapting the Python server.
Expected macOS/Linux project commands:
session-server:
PY_SESSION_OBJECT_PATH="$(OBJECT_PATH)" PY_SESSION_OBJECT_NAME="$(OBJECT_NAME)" python tools/python_session_server.py
session-run:
curl -sS --data-binary @"$(FILE)" http://127.0.0.1:8787/run
For Windows, use the same tools/python_session_server.py but start it with PowerShell Start-Process; see references/windows.md.
Common Mistakes
- Reintroducing
readRDS(), qread(), read_h5ad(), pickle.load(), or joblib.load() inside every analysis script.
- Starting the server with the default large object just to test plumbing. Use skip-load or a tiny fixture first.
- Writing project-specific data paths into the reusable skill. Keep paths configurable.
- Forgetting that Codex resume preserves conversation state, not R or Python process memory.
- Reusing macOS/Linux launch syntax on Windows. PowerShell needs
$env:NAME = "value" before Start-Process, and curl may be an alias rather than curl.
