Installation

Install the npm package

Add the SDK to your web application:

npm install @kaoruisaac/pedelec

Import the runtime API from browser-side code:

import { Pedelec, defineTool } from "@kaoruisaac/pedelec";

The package is ESM and includes its TypeScript declaration file. It does not install the Chrome Extension, Desktop App, provider CLIs, or Ollama models.

Optional: use the integration Agent Skill

If you are using a Coding Agent to add Pedelec to a new or existing browser application, choose one of these developer integration paths:

Option A — Skills CLI

npx skills add kaoruisaac/pedelec

Option B — Release bundle

Download pedelec-integration-guideline.zip from the GitHub Releases page, extract it, and tell the Coding Agent to read START_HERE.md. This is a developer integration path, not a runtime prerequisite or an installer for the Pedelec Desktop App or Chrome Extension.

The pedelec-integration skill helps the agent inspect the application, design product tools, implement browser-side SDK and session lifecycle code, and add the connection, approval, Provider / effort, and task-feedback UI that the product needs. Neither option installs the Pedelec Desktop App or Chrome Extension for end users. Continue with the user-side installation below for those runtime prerequisites.

Install the user-side components

The user running your web application needs a compatible set of Pedelec components:

1. Install the Pedelec Desktop App for the target operating system.
2. Start the app so the Core Runtime is available.
3. Confirm that the app has registered the Chrome Native Messaging host.
4. Install and enable the Pedelec Chrome Extension in the same Chrome profile.
5. Install and authenticate at least one provider, or configure Ollama.

Use the official release channel for the Pedelec version your application targets. Keeping the SDK, extension, and desktop runtime reasonably aligned avoids protocol mismatches.

Create the client in browser code

import { Pedelec } from "@kaoruisaac/pedelec";

export function createPedelecClient() {
  if (typeof window === "undefined") {
    throw new Error("Pedelec can only be initialized in the browser.");
  }

  return new Pedelec();
}

Prefer one client instance per page lifecycle. A client owns one extension port and can manage multiple sessions.

Verify the extension

const pedelec = createPedelecClient();
const approval = await pedelec.getApprovalStatus();

if (!approval.installed) {
  throw new Error("The Pedelec extension is unavailable.");
}

console.log("Current origin:", approval.origin);
console.log("Already approved:", approval.approved);

getApprovalStatus() intentionally converts extension-unavailable and extension-disconnected cases into { installed: false, approved: false, origin, appConnected: false }. Other failures may still throw.

Verify the desktop runtime and providers

Use the non-sensitive getApprovalStatus().appConnected for a Desktop connectivity test. listProviders() requires origin approval and is intended for provider selection:

const providers = await pedelec.listProviders();

for (const provider of providers) {
  console.table({
    code: provider.code,
    available: provider.available,
    error: provider.error,
  });
}

if (!providers.some((provider) => provider.available)) {
  throw new Error("No Pedelec provider is currently available.");
}

Interpret failures by layer:

• EXTENSION_UNAVAILABLE: browser-side extension connection is missing.
• NATIVE_HOST_UNAVAILABLE: extension exists but cannot reach the registered host.
• CORE_RUNTIME_UNAVAILABLE or IPC_UNAVAILABLE: the host could not reach Core. It may have attempted a background Desktop launch; open Desktop manually or repair the installation if it remains unavailable.
• available: false: Core is working, but that provider is not ready.

Provider setup notes

CLI-backed providers

The Desktop App must be able to find the executable in its own environment. A command that works in an already-open terminal may still be missing from the environment inherited by a graphical desktop app. Restart the Desktop App after changing PATH.

Authentication is provider-specific. Complete the provider’s normal login or credential setup before creating a session.

Ollama

Pedelec’s Ollama provider uses the bundled pedelec-agent, not the ollama CLI as the provider process. You still need to:

• run an Ollama-compatible server at the default http://127.0.0.1:11434 endpoint or configure another local, remote, or Ollama Cloud endpoint;
• configure its base URL in the Desktop App when it is not the default;
• set the Ollama API key in Desktop Settings. The current agent requires a non-empty value: use ollama for a local server, or the service-issued key for an authenticated remote/Cloud endpoint;
• install the chosen model;
• configure a model in the selected Ollama effort profile; and
• optionally add a Tavily API key to expose Tavily web search to the Ollama model. The current agent uses basic search depth and returns at most five results per call. Without a Tavily key, web search is not exposed.

Next step

Complete the Quick start to create a real session, stream assistant output, and cleanly end the session.