profclaw 0.0.1-beta.1

package/README.md

@@ -0,0 +1,196 @@
+<p align="center">
+  <h1 align="center">profClaw</h1>
+  <p align="center">Smart, lightweight AI agent engine. Run locally on anything from a $10 board to a VPS.</p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/profclaw"><img src="https://img.shields.io/npm/v/profclaw?style=for-the-badge&logo=npm&logoColor=white" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=for-the-badge" alt="License: AGPL-3.0"></a>
+  <img src="https://img.shields.io/badge/Node.js-22%2B-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 22+">
+  <a href="https://github.com/profclaw/profclaw/pkgs/container/profclaw"><img src="https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker"></a>
+</p>
+
+<p align="center">
+  <a href="https://profclaw.dev/docs"><b>Docs</b></a> &middot;
+  <a href="https://github.com/profclaw/profclaw/issues"><b>Report Bug</b></a> &middot;
+  <a href="https://discord.gg/profclaw"><b>Discord</b></a>
+</p>
+
+---
+
+profClaw is a local-first AI agent that talks to your tools. Connect it to Slack, Discord, Telegram, or any of 22 supported chat channels. Point it at your GitHub, Jira, or Linear. Give it an AI provider (Anthropic, OpenAI, Ollama, or 30+ others). It handles the rest - executing tasks, managing workflows, and automating your dev life through natural language.
+
+Runs on your machine. Your data stays local. No cloud required.
+
+## Features
+
+| | |
+|---|---|
+| **35 AI providers** | Anthropic, OpenAI, Google, Groq, Ollama, DeepSeek, Bedrock, and more |
+| **22 chat channels** | Slack, Discord, Telegram, WhatsApp, iMessage, Matrix, Teams, and 15 more |
+| **72 built-in tools** | File ops, git, browser automation, cron, web search, canvas, voice |
+| **50 skills** | Coding agent, GitHub issues, Notion, Obsidian, image gen, and more |
+| **MCP server** | Native Model Context Protocol - connect to any MCP-compatible client |
+| **Voice I/O** | STT (Whisper) + TTS (ElevenLabs/OpenAI/system) + Talk Mode |
+| **Plugin SDK** | Build and share third-party plugins via npm or ClawHub |
+| **3 deployment modes** | Pico (~140MB), Mini (~180MB), Pro (full features) |
+
+## Deployment Modes
+
+profClaw scales from a Raspberry Pi to a full production server:
+
+| Mode | What you get | RAM | Best for |
+|------|-------------|-----|----------|
+| **pico** | Agent + tools + chat. No UI. | ~140MB | IoT, home automation, $10 boards |
+| **mini** | + Dashboard, basic cron, 1-2 channels | ~180MB | Personal dev server, VPS |
+| **pro** | + All channels, Redis queues, plugins, sandbox | ~200MB | Teams, production |
+
+Set via `PROFCLAW_MODE=pico|mini|pro` environment variable.
+
+## Quick Start
+
+### npm
+
+```bash
+npx profclaw onboard  # Zero-to-running wizard
+# or
+npm install -g profclaw@latest
+profclaw setup        # Interactive config
+profclaw serve        # Start the agent
+```
+
+### Docker
+
+```bash
+docker run -d \
+  -p 3000:3000 \
+  -e ANTHROPIC_API_KEY=sk-ant-xxx \
+  -e PROFCLAW_MODE=mini \
+  ghcr.io/profclaw/profclaw:latest
+```
+
+### Docker Compose
+
+```bash
+git clone https://github.com/profclaw/profclaw.git
+cd profclaw
+cp .env.example .env    # Add your API key
+docker compose up -d
+```
+
+**Free local AI?** Add Ollama:
+
+```bash
+docker compose --profile ai up -d
+```
+
+### One-liner (macOS/Linux)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/profclaw/profclaw/main/install.sh | bash
+```
+
+## Configuration
+
+The setup wizard (`profclaw setup`) handles everything interactively. Or set environment variables:
+
+```bash
+# AI Provider (pick one)
+ANTHROPIC_API_KEY=sk-ant-xxx
+OPENAI_API_KEY=sk-xxx
+OLLAMA_BASE_URL=http://localhost:11434
+
+# Deployment
+PROFCLAW_MODE=mini          # pico | mini | pro
+PORT=3000                   # HTTP server port
+
+# Optional
+REDIS_URL=redis://localhost:6379   # Required for pro mode
+```
+
+See [`.env.example`](.env.example) for all options.
+
+## Architecture
+
+```
+src/
+  adapters/       AI agent adapters (tool calling, streaming)
+  chat/           Chat engine + execution pipeline
+    providers/    Slack, Discord, Telegram, WhatsApp, WebChat, ...
+    execution/    Tool executor, sandbox, agentic loop
+  core/           Deployment modes, feature flags
+  integrations/   GitHub, Jira, Linear webhooks
+  queue/          BullMQ (pro) + in-memory (pico/mini) task queue
+  providers/      35 AI SDK providers
+  skills/         Skill loader and registry
+  mcp/            MCP server (stdio + SSE)
+  types/          Shared TypeScript types
+
+ui/src/           React 19 + Vite dashboard (mini/pro only)
+skills/           Built-in skill definitions
+```
+
+## AI Providers
+
+35 providers with 90+ model aliases:
+
+| Provider | Models | Local? |
+|----------|--------|--------|
+| Anthropic | Claude 4.x, 3.5 | No |
+| OpenAI | GPT-4o, o1, o3 | No |
+| Google | Gemini 2.x | No |
+| Ollama | Llama, Mistral, Qwen, ... | Yes |
+| AWS Bedrock | Claude, Titan, Llama | No |
+| Groq | Fast inference | No |
+| DeepSeek | V3, R1 | No |
+| Azure OpenAI | GPT-4o | No |
+| xAI | Grok | No |
+| Zhipu AI | GLM-4, GLM-5 | No |
+| Moonshot | Kimi | No |
+| Qwen API | Qwen 2.5 | No |
+| Together | Open models | No |
+| Fireworks | Open models | No |
+| Mistral | Mistral Large, Codestral | No |
+| OpenRouter | Any model | No |
+| Replicate | Open models | No |
+| ... and 18 more | HuggingFace, NVIDIA NIM, Watsonx, Volcengine, etc. | |
+
+## Integrations
+
+| Platform | Features |
+|----------|----------|
+| **GitHub** | Webhooks, OAuth, issue sync, PR automation |
+| **Jira** | Webhooks, OAuth, issue sync, transitions |
+| **Linear** | Webhooks, OAuth, issue sync |
+| **Slack** | Slash commands, DM pairing, thread replies |
+| **Discord** | Bot commands, channel routing |
+| **Telegram** | Bot API, inline commands |
+| **WhatsApp** | Cloud API or Baileys |
+| **WebChat** | Browser-based SSE chat, embeddable widget |
+| **Matrix** | Room-based, Client-Server API |
+| **Google Chat** | Webhook + service account, Cards v2 |
+| **MS Teams** | Bot Framework, Adaptive Cards |
+
+## Development
+
+```bash
+git clone https://github.com/profclaw/profclaw.git
+cd profclaw
+pnpm install
+cp .env.example .env
+pnpm dev
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for our security policy and how to report vulnerabilities.
+
+## Docs & Website
+
+Documentation and marketing site live in a separate repo: [`profclaw-site`](https://github.com/profclaw/profclaw-site)
+
+## License
+
+[AGPL-3.0](LICENSE) -- profclaw contributors, 2024-2026

package/config/agents.yml

@@ -0,0 +1,55 @@
+# AI Agent Definitions
+#
+# Agents are only registered if their required config is present.
+# Set the corresponding environment variables to enable an agent.
+#
+# Supported agent types:
+#   - openclaw: OpenClaw gateway (requires OPENCLAW_BASE_URL + OPENCLAW_GATEWAY_TOKEN)
+#   - claude-code: Claude Code CLI (requires claude CLI installed + CLAUDE_WORKING_DIR)
+#   - ollama: Local LLM via Ollama (requires Ollama running on OLLAMA_BASE_URL)
+#
+# To enable auto-discovery of installed CLIs/services, set:
+#   AUTO_DISCOVER_AGENTS=true or agents.autoDiscover: true in settings.yml
+
+agents:
+  # OpenClaw - Autonomous AI agent via gateway
+  # Required env vars: OPENCLAW_BASE_URL, OPENCLAW_GATEWAY_TOKEN, OPENCLAW_WORKING_DIR
+  - id: openclaw-default
+    type: openclaw
+    enabled: true
+    maxConcurrent: 2
+    priority: 10
+    config:
+      baseUrl: ${OPENCLAW_BASE_URL}
+      token: ${OPENCLAW_GATEWAY_TOKEN}
+      workingDir: ${OPENCLAW_WORKING_DIR}
+    labels: [code, research, sysadmin]
+    taskTypes: [feature, bug_fix, refactor]
+
+  # Claude Code - Local CLI agent
+  # Required env vars: CLAUDE_WORKING_DIR (directory for agent to work in)
+  # Also requires 'claude' CLI to be installed and in PATH
+  - id: claude-code-default
+    type: claude-code
+    enabled: true
+    maxConcurrent: 1
+    priority: 5
+    config:
+      workingDir: ${CLAUDE_WORKING_DIR}
+    labels: [code, research]
+    taskTypes: [feature, bug_fix, code_review]
+
+  # Ollama - Local LLM agent (FREE, no API tokens needed!)
+  # Requires Ollama running: https://ollama.ai
+  # Install: curl -fsSL https://ollama.com/install.sh | sh
+  # Pull model: ollama pull llama3.2
+  - id: ollama-default
+    type: ollama
+    enabled: true
+    maxConcurrent: 2
+    priority: 3
+    config:
+      baseUrl: ${OLLAMA_BASE_URL:-http://localhost:11434}
+      model: ${OLLAMA_MODEL:-llama3.2}
+    labels: [code, research, docs]
+    taskTypes: [feature, bug_fix, documentation, code_review]

package/config/budget.yml

@@ -0,0 +1,15 @@
+# Budget Configuration
+
+budget:
+  dailyLimit: 50.00
+  monthlyLimit: 500.00
+  
+alerts:
+  thresholds:
+    - 50
+    - 80
+    - 90
+    - 100
+  channels:
+    - log
+    # Future: slack, email

package/config/pricing.yml

@@ -0,0 +1,46 @@
+# Model Pricing Configuration
+# Rates are per 1,000,000 tokens in USD
+
+pricing:
+  # Anthropic Models
+  claude-3-5-sonnet:
+    provider: anthropic
+    inputRate: 3.00
+    outputRate: 15.00
+  claude-3-opus:
+    provider: anthropic
+    inputRate: 15.00
+    outputRate: 75.00
+  claude-3-haiku:
+    provider: anthropic
+    inputRate: 0.25
+    outputRate: 1.25
+
+  # OpenAI Models
+  gpt-4o:
+    provider: openai
+    inputRate: 5.00
+    outputRate: 15.00
+  gpt-4-turbo:
+    provider: openai
+    inputRate: 10.00
+    outputRate: 30.00
+  gpt-3.5-turbo:
+    provider: openai
+    inputRate: 0.50
+    outputRate: 1.50
+
+  # Google Models
+  gemini-1.5-pro:
+    provider: google
+    inputRate: 3.50
+    outputRate: 10.50
+  gemini-1.5-flash:
+    provider: google
+    inputRate: 0.35
+    outputRate: 1.05
+
+defaultPricing:
+  provider: other
+  inputRate: 5.00
+  outputRate: 15.00

package/config/settings.yml

@@ -0,0 +1,168 @@
+# General System Settings
+
+# Storage configuration
+# tier: 'local' for persistent SQLite, 'memory' for in-memory (lost on restart)
+storage:
+  tier: local
+  dbPath: ./data/profclaw.db
+
+server:
+  port: 3000
+  cors:
+    origin: "http://localhost:5173"
+  enableCron: true
+
+# Agent auto-discovery
+# When enabled, the system will auto-detect available agents (e.g., claude CLI)
+# Set to false to only use agents explicitly defined in agents.yml
+agents:
+  autoDiscover: false
+
+queue:
+  name: ai-tasks
+  notificationName: ai-task-notifications
+  concurrency: 2
+  notificationConcurrency: 5
+  redis:
+    url: redis://localhost:6379
+  retry:
+    attempts: 3
+    backoff: 5000 # ms
+    type: exponential
+
+integrations:
+  github:
+    enabled: true
+    webhookPath: /webhooks/github
+  jira:
+    enabled: true
+    webhookPath: /webhooks/jira
+  linear:
+    enabled: true
+    webhookPath: /webhooks/linear
+    aiTaskLabel: ai-task
+    aiReviewLabel: ai-review
+
+ai:
+  providers:
+    openai:
+      apiKey: "${OPENAI_API_KEY}"
+      embeddingModel: text-embedding-3-small
+    ollama:
+      baseUrl: http://localhost:11434
+      summaryModel: llama3.2:3b
+      embeddingModel: mxbai-embed-large
+  defaultEmbeddingProvider: openai
+  defaultSummaryProvider: ollama  # 'ollama' for local, 'openai' for cloud, 'auto' for fallback
+
+# =========================================================================
+# SYNC ENGINE CONFIGURATION (Phase 16 - AI-Native Tickets)
+# =========================================================================
+sync:
+  # Global sync settings
+  enabled: false  # Set to true to enable sync
+  intervalMs: 60000  # Sync interval (1 minute)
+  maxRetries: 3
+  retryDelayMs: 1000
+  enableWebhooks: true
+
+  # Conflict resolution strategy
+  # Options: 'local_wins' | 'remote_wins' | 'latest_wins' | 'manual'
+  conflictStrategy: latest_wins
+
+  # Platform configurations
+  # Each platform can be enabled/disabled independently
+  platforms:
+    linear:
+      enabled: false
+      apiKey: "${LINEAR_API_KEY}"
+      teamId: "${LINEAR_TEAM_ID}"  # Optional: specific team, or uses first team
+      syncDirection: bidirectional  # push | pull | bidirectional
+      webhookSecret: "${LINEAR_WEBHOOK_SECRET}"
+
+    github:
+      enabled: false
+      accessToken: "${GITHUB_TOKEN}"
+      owner: "${GITHUB_OWNER}"  # Repository owner
+      repo: "${GITHUB_REPO}"    # Repository name
+      syncDirection: bidirectional
+      webhookSecret: "${GITHUB_WEBHOOK_SECRET}"
+      # Labels to sync (empty = all issues)
+      syncLabels: []
+
+    jira:
+      enabled: false
+      baseUrl: "${JIRA_BASE_URL}"  # e.g., https://yourcompany.atlassian.net
+      email: "${JIRA_EMAIL}"
+      apiToken: "${JIRA_API_TOKEN}"
+      projectKey: "${JIRA_PROJECT_KEY}"
+      syncDirection: bidirectional
+
+    plane:
+      enabled: false
+      baseUrl: "${PLANE_BASE_URL}"
+      apiKey: "${PLANE_API_KEY}"
+      workspaceId: "${PLANE_WORKSPACE_ID}"
+      projectId: "${PLANE_PROJECT_ID}"
+      syncDirection: bidirectional
+
+# =========================================================================
+# SESSION SPAWN CONFIGURATION (Phase 23 - Parallel Agent Sessions)
+# =========================================================================
+# Enables spawning child sessions for parallel work within a conversation.
+# Child sessions can work autonomously on subtasks while parent continues.
+sessionSpawn:
+  # Enable/disable session spawn feature
+  enabled: true
+
+  # Maximum depth of session hierarchy (0 = root only, 3 = up to 3 levels deep)
+  # Environment override: SESSION_SPAWN_MAX_DEPTH
+  maxDepth: ${SESSION_SPAWN_MAX_DEPTH:-3}
+
+  # Maximum children a single session can spawn
+  # Environment override: SESSION_SPAWN_MAX_CHILDREN
+  maxChildrenPerSession: ${SESSION_SPAWN_MAX_CHILDREN:-5}
+
+  # Default token budget for child sessions (root sessions get 5x this)
+  # Environment override: SESSION_SPAWN_DEFAULT_BUDGET
+  defaultBudget: ${SESSION_SPAWN_DEFAULT_BUDGET:-20000}
+
+  # Default max steps (tool calls) for child sessions (root sessions get 5x this)
+  # Environment override: SESSION_SPAWN_DEFAULT_STEPS
+  defaultSteps: ${SESSION_SPAWN_DEFAULT_STEPS:-20}
+
+  # Root session multiplier (root gets N times the child defaults)
+  rootMultiplier: ${SESSION_SPAWN_ROOT_MULTIPLIER:-5}
+
+  # Default message priority (1-10, 10 = highest)
+  defaultMessagePriority: ${SESSION_SPAWN_MESSAGE_PRIORITY:-5}
+
+  # Maximum message priority allowed
+  maxMessagePriority: 10
+
+  # Auto-cleanup settings for old sessions
+  cleanup:
+    # Enable automatic cleanup of old sessions
+    enabled: true
+    # Cleanup interval in milliseconds (default: 1 hour)
+    intervalMs: ${SESSION_SPAWN_CLEANUP_INTERVAL:-3600000}
+    # Delete completed sessions older than this (default: 24 hours)
+    maxAgeMs: ${SESSION_SPAWN_MAX_AGE:-86400000}
+
+# =========================================================================
+# STATUS MAPPING (optional)
+# =========================================================================
+# Status mapping overrides (optional)
+# Use this to customize how profClaw statuses map to external platforms
+statusMapping:
+  # profClaw status -> external platform status
+  # Format: profclaw_status: { platform: external_status }
+  # Uncomment and modify as needed:
+  # backlog:
+  #   linear: Backlog
+  #   github: open
+  #   jira: To Do
+  # in_progress:
+  #   linear: In Progress
+  #   github: open
+  #   jira: In Progress

package/dist/adapters/claude-code.d.ts

@@ -0,0 +1,46 @@
+import type { AgentAdapter, AgentCapability, AgentConfig, AgentHealth } from "../types/agent.js";
+import type { Task, TaskResult } from "../types/task.js";
+/**
+ * Claude Code Agent Adapter
+ *
+ * Executes tasks using the Claude Code CLI (claude command).
+ * This adapter spawns claude processes to execute tasks.
+ *
+ * @see https://claude.ai/claude-code
+ */
+export declare class ClaudeCodeAdapter implements AgentAdapter {
+    readonly type = "claude-code";
+    readonly name = "Claude Code";
+    readonly description = "Anthropic Claude Code CLI - agentic coding assistant";
+    readonly capabilities: AgentCapability[];
+    private readonly claudePath;
+    private readonly workingDir;
+    private readonly timeout;
+    private readonly model;
+    constructor(config: AgentConfig);
+    /**
+     * Check if Claude Code CLI is available
+     */
+    healthCheck(): Promise<AgentHealth>;
+    /**
+     * Execute a task via Claude Code CLI
+     */
+    executeTask(task: Task): Promise<TaskResult>;
+    /**
+     * Build prompt for Claude Code
+     */
+    private buildPrompt;
+    /**
+     * Run a claude command
+     */
+    private runCommand;
+    /**
+     * Extract artifacts from Claude Code output
+     */
+    private extractArtifacts;
+}
+/**
+ * Factory function for creating Claude Code adapters
+ */
+export declare function createClaudeCodeAdapter(config: AgentConfig): AgentAdapter;
+//# sourceMappingURL=claude-code.d.ts.map