git clone https://github.com/anbturki/kickd.git
cd kickd
bun install
bun run start

# Tasks
kickd list                              # List all tasks
kickd run <id> [json]                   # Run a task
kickd history <id>                      # Task run history

# Skills
kickd skills                            # List all skills
kickd skill <id> [json]                 # Run a skill

# Workflows
kickd workflow list                     # List workflows
kickd workflow run <id> [json]          # Run a workflow
kickd workflow delete <id>              # Delete a workflow

# Variables
kickd vars list [scope]                 # List variables
kickd vars set <key> <value>            # Set a variable
kickd vars get <key>                    # Get a variable
kickd vars delete <key>                 # Delete a variable

# Credentials
kickd creds list                        # List stored credentials
kickd creds types                       # List available types (github, slack, aws, ...)
kickd creds add <name> <type> <json>    # Store a credential (encrypted)
kickd creds get <name>                  # View credential (sensitive values redacted)
kickd creds test <name>                 # Test connectivity
kickd creds delete <name>              # Delete a credential

# Webhooks
kickd webhook list                      # List webhooks
kickd webhook create <name> task:<id>   # Create a webhook
kickd webhook delete <id>               # Delete a webhook

# Events
kickd events                            # Show recent events
kickd events rules                      # List reactive rules
kickd events add <event> run_task:<id>  # Add a rule

# Notifications
kickd notify add slack <url>            # Add Slack notifications
kickd notify add discord <url>          # Add Discord notifications

# Queue
kickd queue                             # Show queue stats

# Plugins
kickd install <package>                 # Install a plugin from npm
kickd uninstall <package>               # Uninstall a plugin
kickd plugins                           # List installed plugins

# Other
kickd stats                             # Global statistics
kickd health                            # Detailed health report
kickd ask "prompt"                      # Ask Claude Code

{
  "mcpServers": {
    "kickd": {
      "command": "bun",
      "args": ["run", "mcp"],
      "cwd": "/path/to/kickd"
    }
  }
}

// tasks/my-task.ts
import type { Task, TaskResult } from "../src/types";

export const task: Task = {
  id: "my-task",
  name: "My Task",
  description: "Does something useful",
  handler: "tasks/my-task.ts",
  schedule: "0 9 * * MON-FRI", // weekdays at 9am (full cron)
  retry: { maxAttempts: 3, baseDelayMs: 1000, maxDelayMs: 30000, backoffMultiplier: 2 },
  enabled: true,
  status: "idle",
};

export async function handler(params?: Record<string, unknown>): Promise<TaskResult> {
  return { success: true, output: "Done", duration: 0 };
}

// skills/my-skill.ts
import { z } from "zod";
import { skills } from "../src/skills/engine";

skills.register({
  id: "my-skill",
  name: "My Skill",
  description: "A composable unit of work",
  input: z.object({ message: z.string() }),
  output: z.object({ result: z.string() }),
  execute: async (input) => {
    return { result: `Processed: ${input.message}` };
  },
});

curl -X POST http://localhost:7400/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "id": "deploy-pipeline",
    "name": "Deploy Pipeline",
    "description": "Build, test, and deploy",
    "startStep": "build",
    "steps": [
      { "id": "build", "type": "task", "targetId": "build-app", "next": "test" },
      { "id": "test", "type": "task", "targetId": "run-tests", "next": "check" },
      { "id": "check", "type": "condition", "condition": "{{prev.success}} === true", "onTrue": "deploy", "onFalse": "notify-fail" },
      { "id": "deploy", "type": "skill", "targetId": "deploy-prod" },
      { "id": "notify-fail", "type": "skill", "targetId": "send-alert", "input": { "message": "Tests failed" } }
    ]
  }'

# Generate an encryption key
openssl rand -base64 32
# Add to .env: KICKD_ENCRYPTION_KEY=<generated-key>

# Store a GitHub token
kickd creds add my-github github '{"token":"ghp_abc123..."}'

# Store Slack credentials
kickd creds add my-slack slack '{"botToken":"xoxb-...", "webhookUrl":"https://hooks.slack.com/..."}'

# Test connectivity
kickd creds test my-github

# When task "hello" completes, run the "disk-usage" task
kickd events add task.completed run_task:disk-usage --source hello

# When any skill fails, run a notification task
kickd events add skill.failed run_task:alert

# Create a webhook for the "hello" task
kickd webhook create deploy-hook task:hello

# Trigger it (e.g., from GitHub Actions, Stripe, etc.)
curl -X POST http://localhost:7400/hooks/<webhook-id> \
  -H "Content-Type: application/json" \
  -d '{}'

# Via CLI
kickd notify add slack https://hooks.slack.com/services/...
kickd notify add discord https://discord.com/api/webhooks/...

# Or via environment variables
KICKD_NOTIFY_SLACK_URL=https://hooks.slack.com/services/...
KICKD_NOTIFY_DISCORD_URL=https://discord.com/api/webhooks/...

kickd install kickd-skill-example
kickd plugins

cp .env.example .env

docker build -t kickd .
docker run -p 7400:7400 -v kickd-data:/app/data kickd

# Create plist at ~/Library/LaunchAgents/com.kickd.daemon.plist
# then:
launchctl load ~/Library/LaunchAgents/com.kickd.daemon.plist

pm2 start "bun run start" --name kickd
pm2 save

┌──────────────┐    MCP (stdio)    ┌───────────────────────────────────────┐
│  Claude Code │ ────────────────► │            kickd daemon               │
│              │ ◄──────────────── │                                       │
└──────────────┘                   │  ┌───────┐ ┌───────┐ ┌────────────┐  │
                                   │  │ Tasks │ │Skills │ │ Workflows  │  │
┌──────────────┐    HTTP :7400     │  └───┬───┘ └───┬───┘ └──────┬─────┘  │
│   You (CLI)  │ ────────────────► │      │         │            │        │
│              │ ◄──────────────── │  ┌───┴─────────┴────────────┴───┐    │
└──────────────┘                   │  │         Event Bus             │    │
                                   │  └───┬─────────┬───────────┬────┘    │
┌──────────────┐    Webhooks       │  ┌───┴───┐ ┌───┴────┐ ┌───┴──────┐  │
│   External   │ ────────────────► │  │Notify │ │SQLite  │ │Cred Vault│  │
│   Services   │                   │  └───────┘ └────────┘ └──────────┘  │
└──────────────┘                   └───────────────────────────────────────┘