squidclaw 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Squidclaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# 🦑 Squidclaw
+
+**AI agent platform — human-like agents for WhatsApp & more.**
+
+Squidclaw lets you create AI agents that feel like real people. They text naturally, remember conversations, learn over time, and work on WhatsApp out of the box.
+
+## Quick Start
+
+```bash
+npm i -g squidclaw
+squidclaw setup
+squidclaw start
+```
+
+That's it. Your AI agent is live.
+
+## Features
+
+- 🧠 **10+ AI Providers** — Claude, GPT-4o, Gemini, Llama, Mistral, local models
+- 📱 **WhatsApp** — Multi-session, pairing code + QR, auto-reconnect
+- 💬 **Human-like behavior** — Message splitting, reactions, emotion detection
+- 🧬 **Soul & Personality** — Each agent has its own identity, tone, and rules
+- 🧠 **Memory** — Short-term conversations + long-term learned facts
+- 📚 **Knowledge Base** — Upload docs, RAG-powered answers
+- 🔄 **Auto-fallback** — Claude down? Auto-switch to GPT-4o or free models
+- 🤝 **Handoff** — Escalate to humans when needed
+- 📊 **Usage tracking** — Tokens, costs, per-agent analytics
+- 💓 **Heartbeat** — Proactive check-ins and scheduled messages
+- 🔗 **Webhooks** — Integrate with any system
+- 📢 **Broadcast** — Bulk messages with rate limiting
+- 🌍 **Bilingual** — Arabic + English with auto-detection
+- 🏢 **Platform mode** — Multi-tenant for SaaS builders
+
+## Supported AI Models
+
+### Paid
+| Provider | Models |
+|----------|--------|
+| Anthropic | Claude Opus 4, Sonnet 4, Haiku 3.5 |
+| OpenAI | GPT-4o, GPT-4o Mini, o3, o4-mini |
+| Google | Gemini 2.5 Pro, 2.5 Flash, 2.0 Flash |
+| Mistral | Large, Medium, Small |
+
+### Free
+| Provider | Models | Notes |
+|----------|--------|-------|
+| Groq | Llama 4 Scout, Maverick | Free tier, very fast |
+| Together | Llama 4 Scout, Maverick | Free $5 credit |
+| Cerebras | Llama 3.3 70B | Free, fastest inference |
+| Ollama | Any local model | Runs on your machine |
+| LM Studio | Any local model | Runs on your machine |
+
+## Commands
+
+```bash
+# Engine
+squidclaw start                     # Start the engine
+squidclaw stop                      # Stop the engine
+squidclaw status                    # Show status
+
+# Agents
+squidclaw agent create              # Create a new agent
+squidclaw agent list                # List all agents
+squidclaw agent chat <id>           # Chat in terminal
+squidclaw agent edit <id>           # Edit agent files
+squidclaw agent delete <id>         # Delete an agent
+
+# Brain / Models
+squidclaw brain list                # Show available models
+squidclaw brain set <model>         # Set default model
+squidclaw brain show                # Show current model
+
+# API Keys
+squidclaw key set <provider> <key>  # Set API key
+squidclaw key test                  # Test connection
+squidclaw key show                  # Show keys (masked)
+squidclaw key remove <provider>     # Remove a key
+
+# Channels
+squidclaw channels login whatsapp   # Connect WhatsApp
+squidclaw channels status           # Show connections
+squidclaw channels logout whatsapp  # Disconnect
+
+# Usage
+squidclaw usage                     # Token usage & costs
+squidclaw stats                     # Detailed analytics
+squidclaw logs                      # View logs
+```
+
+## How It Works
+
+Each agent gets its own soul (personality), memory, and rules:
+
+```
+~/.squidclaw/agents/luna/
+├── SOUL.md          ← who the agent IS
+├── IDENTITY.md      ← name, language, emoji
+├── MEMORY.md        ← long-term learned facts
+├── RULES.md         ← hard boundaries
+└── BEHAVIOR.md      ← behavior config
+```
+
+When a WhatsApp message comes in:
+
+1. **Route** → identify which agent owns this number
+2. **Understand** → detect language, emotion, intent
+3. **Think** → load soul + memory + knowledge → call AI
+4. **Behave** → split into short messages, add reactions
+5. **Reply** → send human-like responses with natural timing
+
+## Platform Mode (for SaaS builders)
+
+Squidclaw can run in multi-tenant mode — one process, many agents, many customers:
+
+```bash
+squidclaw platform init --supabase-url <url> --supabase-key <key>
+```
+
+Perfect for building your own AI agent SaaS on top of Squidclaw.
+
+## REST API
+
+When running, Squidclaw exposes a REST API on port 9500:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Engine health |
+| `GET /api/agents` | List agents |
+| `POST /api/agents` | Create agent |
+| `POST /api/agents/:id/chat` | Chat with agent |
+| `POST /api/agents/:id/whatsapp/pair` | WhatsApp pairing |
+| `GET /api/usage` | Usage stats |
+| `GET /api/handoffs` | Active handoffs |
+| `POST /api/webhooks` | Add webhook |
+
+Full API docs at [squidclaw.dev/docs/api](https://squidclaw.dev/docs/api)
+
+## Requirements
+
+- Node.js 20+
+- Any AI provider API key (or use free models)
+
+## License
+
+MIT
+
+---
+
+Built with 🦑 by [Squidclaw](https://squidclaw.dev)

package/bin/squidclaw.js

@@ -0,0 +1,512 @@
+#!/usr/bin/env node
+
+/**
+ * 🦑 Squidclaw CLI
+ * AI agent platform — human-like agents for WhatsApp & more
+ * https://squidclaw.dev
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const program = new Command();
+
+program
+  .name('squidclaw')
+  .description('🦑 AI agent platform — human-like agents for WhatsApp & more')
+  .version(pkg.version);
+
+// ── Setup ──────────────────────────────────────────────
+program
+  .command('setup')
+  .description('Interactive first-time setup wizard')
+  .action(async () => {
+    const { setup } = await import('../lib/cli/setup.js');
+    await setup();
+  });
+
+// ── Start / Stop / Restart / Status ────────────────────
+program
+  .command('start')
+  .description('Start the Squidclaw engine')
+  .option('-p, --port <port>', 'API port', '9500')
+  .option('-d, --daemon', 'Run as background daemon')
+  .action(async (opts) => {
+    const { start } = await import('../lib/cli/engine-cmd.js');
+    await start(opts);
+  });
+
+program
+  .command('stop')
+  .description('Stop the Squidclaw engine')
+  .action(async () => {
+    const { stop } = await import('../lib/cli/engine-cmd.js');
+    await stop();
+  });
+
+program
+  .command('restart')
+  .description('Restart the Squidclaw engine')
+  .action(async () => {
+    const { restart } = await import('../lib/cli/engine-cmd.js');
+    await restart();
+  });
+
+program
+  .command('status')
+  .description('Show engine status, agents, and connections')
+  .action(async () => {
+    const { status } = await import('../lib/cli/engine-cmd.js');
+    await status();
+  });
+
+// ── Agent Management ───────────────────────────────────
+const agent = program.command('agent').description('Manage agents');
+
+agent
+  .command('create')
+  .description('Create a new agent')
+  .option('-n, --name <name>', 'Agent name')
+  .option('--soul <text>', 'Soul/personality description')
+  .option('-l, --language <lang>', 'Language (en/ar/bilingual)', 'en')
+  .action(async (opts) => {
+    const { createAgent } = await import('../lib/cli/agent-cmd.js');
+    await createAgent(opts);
+  });
+
+agent
+  .command('list')
+  .description('List all agents')
+  .action(async () => {
+    const { listAgents } = await import('../lib/cli/agent-cmd.js');
+    await listAgents();
+  });
+
+agent
+  .command('edit <id>')
+  .description('Edit an agent')
+  .action(async (id) => {
+    const { editAgent } = await import('../lib/cli/agent-cmd.js');
+    await editAgent(id);
+  });
+
+agent
+  .command('delete <id>')
+  .description('Delete an agent')
+  .action(async (id) => {
+    const { deleteAgent } = await import('../lib/cli/agent-cmd.js');
+    await deleteAgent(id);
+  });
+
+agent
+  .command('chat <id>')
+  .description('Chat with an agent in terminal')
+  .action(async (id) => {
+    const { chatAgent } = await import('../lib/cli/agent-cmd.js');
+    await chatAgent(id);
+  });
+
+// ── Brain / Model Management ───────────────────────────
+const brain = program.command('brain').description('Manage AI models');
+
+brain
+  .command('list')
+  .description('List available models')
+  .action(async () => {
+    const { listBrains } = await import('../lib/cli/brain-cmd.js');
+    await listBrains();
+  });
+
+brain
+  .command('set <model>')
+  .description('Set default model')
+  .option('-a, --agent <id>', 'Set for specific agent')
+  .option('-f, --fallback <model>', 'Add fallback model', [])
+  .action(async (model, opts) => {
+    const { setBrain } = await import('../lib/cli/brain-cmd.js');
+    await setBrain(model, opts);
+  });
+
+brain
+  .command('show')
+  .description('Show current model config')
+  .action(async () => {
+    const { showBrain } = await import('../lib/cli/brain-cmd.js');
+    await showBrain();
+  });
+
+// ── API Key Management ─────────────────────────────────
+const key = program.command('key').description('Manage API keys');
+
+key
+  .command('set <provider> <apiKey>')
+  .description('Set API key for a provider')
+  .action(async (provider, apiKey) => {
+    const { setKey } = await import('../lib/cli/key-cmd.js');
+    await setKey(provider, apiKey);
+  });
+
+key
+  .command('test')
+  .description('Test current API key')
+  .option('-p, --provider <provider>', 'Test specific provider')
+  .action(async (opts) => {
+    const { testKey } = await import('../lib/cli/key-cmd.js');
+    await testKey(opts);
+  });
+
+key
+  .command('show')
+  .description('Show configured keys (masked)')
+  .action(async () => {
+    const { showKeys } = await import('../lib/cli/key-cmd.js');
+    await showKeys();
+  });
+
+key
+  .command('remove <provider>')
+  .description('Remove an API key')
+  .action(async (provider) => {
+    const { removeKey } = await import('../lib/cli/key-cmd.js');
+    await removeKey(provider);
+  });
+
+// ── Channel Management ─────────────────────────────────
+const channels = program.command('channels').description('Manage messaging channels');
+
+channels
+  .command('login <channel>')
+  .description('Connect a channel (whatsapp, telegram)')
+  .option('-a, --agent <id>', 'Agent to connect')
+  .option('-m, --method <method>', 'Login method (pairing/qr)', 'pairing')
+  .action(async (channel, opts) => {
+    const { loginChannel } = await import('../lib/cli/channels-cmd.js');
+    await loginChannel(channel, opts);
+  });
+
+channels
+  .command('status')
+  .description('Show channel connection status')
+  .action(async () => {
+    const { channelStatus } = await import('../lib/cli/channels-cmd.js');
+    await channelStatus();
+  });
+
+channels
+  .command('logout <channel>')
+  .description('Disconnect a channel')
+  .option('-a, --agent <id>', 'Agent to disconnect')
+  .action(async (channel, opts) => {
+    const { logoutChannel } = await import('../lib/cli/channels-cmd.js');
+    await logoutChannel(channel, opts);
+  });
+
+// ── Memory Management ──────────────────────────────────
+const memory = program.command('memory').description('Manage agent memory');
+
+memory
+  .command('show <agentId>')
+  .description('Show agent memory')
+  .action(async (agentId) => {
+    const { showMemory } = await import('../lib/cli/memory-cmd.js');
+    await showMemory(agentId);
+  });
+
+memory
+  .command('clear <agentId>')
+  .description('Clear agent memory')
+  .option('--confirm', 'Skip confirmation')
+  .action(async (agentId, opts) => {
+    const { clearMemory } = await import('../lib/cli/memory-cmd.js');
+    await clearMemory(agentId, opts);
+  });
+
+memory
+  .command('export <agentId>')
+  .description('Export agent memory to file')
+  .option('-o, --output <path>', 'Output file path')
+  .action(async (agentId, opts) => {
+    const { exportMemory } = await import('../lib/cli/memory-cmd.js');
+    await exportMemory(agentId, opts);
+  });
+
+// ── Knowledge Base ─────────────────────────────────────
+const knowledge = program.command('knowledge').description('Manage knowledge base');
+
+knowledge
+  .command('upload <file>')
+  .description('Upload a document to knowledge base')
+  .option('-a, --agent <id>', 'Target agent')
+  .action(async (file, opts) => {
+    const { uploadKnowledge } = await import('../lib/cli/knowledge-cmd.js');
+    await uploadKnowledge(file, opts);
+  });
+
+knowledge
+  .command('list')
+  .description('List knowledge base documents')
+  .option('-a, --agent <id>', 'Filter by agent')
+  .action(async (opts) => {
+    const { listKnowledge } = await import('../lib/cli/knowledge-cmd.js');
+    await listKnowledge(opts);
+  });
+
+knowledge
+  .command('delete <docId>')
+  .description('Delete a document')
+  .action(async (docId) => {
+    const { deleteKnowledge } = await import('../lib/cli/knowledge-cmd.js');
+    await deleteKnowledge(docId);
+  });
+
+// ── Usage & Stats ──────────────────────────────────────
+program
+  .command('usage')
+  .description('Show token usage and costs')
+  .option('-a, --agent <id>', 'Filter by agent')
+  .option('-p, --period <period>', 'Time period (7d/30d/all)', '30d')
+  .action(async (opts) => {
+    const { showUsage } = await import('../lib/cli/stats-cmd.js');
+    await showUsage(opts);
+  });
+
+program
+  .command('stats')
+  .description('Show detailed analytics')
+  .option('-a, --agent <id>', 'Filter by agent')
+  .option('-p, --period <period>', 'Time period (7d/30d/all)', '7d')
+  .action(async (opts) => {
+    const { showStats } = await import('../lib/cli/stats-cmd.js');
+    await showStats(opts);
+  });
+
+program
+  .command('logs')
+  .description('Show engine logs')
+  .option('-a, --agent <id>', 'Filter by agent')
+  .option('-n, --lines <n>', 'Number of lines', '50')
+  .option('-f, --follow', 'Follow log output')
+  .action(async (opts) => {
+    const { showLogs } = await import('../lib/cli/stats-cmd.js');
+    await showLogs(opts);
+  });
+
+// ── Broadcast ──────────────────────────────────────────
+const broadcast = program.command('broadcast').description('Send broadcast messages');
+
+broadcast
+  .command('send')
+  .description('Send a broadcast message')
+  .requiredOption('-a, --agent <id>', 'Agent to send from')
+  .requiredOption('-m, --message <text>', 'Message to send')
+  .option('-g, --group <group>', 'Target group')
+  .action(async (opts) => {
+    const { sendBroadcast } = await import('../lib/cli/broadcast-cmd.js');
+    await sendBroadcast(opts);
+  });
+
+// ── Handoff ────────────────────────────────────────────
+const handoff = program.command('handoff').description('Manage human handoffs');
+
+handoff
+  .command('list')
+  .description('List pending handoffs')
+  .action(async () => {
+    const { listHandoffs } = await import('../lib/cli/handoff-cmd.js');
+    await listHandoffs();
+  });
+
+handoff
+  .command('resolve <id>')
+  .description('Resolve a handoff (hand back to agent)')
+  .action(async (id) => {
+    const { resolveHandoff } = await import('../lib/cli/handoff-cmd.js');
+    await resolveHandoff(id);
+  });
+
+// ── Business Hours ─────────────────────────────────────
+const hours = program.command('hours').description('Manage business hours');
+
+hours
+  .command('set <schedule>')
+  .description('Set business hours (e.g. "sun-thu 9:00-18:00")')
+  .option('-a, --agent <id>', 'Agent')
+  .option('-t, --timezone <tz>', 'Timezone', 'UTC')
+  .action(async (schedule, opts) => {
+    const { setHours } = await import('../lib/cli/hours-cmd.js');
+    await setHours(schedule, opts);
+  });
+
+hours
+  .command('show')
+  .description('Show business hours')
+  .option('-a, --agent <id>', 'Agent')
+  .action(async (opts) => {
+    const { showHours } = await import('../lib/cli/hours-cmd.js');
+    await showHours(opts);
+  });
+
+hours
+  .command('off')
+  .description('Set 24/7 mode (no business hours)')
+  .option('-a, --agent <id>', 'Agent')
+  .action(async (opts) => {
+    const { setAlwaysOn } = await import('../lib/cli/hours-cmd.js');
+    await setAlwaysOn(opts);
+  });
+
+// ── Webhook ────────────────────────────────────────────
+const webhook = program.command('webhook').description('Manage webhooks');
+
+webhook
+  .command('add <url>')
+  .description('Add a webhook endpoint')
+  .action(async (url) => {
+    const { addWebhook } = await import('../lib/cli/webhook-cmd.js');
+    await addWebhook(url);
+  });
+
+webhook
+  .command('list')
+  .description('List webhooks')
+  .action(async () => {
+    const { listWebhooks } = await import('../lib/cli/webhook-cmd.js');
+    await listWebhooks();
+  });
+
+webhook
+  .command('remove <id>')
+  .description('Remove a webhook')
+  .action(async (id) => {
+    const { removeWebhook } = await import('../lib/cli/webhook-cmd.js');
+    await removeWebhook(id);
+  });
+
+// ── Config ─────────────────────────────────────────────
+const config = program.command('config').description('Manage configuration');
+
+config
+  .command('get [key]')
+  .description('Get config value')
+  .action(async (key) => {
+    const { getConfig } = await import('../lib/cli/config-cmd.js');
+    await getConfig(key);
+  });
+
+config
+  .command('set <key> <value>')
+  .description('Set config value')
+  .action(async (key, value) => {
+    const { setConfig } = await import('../lib/cli/config-cmd.js');
+    await setConfig(key, value);
+  });
+
+config
+  .command('edit')
+  .description('Open config in editor')
+  .action(async () => {
+    const { editConfig } = await import('../lib/cli/config-cmd.js');
+    await editConfig();
+  });
+
+// ── Conversations ──────────────────────────────────────
+const conversations = program.command('conversations').description('Manage conversations');
+
+conversations
+  .command('list')
+  .description('List recent conversations')
+  .option('-a, --agent <id>', 'Filter by agent')
+  .option('-n, --limit <n>', 'Limit results', '20')
+  .action(async (opts) => {
+    const { listConversations } = await import('../lib/cli/conversations-cmd.js');
+    await listConversations(opts);
+  });
+
+conversations
+  .command('search <query>')
+  .description('Search conversations')
+  .option('-a, --agent <id>', 'Filter by agent')
+  .action(async (query, opts) => {
+    const { searchConversations } = await import('../lib/cli/conversations-cmd.js');
+    await searchConversations(query, opts);
+  });
+
+conversations
+  .command('export')
+  .description('Export conversations')
+  .option('-a, --agent <id>', 'Filter by agent')
+  .option('-f, --format <format>', 'Export format (csv/json)', 'json')
+  .option('-o, --output <path>', 'Output file')
+  .action(async (opts) => {
+    const { exportConversations } = await import('../lib/cli/conversations-cmd.js');
+    await exportConversations(opts);
+  });
+
+// ── Platform Mode ──────────────────────────────────────
+const platform = program.command('platform').description('Platform integration (multi-tenant)');
+
+platform
+  .command('init')
+  .description('Initialize platform mode')
+  .option('--supabase-url <url>', 'Supabase project URL')
+  .option('--supabase-key <key>', 'Supabase service role key')
+  .action(async (opts) => {
+    const { initPlatform } = await import('../lib/cli/platform-cmd.js');
+    await initPlatform(opts);
+  });
+
+platform
+  .command('agents')
+  .description('List all platform agents')
+  .action(async () => {
+    const { platformAgents } = await import('../lib/cli/platform-cmd.js');
+    await platformAgents();
+  });
+
+platform
+  .command('usage')
+  .description('Platform-wide usage stats')
+  .action(async () => {
+    const { platformUsage } = await import('../lib/cli/platform-cmd.js');
+    await platformUsage();
+  });
+
+// ── Update ─────────────────────────────────────────────
+program
+  .command('update')
+  .description('Update Squidclaw to latest version')
+  .action(async () => {
+    const { update } = await import('../lib/cli/update-cmd.js');
+    await update();
+  });
+
+// ── Splash ─────────────────────────────────────────────
+if (process.argv.length <= 2) {
+  console.log(chalk.cyan(`
+  🦑 Squidclaw v${pkg.version}
+  AI agent platform — human-like agents for WhatsApp & more
+  
+  ${chalk.gray('Get started:')}  squidclaw setup
+  ${chalk.gray('Help:')}         squidclaw --help
+  ${chalk.gray('Docs:')}         https://squidclaw.dev
+  `));
+  process.exit(0);
+}
+
+program.parse();
+
+// ── TUI ────────────────────────────────────────────────
+program
+  .command('tui')
+  .description('Open terminal chat UI')
+  .option('-a, --agent <id>', 'Start with specific agent')
+  .action(async (opts) => {
+    const { tui } = await import('../lib/cli/tui.js');
+    await tui(opts);
+  });