# Paper Agent for Raycast

URL: https://www.raycast.com/marvel940804836/paper-agent

> Browse, search and triage research papers from your local Paper Agent workflow, manage favorites and a reading queue, and run or schedule the pipeline.

- Install: raycast://extensions/marvel940804836/paper-agent
- Author: [Ge Li](https://www.raycast.com/marvel940804836)
- Installs: 30
- Platforms: macOS
- Categories: Developer Tools, Productivity
- Updated: 2026-11-17
- Source: https://github.com/raycast/extensions/tree/480c8790efdca370fda96f8f95bc914604e362d5/extensions/paper-agent/

## Commands

- **Browse Today's Papers**: Show today's papers from your local Paper Agent workflow and open notes or paper links.
- **Browse Recent Papers**: Show recently discovered papers from your Paper Agent library.
- **Search Papers**: Search papers in your local library by title, authors, summary, and more.
- **Browse Favorite Papers**: Open papers you have added to favorites from the Paper Agent extension.
- **Browse Reading Queue**: Open papers you have added to your reading queue from the Paper Agent extension.
- **Run Paper Pipeline**: Runs the full Paper Agent pipeline with Raycast Preferences applied at runtime (overriding runtime YAML fields), then updates local notes, library JSON, and daily/weekly digests.
- **Install Daily Schedule**: Installs or updates a macOS launchd job that runs Paper Agent daily at 04:00 and catches up after boot/login if missed.
- **Remove Daily Schedule**: Unloads and removes the macOS launchd job for the daily Paper Agent run while keeping logs and status history.
- **Check Run Status**: Shows run status for both scheduled (launchd) and manual runs: whether the daily schedule is installed, today's result, last successful day, and the most recent run metadata with actions to open log or state directory.
- **Open Paper Directory**: Opens the Paper directory folder from Preferences in Finder.
- **Open Config Directory**: Opens the folder that contains your config.yaml (the core repo root) in Finder.

## README

<h1 align="center"><img src="https://github.com/raycast/extensions/raw/480c8790efdca370fda96f8f95bc914604e362d5/extensions/paper-agent//assets/extension-icon.png" width="23" height="23" alt="" style="vertical-align: middle;" /> Paper Agent</h1>

A [Raycast](https://www.raycast.com/) extension for the [Paper Agent](https://github.com/galleonli/paper-agent) workflow: run the pipeline, browse today’s and recent papers, search your library, manage favorites and a reading queue, and schedule daily runs on macOS.

> [!IMPORTANT]
> **Repository references**
>
> - **Paper Agent core repo (main workflow):** https://github.com/galleonli/paper-agent
> - **Paper Agent Raycast extension repo (this project):** https://github.com/galleonli/paper-agent-raycast
>
> **Start with the [Paper Agent core README](https://github.com/galleonli/paper-agent#readme) first.** This repo contains the Raycast extension only.
> Complete core setup and run it once before using extension commands.

---

#### Requirements

- **Raycast** (macOS)
- **Paper Agent core** — cloned repo with valid `config.yaml` and `paper_agent` installed (default Python is `<config_dir>/.venv/bin/python3`, or set **Python Executable** in Preferences)
- **Paper Directory** — a folder where the core writes notes, daily/weekly digests, and `library/` (JSON outputs)

---

#### Quick start

##### 1. Install Paper Agent core

Follow the [core README Quick start](https://github.com/galleonli/paper-agent#quick-start) first, then return here.
You need core installed and runnable (valid `config.yaml`, environment ready, and at least one successful run so `library/` has data).

**One-liner (Unix/macOS):**

```bash
git clone https://github.com/galleonli/paper-agent.git && cd paper-agent && ./scripts/bootstrap.sh
```

Then run the pipeline once (e.g. `./.venv/bin/python -m paper_agent run --config config.yaml`). For detailed core install (cron, config options), see the [core README Quick start](https://github.com/galleonli/paper-agent#quick-start).

##### 2. Install this extension

- **From the Store:** search for “Paper Agent” in Raycast and install.
- **Local development:** use Node.js 22.22.2 or later, enter this extension's directory, run `npm ci` and `npm run dev` to load it in Raycast.

##### 3. Configure Preferences

Open **Raycast → Extensions → Paper Agent → Preferences** and set:

| Preference            | Description                                                                    |
| --------------------- | ------------------------------------------------------------------------------ |
| **Config File Path**  | Full path to the core `config.yaml` (e.g. `/path/to/paper-agent/config.yaml`). |
| **Paper Directory**   | Your `delivery.paper_dir`: where notes, digests, and `library/` live.          |
| **Python Executable** | Optional. Leave empty to use `<config_dir>/.venv/bin/python3`.                 |

When you use **Run Paper Pipeline** or **Install Daily Schedule**, the extension builds runtime config (direction, delivery, summarize, sources, policy) from these preferences; values in `config.yaml` for those sections are overridden. Other sections (e.g. interests, export, prompts) are still read from `config.yaml`.

---

#### Commands

| Command                    | Description                                                                                                                                                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Run Paper Pipeline**     | Start the full pipeline in background: fetch, filter, summarize, and write local notes/library plus daily/weekly digests. Runtime fields come from Preferences (direction, delivery, summarize, sources); shared sections still come from `config.yaml`. |
| **Today Papers**           | Browse today’s papers from your local library. Detail view: title, authors, abstract, “Why this paper,” optional research summary. Actions: open paper/note, related papers, mark read, favorites, reading queue.                                        |
| **Recent Papers**          | Browse recently added papers (count-based). Same detail and actions as Today Papers. Limit is set in Preferences (**Recent Papers Limit**).                                                                                                              |
| **Search Papers**          | Search the local library by title, authors, abstract, categories, date. Same list actions as above.                                                                                                                                                      |
| **Favorite Papers**        | Papers you’ve added to favorites from any list. Stored locally in the extension.                                                                                                                                                                         |
| **Reading Queue**          | Papers you’ve queued for reading. Stored locally; same open/read/favorite actions.                                                                                                                                                                       |
| **Install Daily Schedule** | Install a macOS `launchd` job that runs Paper Agent daily at **04:00** and catches up once after boot/login if 04:00 was missed. Re-run after changing Preferences that affect the pipeline.                                                             |
| **Remove Daily Schedule**  | Uninstall the daily `launchd` job. Logs and status history are kept.                                                                                                                                                                                     |
| **Check Run Status**       | View whether the daily schedule is installed, today’s result, last successful day, and last run metadata. Actions: open config directory, log directory, state directory, and last run log (when available).                                             |
| **Open Paper Directory**   | Open the configured paper directory in Finder (notes, `library/`, digests).                                                                                                                                                                              |
| **Open Config Directory**  | Open the folder that contains your `config.yaml` (core repo root) in Finder. Also available as an action in **Run Paper Pipeline** (Core not found) and **Check Run Status** when **Config File Path** is set.                                           |

##### Daily schedule: when does the LaunchAgent run?

The daily job is a macOS LaunchAgent. It is **loaded** only in two cases:

1. **User login** — When you log in to the Mac (e.g. after reboot or logout/login), launchd loads all jobs in `~/Library/LaunchAgents/`, including the Paper Agent daily job. If the plist has `RunAtLoad = true`, that triggers one run at load time (the "catch-up" run).
2. **Running Install Daily Schedule** — The command runs `launchctl bootstrap`, which loads (or reloads) the job and triggers `RunAtLoad` once.

**Opening Raycast or the extension does not load the LaunchAgent.** So opening the plugin, running **Check Run Status**, or browsing papers does not cause a catch-up run.

- **04:00 run** — Fires only if the Mac is **awake** at 04:00. If the Mac is off or asleep, that run is skipped; the next run is the next calendar 04:00 (or a catch-up run when the job is loaded).
- **Catch-up** — Runs only when the job is loaded (login or Install Daily Schedule). It does **not** run when you wake the Mac from sleep.

**Agent root on Desktop / iCloud / external drive:** When the job runs, the agent root path (where `run_paper_agent.sh` lives) must be readable. Right after login, iCloud Drive (e.g. Desktop & Documents) or an external disk may not be mounted or ready yet, so the script can be temporarily unavailable. The wrapper **waits up to 2 minutes** (checking every 15 seconds) for the path to become readable before giving up and writing "agent-root-unavailable". So placing the repo on Desktop or an external drive is supported as long as the volume is available within that window (e.g. after login). If the path is still unavailable after 2 minutes (e.g. external drive not connected at 04:00), run manually or move the repo to a path that is always present (e.g. `~/paper-agent`).

---

#### Core not found

If the extension can’t detect the core (missing or invalid config path, missing Python/venv, or `paper_agent` not runnable), relevant commands show **Core not found** with:

- A link to the [core repo](https://github.com/galleonli/paper-agent)
- **Copy Bootstrap Command** — copies a one-line install command; paste in a terminal to clone and bootstrap the core, then set Preferences again
- **Open Config Directory** — shown only when **Config File Path** is set; opens the folder containing `config.yaml` in Finder
- **Open GitHub** — opens the core repo in the browser

---

#### Updates

Open **Check Run Status** to see the versions actually in use. **Check Core Update** contacts GitHub only when selected; it reports newer stable core releases without installing them or running the pipeline. Failed checks remain errors, not up-to-date results.

- **Core:** from a clean core checkout on `main`, run `git pull --ff-only && ./scripts/bootstrap.sh`. The bootstrap refreshes the Python environment and preserves an existing `config.yaml`. Resolve any local changes or diverged branch before updating.
- **Store extension:** Raycast manages Store updates separately from the Python core.
- **Development extension:** update your extension checkout, run `npm ci`, then `npm run dev`. Updating source files alone does not update the extension loaded in Raycast.

Refresh **Check Run Status** after updating. Reinstall the daily schedule only if its paths or pipeline preferences changed.

#### Development

Use Node.js 22.22.2 or later and an up-to-date Raycast installation. This extension uses Raycast API 2.9.0. Run `npm run build` first to generate the preference types, then `npm run typecheck` and `npm test` for typechecking and offline regression tests.

```bash
git clone <this-repo> && cd paper-agent-raycast
npm install
npm run dev    # Load extension in Raycast for development
npm run lint   # Validate package.json and run ESLint + Prettier
npm run build  # Compile extension
```

**Publish to the Raycast Store:** `npm run publish` (see [Raycast publish docs](https://developers.raycast.com/basics/publish-an-extension)).

---

#### Troubleshooting

##### Core detection and preferences

- **Core not found / Run Paper Pipeline fails immediately** — Verify **Config File Path** points to a real `config.yaml`, and **Python Executable** points to a valid interpreter (or leave empty to use `<config_dir>/.venv/bin/python3`).
- **Quick verification command** — In the core repo root, run `python -m paper_agent run --help`. If this fails, fix the core environment first.
- **Paper Directory mismatch** — Ensure Raycast **Paper Directory** matches the core runtime output location you expect; list/search commands read from that location.

##### Empty lists (Today / Recent / Search)

- **Could not load/search papers** — The command failed; this does not mean the library is empty. Use **Open Extension Preferences** to check paths, then **Retry**. Invalid CLI output is also reported as an error. Core checks time out after 10 seconds and library queries after 30 seconds.
- **Python path copied with spaces** — Leading and trailing whitespace is ignored. Spaces inside a path are preserved.
- **No data yet** — Run the core pipeline at least once so `library/` has JSON entries.
- **Recent is count-based** — **Recent Papers** is controlled by **Recent Papers Limit** (not by a day window). Increase the limit in Preferences if needed.
- **Source checks** — If data still looks empty, use core CLI checks: `python -m paper_agent today --json --config config.yaml` and `python -m paper_agent list --json --limit 20 --config config.yaml`.

##### Run and schedule behavior

- **Run Paper Pipeline shows only “Run started in background”** — This is expected: manual runs are detached. Use **Check Run Status** and open run logs from there to inspect final success/failure.
- **Last run failed / pipeline exit nonzero?** — In **Check Run Status**, use **Open Last Run Log** to see the error. A common cause is **arXiv 429** (rate limit): wait 15–30 minutes and run again; the pipeline also retries automatically. For other errors, see the core [Troubleshooting](https://github.com/galleonli/paper-agent#troubleshooting).
- **Daily schedule not running / today's 04:00 didn't run** — The 04:00 run only fires if the Mac is **awake** at 04:00. If the Mac was off or asleep, no run occurs. Catch-up runs only when the LaunchAgent is **loaded**: at **user login** (after reboot or logout/login) or when you run **Install Daily Schedule**. Opening Raycast or the extension does **not** load the agent, so it does not trigger a catch-up. If "Today's result" is still "Not run yet", run **Run Paper Pipeline** manually for today, or log out and back in / re-run **Install Daily Schedule** to trigger a catch-up. After changing Preferences that affect the pipeline, re-run **Install Daily Schedule** and use **Check Run Status** to confirm install state and latest run metadata. To verify whether launchd ever started the job today, check `~/Library/Logs/PaperAgent/launchd.stdout.log` and `launchd.stderr.log` for today's date.
- **Launchd scope** — Daily schedule commands are macOS `launchd` automation only.

##### Scholar Inbox via Raycast

- **Enabled but no Scholar items** — Confirm Scholar Preferences are filled (`provider`, `imap host`, `imap user`, password or password env var name), then run again.
- **Credentials confusion** — If you set **Scholar IMAP password** in Preferences, Raycast injects it for runs. If left empty, ensure the configured env var exists in the execution environment.

For core-side troubleshooting (config schema, diagnostics, CLI/cron, Scholar provider behavior, output artifacts), see the [Paper Agent core Troubleshooting](https://github.com/galleonli/paper-agent#troubleshooting).

---

#### License

This project is licensed under the [MIT License](https://github.com/raycast/extensions/raw/480c8790efdca370fda96f8f95bc914604e362d5/extensions/paper-agent//LICENSE).
