Learnfold Link

Learnfold Link is the open-source connection boundary between a learner-owned coding agent and the Learnfold app.

The repository contains:

• the native learnfold-link connector distributed through npm;
• the one-time Cloudflare Worker pairing broker and its tests;
• the complete pairing protocol;
• public CI and release automation.

The connector delegates local daemon behavior to the open-source Alleycat project and adds learnfold-link handoff <url>. That command performs user-level service setup, captures the pairing credential inside the native process, and submits it directly to Learnfold's one-time broker.

For stock Hermes Agent, the same command discovers the active Hermes profile, enables its authenticated localhost API, installs or refreshes the user-level gateway service when needed, and keeps the generated API key local. No Hermes source modification is required.

Install and connect

Learnfold provides a short-lived URL in its generated prompt. The agent needs to run only:

npx -y [email protected] handoff "<one-time Learnfold URL>"

Do not save or log the URL. It is a temporary credential.

Repository layout

| Path | Purpose | |---|---| | src/ | Native Rust connector and secure handoff command | | broker/ | One-time pairing broker, generated binding types, and tests | | docs/pairing-protocol.md | Public protocol and security properties | | .github/workflows/ | Public test and release provenance |

The operating-system service identifiers intentionally retain the legacy kittylitter name so existing installations keep their pairings and autostart entry while the public package remains Learnfold Link.

Verify locally

cargo test --locked

cd broker
npm ci
npm run types -- --check
npm run check
npm test

Broker deployment

The broker is a Cloudflare Worker backed by SQLite Durable Objects. Its checked in configuration is deployable but contains no credentials.

Before deploying a fork, choose a rate-limit namespace_id unique to your Cloudflare account in broker/wrangler.jsonc, then run:

cd broker
npm ci
npm run deploy

See the pairing protocol for the request flow and security guarantees.

Releases

GitHub Actions builds the native archives and npm installer from this public repository. npm publication uses a repository-scoped OIDC trusted publisher; no long-lived npm publishing token is stored in GitHub.

To cut a release:

1. Pin a reviewed public Alleycat commit and run cargo update -p alleycat.
2. Review and commit the resulting Cargo.lock.
3. Bump version in Cargo.toml.
4. Dispatch the public Release workflow with tag vX.Y.Z.

License

GPL-3.0-only. See LICENSE.