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

URL: https://research-memex.org/docs/toolkit/carrel
Description: Carrel pairs a full Claude Code research-environment plugin with a portable multi-host Agent Skill, both governed by explicit trust and sensitivity boundaries.



*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](https://github.com/linxule/carrel). The portable skill has its own repository at [linxule/carrel-skill](https://github.com/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.

<ToolMeta slug="carrel" runtime="Full plugin: Python 3.11+ / uv + JavaScript hooks; portable skill: Python 3.10+ stdlib" note="Interview first, install second. The setup is the pedagogy." />

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 [#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?
> &#x2A;You:* A mix, but heavy on interview audio right now.
> &#x2A;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 [#two-surfaces-one-contract]

### Full Claude Code plugin [#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 [#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 [#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.

<KeyTable>
  | Command              | What it does                                                      |
  | -------------------- | ----------------------------------------------------------------- |
  | `/carrel-setup`      | Full onboarding interview, audit, scaffold a vault                |
  | `/carrel-status`     | Check what's installed and working                                |
  | `/carrel-fix`        | Diagnose environment drift and guide recovery                     |
  | `/carrel-convert`    | Convert PDF / Word / slides to markdown in your vault             |
  | `/carrel-batch`      | Batch convert or transcribe a folder; file results into the vault |
  | `/carrel-capture`    | Save web content to your vault                                    |
  | `/carrel-transcribe` | Transcribe audio to text in your vault                            |
  | `/carrel-automate`   | Set up or update overnight vault maintenance and analytical tasks |
  | `/carrel-reflect`    | End-of-session reflection                                         |
  | `/carrel-mirror`     | Synthesize your research patterns from reflections and logs       |
  | `/carrel-cheatsheet` | Regenerate your reference card                                    |
  | `/carrel-share`      | Generate a collaborator handbook for this vault                   |
  | `/carrel-teammates`  | Add, remove, or review model teammates (Codex, Gemini, Kimi)      |
  | `/carrel-migrate`    | Check for updates, show what's new, apply migrations              |
  | `/carrel-feedback`   | Generate an anonymized feedback digest for sharing                |
</KeyTable>

## Host support [#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.

<HostSupport
  rows="[
{ host: 'Claude Code (Desktop Code tab / CLI)', status: 'full', note: 'Install the full plugin for commands, hooks, agents, workflow skills, cloud adapters, and the typed CLI. Standalone skill installation is also supported when the plugin is absent.' },
{ host: 'Codex CLI / IDE / Desktop', status: 'full', note: 'Install the portable folder at `.agents/skills/carrel` or `~/.agents/skills/carrel`. Codex metadata lives in `agents/openai.yaml`; symlinked skill folders are supported.' },
{ host: 'Cursor', status: 'full', note: 'Install the portable folder at `.agents/skills/carrel` or `~/.agents/skills/carrel`, with bundled scripts and assets intact.' },
{ host: 'OpenCode', status: 'full', note: 'Use `.agents/skills/carrel`, `.opencode/skills/carrel`, `~/.agents/skills/carrel`, or `~/.config/opencode/skills/carrel`; allow skill, read, and shell access.' },
{ host: 'Gemini CLI', status: 'full', note: 'Where Agent Skills are enabled, install at `.agents/skills/carrel` or `.gemini/skills/carrel` and allow access to bundled scripts and assets.' },
{ host: 'Kimi Code CLI', status: 'full', note: 'Install at `.kimi-code/skills/carrel`, `.agents/skills/carrel`, or the corresponding global path.' },
{ host: 'Claude app / Claude.ai chat', status: 'partial', note: 'Upload the complete skill as a zip through Settings > Capabilities > Skills. Cloud execution can work with uploaded or connected files, but it cannot directly write an arbitrary local vault.' },
{ host: 'Claude Cowork', status: 'full', note: 'Works with a connected local folder while Claude Desktop is open. Remote-only sessions without that connection cannot reach the local vault.' },
{ host: 'Kimi app / Kimi Work', status: 'partial', note: 'Suitable for instructions and documents, but not verified for bundled local scripts. Use Kimi Code when the runtime must write a vault.' },
]"
/>

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-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:

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

The portable runtime provides the corresponding checks:

```bash
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 [#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.

<Tabs>
  <Tab title="Full plugin: bootstrap">
    Use the one-line bootstrap on a fresh machine or for facilitator-assisted setup.

    <KeyTable column="2">
      | Platform | Command                                                                               |
      | -------- | ------------------------------------------------------------------------------------- |
      | macOS    | `curl -fsSL https://raw.githubusercontent.com/linxule/carrel/main/install.sh \| bash` |
      | Linux    | `curl -fsSL https://raw.githubusercontent.com/linxule/carrel/main/install.sh \| bash` |
      | Windows  | `irm https://raw.githubusercontent.com/linxule/carrel/main/install.ps1 \| iex`        |
    </KeyTable>

    The script installs the prerequisites, Claude Code, the Carrel plugin, and the typed `carrel` CLI. It is idempotent and safe to re-run.

    Then open Claude Desktop, choose the Code tab, select the research folder, and run `/carrel-setup`.
  </Tab>

  <Tab title="Full plugin: marketplace">
    For an existing Claude Code installation:

    1. Open Claude Desktop → Code tab → click + beside the plugin tabs.
    2. Choose Add marketplace and enter `linxule/carrel`.
    3. Sync the marketplace and enable Carrel.
    4. Install the typed CLI separately:

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

    The marketplace path installs the plugin but not the CLI its commands and hooks call. GitHub CLI authentication is required for repository access.
  </Tab>

  <Tab title="Portable skill: package manager">
    Any compatible `npx skills` client can install the dedicated [Carrel Skill repository](https://github.com/linxule/carrel-skill):

    ```bash
    npx skills add linxule/carrel-skill
    ```

    Do not run `npx skills add linxule/carrel` without scoping it to `--skill carrel`. The plugin repository also contains Claude-specific skills that assume commands, hooks, and agents unavailable in a standalone host.
  </Tab>

  <Tab title="Portable skill: local hosts">
    Copy the entire `skills/carrel/` folder, not only `SKILL.md`.

    | Host                   | Project or user location                                                             |
    | ---------------------- | ------------------------------------------------------------------------------------ |
    | Codex / Cursor         | `.agents/skills/carrel` or `~/.agents/skills/carrel`                                 |
    | OpenCode               | `.opencode/skills/carrel`, `.agents/skills/carrel`, or a supported global equivalent |
    | Gemini CLI             | `.gemini/skills/carrel` or `.agents/skills/carrel`                                   |
    | Kimi Code CLI          | `.kimi-code/skills/carrel` or `.agents/skills/carrel`                                |
    | Standalone Claude Code | `.claude/skills/carrel` or `~/.claude/skills/carrel`                                 |

    The runtime imports `scripts/carrel_core/`, and vault setup reads `assets/templates/`. Both directories are required.
  </Tab>

  <Tab title="Portable skill: Claude app">
    Zip the complete folder:

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

    Upload it through Settings → Capabilities → Skills. Claude app and Claude.ai chat need uploaded files, connectors, or a desktop flow to exchange data with a local vault. Cowork can write a connected local folder while Claude Desktop remains open.
  </Tab>
</Tabs>

### Verifying installation [#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:

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

### Facilitator-assisted setup [#facilitator-assisted-setup]

When setting up a researcher's machine in person:

<Steps>
  <Step title="Bootstrap">
    Choose the full plugin or portable skill before installing anything. For the full plugin, run the platform bootstrap script and help with GitHub authentication.
  </Step>

  <Step title="Run the interview">
    In Claude Desktop, run `/carrel-setup`. In another host, ask the installed Carrel skill to begin onboarding.
  </Step>

  <Step title="Human steps">
    Help install Obsidian and any local tools the interview selected.
  </Step>

  <Step title="Confirm and teach">
    Test with a real PDF, inspect the resulting vault, and make the trust and sensitivity choices legible.
  </Step>
</Steps>

## Part of Research Memex [#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 [#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`](https://github.com/run-llama/liteparse) for PDFs, [`markitdown`](https://github.com/microsoft/markitdown) for general formats, and [`defuddle`](https://github.com/kepano/defuddle) for web pages.
* Local transcription: [`coli`](https://github.com/marswaveai/coli) plus [`ffmpeg`](https://ffmpeg.org/).
* Google Workspace: [`gws`](https://github.com/googleworkspace/cli) when the interview surfaces Drive or Docs work.

<Aside label="WHY NO PAGES">
  These local tools have no Toolkit pages because they are command-line utilities that Carrel orchestrates, not agent-callable surfaces in their own right.
</Aside>

### Optional integrations [#optional-integrations]

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

<CarrelInstallTable />

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](https://github.com/linxule/carrel) (`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 [#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:

<CarrelInstallTable mode="excluded" />

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.