🦐 Krill

Open-source agent connectors. Copy & own.

Krill is a CLI that copies API connector files into your project the same way shadcn/ui copies components. It is not a runtime library. You install a connector, the YAML and helper files land in your repo, and your team owns them from that point forward.

What Is Krill?

A Krill connector teaches an AI agent how to talk to an external API. Each connector ships with declarative YAML for reads, actions, and triggers, plus small TypeScript helper files for auth and response transforms. Krill copies those files into your workspace so you can audit, edit, and extend them without lock-in.

Quick Start

npx @krillto/krill init
npx @krillto/krill list
npx @krillto/krill add github gmail
npx @krillto/krill generate --skill

After installation, review the copied connector files under your configured connectors directory and add your credentials to each connector's config.yaml and auth helper.

Why This Model

Installation

Krill targets Node.js 22+ and ships as an ESM CLI.

npm install -D @krillto/krill

Or run it directly with npx:

npx @krillto/krill list

CLI Reference

krill init

Interactive setup for krill.json.

Questions:

1. Connector install directory
2. Agent framework: OpenClaw, Claude Code, or Custom
3. TypeScript or JavaScript
4. Whether to auto-generate connector SKILL.md files

Flags:

• -y, --yes: accept defaults without prompts

krill add <connector...>

Copy one or more connectors from the bundled registry into your workspace.

Examples:

npx @krillto/krill add github
npx @krillto/krill add github gmail twitter

Behavior:

• Reads the nearest krill.json from the current directory or its parents
• Copies YAML and helper files into connectors_dir
• Prompts before overwrite unless --yes is passed
• Updates the installed array in krill.json
• Generates a connector-local SKILL.md when auto_generate_skill is enabled
• Converts .ts helpers to .js for JavaScript projects

Flags:

• -y, --yes: overwrite without prompting

krill list

Print the bundled registry catalog and highlight installed connectors when a krill.json is found.

krill diff <connector>

Compare your local connector files against the bundled upstream version and summarize what changed.

krill generate --skill

Generate a workspace-level SKILL.md from the installed connectors in your project.

krill generate --mcp

Generate krill.mcp.json describing installed connectors in a machine-readable format suitable for MCP-style tooling.

krill.json

Example:

{
  "$schema": "https://krill.to/schema.json",
  "connectors_dir": "./connectors",
  "framework": "openclaw",
  "typescript": true,
  "auto_generate_skill": true,
  "installed": [
    {
      "name": "github",
      "version": "0.1.0",
      "installed_at": "2026-03-13T00:00:00.000Z"
    }
  ]
}

Connector Spec

Each connector lives in its own directory and usually contains:

connector-name/
├── config.yaml
├── reads.yaml
├── actions.yaml
├── triggers.yaml
├── auth.ts
├── transform.ts
├── types.ts
└── README.md

config.yaml

Defines connector metadata, base URL, auth strategy, rate limiting, and default headers.

reads.yaml

Safe, read-only operations. Each read defines:

• description
• method (GET)
• path
• params
• returns

actions.yaml

Mutating operations. Each action defines:

• description
• method (POST, PUT, PATCH, DELETE)
• path
• risk
• params

triggers.yaml

Webhook or event-driven subscriptions that an agent can listen to.

Create A Custom Connector

1. Start from an installed connector or create a new folder under your workspace connector directory.
2. Write config.yaml with the service metadata and auth type.
3. Add your read-only endpoints to reads.yaml.
4. Add write endpoints to actions.yaml with realistic risk levels.
5. Add webhook/event contracts to triggers.yaml.
6. Implement custom auth and response mapping in auth.ts and transform.ts.
7. Run npx @krillto/krill generate --skill to rebuild the workspace skill file.

Contributing

1. Fork the repo.
2. Add or improve connectors under registry/.
3. Update tests and docs when connector counts or command behavior change.
4. Run:

npm install
npm run lint
npm run build
npm test

1. Open a pull request with example usage and any schema updates.

Development Notes

• Runtime: Node.js 22+
• Language: TypeScript with strict mode
• CLI framework: Commander.js
• Build: tsup
• Tests: vitest
• Registry: bundled locally for v1, no remote fetches

Links

• https://krill.to
• https://discord.gg/krill
• https://twitter.com/krillto