npm package: @krillto/krill
Description: Open-source agent connectors. Copy & own.
Latest version: 0.1.0

# 🦐 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

```bash
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

| Tool | Ownership model | Runtime dependency | Best for |
| --- | --- | --- | --- |
| Krill | Copy files into your repo | No | Teams that want editable agent connectors |
| Zapier MCP | Hosted integration surface | Yes | Quick access to a large SaaS catalog |
| AgentGate | Managed gateway | Yes | Centralized policy and hosted orchestration |
| Peta | Platform-defined connectors | Usually | Teams buying into a broader agent platform |

## Installation

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

```bash
npm install -D @krillto/krill
```

Or run it directly with `npx`:

```bash
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:

```bash
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:

```json
{
  "$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:

```text
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:

```bash
npm install
npm run lint
npm run build
npm test
```

5. 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