Carrel: A Private Desk in the Library, Set Up by AI

A research desk should emerge from conversation, not from a checklist.

Carrel now comes in two forms. The full Claude Code plugin provides the dedicated setup agent, slash commands, hooks, workflow skills, and a typed Python CLI. The standalone skills/carrel/ Agent Skill carries the same research-vault practice into other Agent Skills hosts through portable workflows, contracts, templates, and a bundled stdlib-only Python runtime.

The full plugin lives at linxule/carrel. The portable skill has its own repository at linxule/carrel-skill.

The portable skill is not merely the old CLI without Claude. It preserves the conversational onboarding and judgment layer, then uses its bundled runtime for deterministic vault and policy operations. It is a strict subset of the full plugin, which remains the richest Carrel surface. Both keep the premise that made Carrel worth building: the product is not the install; it is the relationship that begins during install.

The full plugin bootstrap supports macOS, Linux, and Windows. The portable skill runs wherever a host can discover the whole skill folder, execute bundled files, and provide Python 3.10 or newer.

Why it matters

The list of tools at the bottom of an "AI research stack" tutorial may be correct. Following it is still the wrong way to start, because you end up with a configured machine and no understanding of why each piece is there.

Carrel inverts that. In the full plugin, @setup-interviewer asks about the researcher's actual work before installing anything. In a portable host, the same interview is defined in the skill's onboarding workflow. A short stretch reads roughly like this:

Setup-interviewer: What kind of source material do you work with most? Mostly PDFs, mostly interview recordings, mostly notes from the web, or a mix? You: A mix, but heavy on interview audio right now. Setup-interviewer: Good to know. I'll set up coli for local transcription and liteparse for ordinary PDFs. For complex tables or scans, I can offer MinerU or Mistral OCR after we check whether cloud processing is acceptable. Anything sensitive about the audio? Patient interviews? Anything under NDA?

The product of the interview is a stack the researcher can explain. Its record also gives later setup, repair, and research sessions a shared account of the environment and its boundaries.

Two surfaces, one contract

Full Claude Code plugin

The plugin is the complete experience:

• 15 /carrel-* commands: seven thin wrappers over typed CLI subcommands and eight full skill prompts.
• Two agents: @setup-interviewer for onboarding and @research-partner for thinking with the researcher.
• 13 workflow-specific plugin skills, plus the portable Carrel umbrella skill in the repository.
• Four hooks for environment checks, reflection prompts, per-turn vault context, and a cloud-tool sensitivity checkpoint.
• An installed carrel CLI with 11 subcommand groups: paper, transcript, capture, google, vault, env, setup-state, trust, automate, batch, and migrate.

The slash commands and hooks call the installed typed CLI. They do not call the portable skill's bundled runtime.

Portable Agent Skill

The standalone skill is a host-neutral operating layer for research vaults. Its lean SKILL.md routes the agent to deeper workflow and contract references. Templates under assets/ scaffold the vault, while scripts/carrel.py and scripts/carrel_core/ provide a stdlib-only Python 3.10+ runtime with no pip dependencies.

That runtime handles low-freedom operations such as vault initialization, profile validation and repair, document filing, batch work, trust checks, policy explanations, automation configuration, reflection logs, feedback export, and collaborator handoffs. Search, synthesis, note design, and the interview remain agent work.

The portable surface does not provide Claude Code slash commands, hooks, agents, marketplace state, plugin migrations, or direct cloud-provider calls. Host adapters may add those capabilities while preserving the portable contracts.

Commands

These commands belong to the full Claude Code plugin. Portable hosts invoke the skill in natural language and let it call scripts/carrel.py when a deterministic operation is needed.

Host support

"Full" below means full support for the Carrel surface available on that host. On non-Claude hosts, that surface is the portable Agent Skill, not the full Claude Code plugin.

For a researcher who wants the full plugin, use Claude Desktop's Code tab. For a researcher committed to another host, install the portable skill and keep the whole folder together.

Trust and sensitivity

Trust governs what the agent may do. Sensitivity governs where research data may go. The two are separate, and high sensitivity overrides every trust level.

Carrel uses four trust levels:

• Advisory: suggest, never act without explicit approval.
• Consultative: prepare and propose actions, then ask before meaningful writes.
• Delegated: act on routine work within named boundaries and report afterward.
• Partnership: exercise broader autonomy only after explicit opt-in.

In the full plugin, the typed CLI enforces its action matrix through commands such as:

carrel trust check vault:move-file --vault .
carrel trust list --vault .

The portable runtime provides the corresponding checks:

python3 scripts/carrel.py trust check vault:move-file --vault .
python3 scripts/carrel.py trust list --vault .

The portable runtime stores and validates trust preferences, but the calling agent must still apply judgment before writes. If a host lacks the full plugin's hooks, its agent must also supply the confirmation step those hooks would have provided.

The sensitivity router follows three rules:

• High: block cloud tools even when credentials and consent are present.
• Medium: prefer local tools. A cloud route must be explicitly requested; the full plugin also pauses for human confirmation through its PreToolUse hook.
• Low: still prefer local tools. Cloud fallback requires consent and an available adapter.

The full plugin implements cloud adapters for MinerU and Mistral OCR conversion, plus Groq and Gemini transcription routes. Mistral OCR is intended for scanned or layout-heavy documents and requires MISTRAL_API_KEY. The portable stdlib runtime can explain policy and report credentials, but it does not call those provider APIs directly. A host adapter must supply the cloud execution.

Install

Choose the surface you intend to use. Installing the portable skill does not install the full plugin, and installing only the typed carrel CLI does not install the portable skill.

uv tool install git+https://github.com/linxule/carrel.git

npx skills add linxule/carrel-skill

cd skills
zip -r carrel-skill.zip carrel -x "*__pycache__*" "*.pyc" "*.DS_Store"

Verifying installation

For the full plugin, run:

/carrel-status

For the portable skill, ask the host to use Carrel, then verify the bundled runtime from the installed skill directory:

python3 scripts/carrel.py env doctor --vault <vault> --format json

Facilitator-assisted setup

When setting up a researcher's machine in person:

Part of Research Memex

The full plugin's interview configures the research environment and then offers optional integrations. The portable skill can scaffold and repair the same kind of vault, but host adapters own system installation, scheduling, and direct cloud execution.

The full plugin environment

These are the foundation of the complete setup:

• Obsidian: the researcher sees a notebook; the agent sees markdown.
• The typed carrel Python CLI: 11 subcommand groups used by the plugin's commands and hooks.
• Local conversion: liteparse for PDFs, markitdown for general formats, and defuddle for web pages.
• Local transcription: coli plus ffmpeg.
• Google Workspace: gws when the interview surfaces Drive or Docs work.

Optional integrations

The full plugin offers these MCPs only when the interview surfaces a need:

The typed CLI also carries a Mistral OCR cloud adapter for scanned or layout-heavy documents, when cloud processing is allowed. It has no Toolkit page of its own because it is a provider route inside the CLI, not an agent-callable server. Its credentials are covered in the API-key guide (docs/api-keys-guide.md).

Each integration needs its own credentials. The portable runtime can record these choices and report configured keys, but provider calls and MCP installation remain adapter work.

What Carrel does not install today

Carrel does not currently install sibling Claude Code plugins, methodology-specific MCP bundles, compute-heavy optional MCPs, or standalone research platforms. These are scope decisions, not architectural limits:

These tools coexist with Carrel without sharing state. The division is by layer: Carrel sets up and maintains the research environment, while the other tools add methodology, memory, review, compute, or a separate application surface.