@raggle-ai/raycast-adapter

A Raycast project-search wrapper with shared project state and Git synchronization.

Features

• A reusable project picker for Raycast extensions.
• Shared project discovery and search.
• Shared cache, favorite, recent, and excluded-project storage.
• Git remote synchronization.

Installation

npm install @raggle-ai/raycast-adapter @raycast/api react

The adapter has one public entry point: @raggle-ai/raycast-adapter. It does not own product settings, source databases, cloning, project management, application launching, or product presentation. Platform-neutral search and storage behavior is delegated to @raggle-ai/local.

Project picker

ProjectPicker reads the shared Raggle user settings and scans each configured clone directory and project directory with the Scout Rust scanner. It does not need another Raycast command or a project catalog file. The list supports indexed search across project names, repositories, keywords, session titles, and GitHub owners.

import ProjectPicker from "@raggle-ai/raycast-adapter";
import { open } from "@raycast/api";
import { existsSync } from "node:fs";
import path from "node:path";

export default function Command() {
  return (
    <ProjectPicker
      actionTitle="Open AGENTS.md"
      onSelect={async (project) => {
        const agentsFile = path.join(project.worktree, "AGENTS.md");
        if (!existsSync(agentsFile)) {
          throw new Error("This project has no AGENTS.md file.");
        }
        await open(agentsFile);
      }}
    />
  );
}

The picker reads one shared cache from the Raggle user-data directory, so all Raycast extensions show projects immediately. It refreshes that cache with the Rust scanner in the background. Favorites and recent selections come from shared Raggle user settings. Project icons remain at their original local paths and are not copied into extension storage.

Raycast extensions must copy the native scanner before development and builds:

{
  "scripts": {
    "prepare:native": "raggle-raycast-prepare-native",
    "predev": "npm run prepare:native",
    "prebuild": "npm run prepare:native"
  }
}

Examples

• open-agents-md

Start the example:

npm run dev:examples

Development

Node.js 20 or later is required.

npm ci
npm run typecheck
npm test
npm run lint

Automated tests use generated temporary directories and example identities. For a manual verification that needs values from your machine, create test/local-config.json. Git ignores this file. Do not put local paths, private repository URLs, or credentials in tracked fixtures.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for private reporting instructions.

License

MIT. See LICENSE.

Props

| Prop | Type | Default | Description | | ---------------------- | ---------------------------------------------------- | ---------------------- | ------------------------------------------------------------- | | onSelect | (project: RaycastProject) => void \| Promise<void> | (required) | Called when the user selects a project. May return a promise. | | actionTitle | string | "Select Project" | Primary action title in the action panel. | | navigationTitle | string | "Projects" | Title in the Raycast window chrome. | | searchBarPlaceholder | string | "Search projects..." | Placeholder text in the search bar. |