# Quick Start Guide

Get started with planck-claw as a headless API library.

## What is planck-claw?

planck-claw is a **headless API library** for building LLM-powered agents in TypeScript/Node.js. It has no CLI — you import it into your application and drive it programmatically. All LLM calls go through **OpenRouter**.

## Prerequisites

- Node.js >= 18.0.0
- An OpenRouter API key ([get one here](https://openrouter.ai/keys))

## Installation

```bash
npm install planck-claw
```

### From Source

```bash
git clone <repo-url>
cd planck-claw
npm install
npm run build
```

## Basic Usage

```typescript
import { createAgent } from 'planck-claw';

const agent = createAgent({
  providers: {
    openrouter: {
      apiKey: process.env.OPENROUTER_API_KEY,
    },
  },
  agents: {
    defaults: {
      model: 'anthropic/claude-sonnet-4-5',
      temperature: 0.7,
      maxTokens: 4096,
    },
  },
});

const response = await agent.send('What is TypeScript?');
console.log(response);
```

## Configuration

Pass a config object when creating the agent. The config is validated with Zod at startup.

```typescript
const agent = createAgent({
  providers: {
    openrouter: {
      apiKey: 'sk-or-v1-YOUR_KEY_HERE',
    },
  },
  agents: {
    defaults: {
      model: 'anthropic/claude-sonnet-4-5',
      temperature: 0.7,
      maxTokens: 4096,
      systemPrompt: 'You are a helpful coding assistant.',
    },
  },
  tools: {
    restrictToWorkspace: true,
    allowedCommands: ['ls', 'cat', 'grep'],
    deniedCommands: ['rm', 'sudo'],
  },
});
```

### Environment Variables

Set your API key via environment variable:

```bash
export OPENROUTER_API_KEY="sk-or-v1-xxx"
```

## Available Models (via OpenRouter)

OpenRouter gives you access to models from many providers through a single API key:

- `anthropic/claude-opus-4-5` — Most capable
- `anthropic/claude-sonnet-4-5` — Balanced
- `openai/gpt-4-turbo` — GPT-4 Turbo
- `google/gemini-pro-1.5` — Gemini Pro
- `meta-llama/llama-3.1-405b` — Llama 3.1
- `deepseek/deepseek-chat` — DeepSeek

See the full model list at [openrouter.ai/models](https://openrouter.ai/models).

## Adding Skills

Skills are Markdown documents that provide additional context to the agent's system prompt:

```typescript
const agent = createAgent({
  providers: { openrouter: { apiKey: '...' } },
  agents: { defaults: { model: 'anthropic/claude-sonnet-4-5' } },
  skills: [
    { name: 'my-skill', content: '# My Skill\n\nDo X when asked about Y.' },
  ],
});
```

## Custom Channels

planck-claw ships with `BaseChannel` and `ChannelManager` abstractions but no built-in platform adapters. To integrate with a messaging platform:

1. Extend `BaseChannel`
2. Implement `initialize()`, `start()`, `stop()`, `sendMessage()`, `isConnected()`
3. Register your channel with `ChannelManager`

See [ARCHITECTURE.md](ARCHITECTURE.md) for details on the gateway and message bus.

## Troubleshooting

### "No provider configured"

Ensure you pass a valid `providers.openrouter.apiKey` in your config object.

### "Provider API error"

- Verify your OpenRouter API key is correct
- Confirm you have API credits
- Check your internet connection

### Build errors (from source)

```bash
npm run clean && npm install && npm run build
```

## Next Steps

- [Configuration Guide](CONFIGURATION.md) — Full configuration reference
- [Architecture](ARCHITECTURE.md) — System design and internals