Use without installing¶

You can run a gleanyard project without installing anything on your computer. The project lives in a GitHub repo, GitHub Actions run the collection, and an assistant in the cloud sets sources up. There are four ways in, and you can combine them.

Start from the template repo¶

kausalflow/gleanyard-template holds what gleanyard init writes. Click Use this template, name the repo and create it. Keep it public if the data may be public: Actions minutes are free for public repos.

Then, on github.com:

1. In gleanyard.yaml, replace my-collection with your repo's name and OWNER with your GitHub name, so sites can see who is fetching.
2. Write what you want to collect in research.md and the fields of one record in schema.yaml. The schema reference lists the field types.

The template has the same workflows as any project: validate checks pull requests and collect runs daily once a source is enabled. Repair and research stay off until you add a model key.

Set sources up in the cloud¶

Open Claude Code on the web, pick the repo and ask:

• "Research sources for this project." It reads research.md and schema.yaml, searches, probes each site and opens a pull request with candidates.
• "Set up the candidate for example.org." It writes the source, tries the extraction modes, saves a fixture and the terms it read, and opens a pull request with the try report.

The repo's CLAUDE.md and the gleanyard skill give it the procedures, and the session installs the pinned gleanyard on its own. You review each pull request, decide the source's rights and set enabled: true. The Claude GitHub app works the same way from an issue: mention @claude with the request.

Or open it in Codespaces¶

The template has a devcontainer. Code → Codespaces → Create codespace opens the repo in a browser editor with Python, gleanyard (with its MCP server registered for Claude Code) and Claude Code ready. Run claude in the terminal and ask as above, or run commands yourself:

gleanyard probe https://example.org/events
gleanyard try example-events

crawl4ai, which only gleanyard map needs, is not preinstalled: pip install 'gleanyard[map]' && crawl4ai-setup.

The read-only connector¶

The gleanyard connector is a remote MCP server. Add its URL as a custom connector in claude.ai, ChatGPT, Claude Desktop or any client that speaks MCP over HTTP:

https://gleanyard-connector.leima.workers.dev/mcp

It is read-only by design. It cannot create, change or run sources, and it never fetches the sites a project collects from: it reads only the registry's site and raw.githubusercontent.com, so it sees exactly what a project has already published. Private repos stay invisible to it. To set up sources, use one of the ways above.

Ask, for example: "Using gleanyard, what family events in kausalflow/berlin-family-events mention theater?" or "Are any sources failing in kausalflow/berlin-family-events?"

Run your own¶

The connector is one file with no dependencies, connector/worker.js, for Cloudflare Workers. The free plan's 100,000 requests a day are plenty for it. To serve your own registry, set REGISTRY_URL in wrangler.toml, then:

cd connector
npx wrangler deploy

node connector/test.mjs runs its tests offline.

In a fork or copy of the gleanyard repo, the Deploy connector workflow deploys it for you whenever connector/ changes on main: add the repository secrets CLOUDFLARE_API_TOKEN (a token from the template "Edit Cloudflare Workers") and CLOUDFLARE_ACCOUNT_ID. Without them the workflow does nothing.

The GitHub Action¶

The gleanyard repo is also an Action. It installs the gleanyard version of the ref you use and runs commands, one per line:

- uses: actions/checkout@v4
- uses: kausalflow/[email protected]
  with:
    run: |
      validate
      test

The template's own workflows install gleanyard with pip and do not need the Action; it is for workflows you write yourself, such as checking a project folder inside another repo.