crewx 0.8.0-rc.9 → 0.8.0-rc.91

package/README.md

@@ -1,300 +1,268 @@
-# SowonAI CrewX
+# CrewX
 
-> Bring Your Own AI(BYOA) team in Slack/IDE(MCP) with your existing subscriptions
+> Build your AI agent team — bring any model, orchestrate any workflow
 
-Transform Claude, Gemini, Codex and Copilot into a collaborative development team. No extra costs—just your existing AI subscriptions working together.
+[![npm version](https://img.shields.io/npm/v/crewx)](https://www.npmjs.com/package/crewx)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/license-see%20below-blue)](#license)
 
-![CrewX usage overview](docs/diagram1.svg)
+## What is CrewX?
 
-## Why CrewX?
+CrewX is a developer tool for building and managing AI agent teams. Define agents in YAML, wire them into workflows, and let them collaborate using built-in tools — all from a single CLI or web dashboard.
 
-### **Slack Team Collaboration** - Your AI Team in Slack
-Bring AI agents directly into your team's workspace:
-- **Team-wide AI access** - Everyone benefits from AI expertise in Slack channels
-- **Thread-based context** - Maintains conversation history automatically
-- **Multi-agent collaboration** - `@claude`, `@gemini`, `@copilot` work together in real-time
-- **Natural integration** - Works like chatting with team members
-- **Shared knowledge** - Team learns from AI interactions, not isolated sessions
-
-### **Remote Agents** - Distributed AI Teams
-Connect and orchestrate CrewX instances across projects and servers:
-- **Cross-project experts** - Frontend dev asks backend team's API specialist agent
-- **Team collaboration** - Each team builds their own agents, entire org can use them
-- **Expert knowledge sharing** - Ask senior's code review agent, security team's audit agent anytime
-- **Separate but connected** - Each project keeps its own context, collaborate when needed
-
-```yaml
-# Access another project's specialized agents
-providers:
-  - id: backend_project
-    type: remote
-    location: "file:///workspace/backend-api/crewx.yaml"
-    external_agent_id: "api_expert"
-
-# Use their expertise in your project
-crewx query "@api_expert design user authentication API"
-crewx execute "@api_expert implement OAuth flow"
-```
-
-### **Plugin Provider System** - Universal AI Integration
-Transform any CLI tool or AI service into an agent:
-- **Bring Your Own AI** - OpenAI, Anthropic, Ollama, LiteLLM, or any AI service
-- **Bring Your Own Tools** - jq, curl, ffmpeg, or any CLI tool becomes an agent
-- **Bring Your Own Framework** - Integrate LangChain, CrewAI, AutoGPT seamlessly
-- **No coding required** - Simple YAML configuration
-- **Mix and match** - Combine different AI services in one workflow
-
-```yaml
-# Example: Add any AI service as a plugin
-providers:
-  - id: ollama
-    type: plugin
-    cli_command: ollama
-    default_model: "llama3"
-    query_args: ["run", "{model}"]
-    prompt_in_args: false
-
-agents:
-  - id: "local_llama"
-    provider: "plugin/ollama"
-```
-
-### Other Benefits
-- **No additional costs** - Use existing Claude Pro, Gemini, Codex or GitHub Copilot subscriptions
-- **Multi-agent collaboration** - Different AI models working on specialized tasks
-- **Parallel execution** - Multiple agents working simultaneously
-- **Flexible integration** - CLI, MCP server, or Slack bot
+- **Bring Your Own AI** — Claude, Gemini, Copilot, Codex, or any OpenAI-compatible model
+- **One command to start** — `npx crewx` launches everything
+- **Team orchestration** — agents work together through threads, workflows, and shared memory
 
 ## Quick Start
 
 ```bash
-# Install
-npm install -g crewx
-
-# Initialize
-crewx init
-
-# Check system
-crewx doctor
-
-# Try it out
-crewx query "@claude analyze my code"
-crewx execute "@claude create a login component"
+npx crewx
 ```
 
-## Three Ways to Use
+That's it. This launches the CrewX dashboard at `http://localhost:8150` where you can manage agents, create threads, and monitor workflows.
+
+### Initialize a new project
 
-### Slack Mode - Team Collaboration (Recommended)
 ```bash
-# Start CrewX in your Slack workspace (read-only query mode)
-crewx slack
+npx crewx init
+```
 
-# Allow agents to run execute tasks (file changes, migrations, etc.)
-crewx slack --mode execute
+This creates a `crewx.yaml` in your project with default agents and settings.
 
-# Your team can now:
-# - @mention AI agents in channels
-# - Maintain context in threads
-# - Share AI insights with the whole team
-```
-👉 **[Complete Slack Setup Guide →](../../docs/slack-install.md)**
+### Talk to your agents
 
-### CLI Mode - Direct terminal usage
 ```bash
-crewx query "@claude review this code"
-crewx execute "@gemini optimize performance"
-crewx query "@claude @gemini @copilot compare approaches"
-```
+# Ask a question (query mode)
+npx crewx q "@claude review this codebase"
 
-### MCP Server Mode - IDE integration
-```bash
-crewx mcp  # VS Code, Claude Desktop, Cursor
-```
+# Execute a task (agents can edit files)
+npx crewx x "@copilot implement login component"
 
-## Supported AI Tools
+# Multi-agent collaboration
+npx crewx q "@claude @gemini compare approaches for caching"
+```
 
-- **Claude Code** - Advanced reasoning and analysis
-- **Gemini CLI** - Real-time web access
-- **GitHub Copilot CLI** - Specialized coding assistant
-- **Codex CLI** - Open inference with workspace-aware execution
+## Key Features
 
-## Basic Usage
+### BYOA (Bring Your Own AI)
 
-```bash
-# Read-only analysis
-crewx query "@claude explain this function"
+Use your existing AI subscriptions — or run fully local with Ollama. No vendor lock-in.
 
-# File creation/modification
-crewx execute "@claude implement user authentication"
+| Provider | CLI | Status |
+|----------|-----|--------|
+| Claude | `claude` | Supported |
+| Gemini | `gemini` | Supported |
+| GitHub Copilot | `copilot` | Supported |
+| Codex | `codex` | Supported |
+| Ollama (local LLM) | API provider | Supported |
+| OpenAI-compatible | API provider | Supported |
 
-# Parallel tasks
-crewx execute "@claude create tests" "@gemini write docs"
+Build a **fully local AI team** with Ollama — no cloud, no API costs, complete data privacy. Mix and match cloud and local models in the same team.
 
-# Pipeline workflows
-crewx query "@architect design API" | \
-crewx execute "@backend implement it"
+### Agent Teams
 
-# Thread-based conversations
-crewx query "@claude design login" --thread "auth-feature"
-crewx execute "@gemini implement it" --thread "auth-feature"
+Define your team in `crewx.yaml`:
 
-# Codex CLI agent
-crewx query "@codex draft a release checklist"
+```yaml
+agents:
+  - id: reviewer
+    name: Code Reviewer
+    provider: cli/claude
+    inline:
+      model: claude-sonnet-4-6
+      prompt: |
+        You are a senior code reviewer.
+        Focus on correctness, performance, and security.
+
+  - id: implementer
+    name: Implementer
+    provider: cli/copilot
+    inline:
+      prompt: |
+        You are a full-stack developer.
+        Write clean, tested code following project conventions.
 ```
 
-Built-in CLI providers:
-
-- `cli/claude`
-- `cli/gemini`
-- `cli/copilot`
-- `cli/codex`
+### Thread Conversations
 
-## Create Custom Agents
+Thread-based conversations keep context across multiple interactions. Agents remember previous messages and can build on each other's work.
 
 ```bash
-# Let SowonAI CrewX create agents for you
-crewx execute "@crewx Create a Python expert agent"
-crewx execute "@crewx Create a React specialist with TypeScript"
-crewx execute "@crewx Create a DevOps agent for Docker"
+# Start a thread
+npx crewx q "@reviewer review PR #42" --thread="pr-42-review"
 
-# Test your new agent
-crewx query "@python_expert Review my code"
+# Continue the conversation
+npx crewx q "@implementer fix the issues found" --thread="pr-42-review"
 ```
 
-## Agent Configuration
+### Semantic Workflows
 
-Create `crewx.yaml` (or `agents.yaml` for backward compatibility):
+Define agent collaboration as semantic workflow YAML — branching, parallel execution, approval gates, and loops:
 
 ```yaml
-agents:
-  - id: "frontend_dev"
-    name: "React Expert"
-    provider: "cli/claude"  # Built-in CLI provider
-    working_directory: "./src"
-    inline:
-      type: "agent"
-      system_prompt: |
-        You are a senior React developer.
-        Provide detailed examples and best practices.
+# workflows/code-review.yaml
+workflows:
+  code-review:
+    metadata:
+      name: "Code Review Workflow"
+    nodes:
+      review:
+        type: agent_task
+        agent: reviewer
+        mode: query
+        input: "Review the latest changes for bugs and security issues"
+        output: review_result
+        next: fix
+
+      fix:
+        type: agent_task
+        agent: implementer
+        mode: execute
+        input: "Fix the issues found: {{review_result}}"
+        next: end
+
+      end:
+        type: end
 ```
 
-> **Note:** `crewx.yaml` is the preferred configuration file name. The legacy `agents.yaml` is still supported for backward compatibility. If both files exist, `crewx.yaml` takes priority.
+### Built-in Tools
 
-## Remote Agents
+Each tool is a standalone npm package — install individually or use all out of the box:
 
-Connect to other CrewX instances and delegate tasks across projects or servers.
+| Package | npm | Description |
+|---------|-----|-------------|
+| `@crewx/memory` | [![npm](https://img.shields.io/npm/v/@crewx/memory)](https://www.npmjs.com/package/@crewx/memory) | Persistent agent memory (markdown + frontmatter) |
+| `@crewx/doc` | [![npm](https://img.shields.io/npm/v/@crewx/doc)](https://www.npmjs.com/package/@crewx/doc) | Document TOC extraction and section reader |
+| `@crewx/search` | [![npm](https://img.shields.io/npm/v/@crewx/search)](https://www.npmjs.com/package/@crewx/search) | BM25 full-text code/document search |
+| `@crewx/cron` | [![npm](https://img.shields.io/npm/v/@crewx/cron)](https://www.npmjs.com/package/@crewx/cron) | Scheduled task execution |
+| `@crewx/wbs` | [![npm](https://img.shields.io/npm/v/@crewx/wbs)](https://www.npmjs.com/package/@crewx/wbs) | Work breakdown structure management |
+| `@crewx/workflow` | [![npm](https://img.shields.io/npm/v/@crewx/workflow)](https://www.npmjs.com/package/@crewx/workflow) | Semantic workflow engine (branch, parallel, approval) |
+| `@crewx/skill` | [![npm](https://img.shields.io/npm/v/@crewx/skill)](https://www.npmjs.com/package/@crewx/skill) | Reusable skill system (Claude Code compatible) |
+| `@crewx/knowledge-core` | [![npm](https://img.shields.io/npm/v/@crewx/knowledge-core)](https://www.npmjs.com/package/@crewx/knowledge-core) | Knowledge graph engine |
+| `@crewx/shared` | [![npm](https://img.shields.io/npm/v/@crewx/shared)](https://www.npmjs.com/package/@crewx/shared) | Shared utilities for built-in tools |
 
-**Quick Example:**
-```bash
-# Add a remote CrewX instance
-providers:
-  - id: backend_server
-    type: remote
-    location: "http://api.example.com:3000"
-    external_agent_id: "backend_team"
+### Desktop & Server
 
-agents:
-  - id: "remote_backend"
-    provider: "remote/backend_server"
+- **Web Dashboard** — `npx crewx` serves a full management UI
+- **Electron Desktop App** — native app with the same features
+- **MCP Server** — JSON-RPC 2.0 endpoint for IDE integration (Claude Code, Cursor, etc.)
 
-# Use it like any other agent
-crewx query "@remote_backend check API status"
-```
+## Use Cases
 
-**Use Cases:**
-- **Project isolation** - Separate configurations for different codebases
-- **Distributed teams** - Each team runs their own CrewX with specialized agents
-- **Resource sharing** - Access powerful compute resources remotely
-- **Multi-project coordination** - Orchestrate work across multiple projects
+### Development Workflow Automation
+Set up AI-powered code review, testing, and deployment pipelines. Multiple agents handle different stages of your development process.
 
-👉 **[Remote Agents Guide →](./docs/remote-agents.md)** for detailed setup and configuration
+### Team Productivity
+Distribute tasks across specialized agents. A reviewer checks code quality while an implementer writes features — in parallel.
 
-## Monorepo Architecture
+### AI-Powered Business Automation
+Build agent teams that handle business processes end-to-end. From customer research to content generation, agents collaborate through workflows and shared knowledge.
 
-SowonAI CrewX is structured as a monorepo with separate packages for maximum flexibility:
+## Supported Providers
 
-```
-crewx/
-├── packages/
-│   ├── sdk/          # @sowonai/crewx-sdk (Apache-2.0)
-│   │   ├── Core AI provider interfaces
-│   │   ├── Conversation management
-│   │   ├── Knowledge utilities
-│   │   └── Agent domain types
-│   └── cli/          # crewx (MIT)
-│       ├── CLI implementation
-│       ├── Slack integration
-│       ├── MCP server
-│       └── Provider implementations
-├── docs/             # Comprehensive documentation
-└── README.md         # This file
-```
+### CLI Providers
+Use AI tools you already have installed:
 
-### Package Overview
+| Provider | CLI | Notes |
+|----------|-----|-------|
+| Claude (Anthropic) | `claude` | Complex reasoning, system design |
+| Gemini (Google) | `gemini` | Research, data analysis |
+| GitHub Copilot | `copilot` | Code generation |
+| Codex (OpenAI) | `codex` | General-purpose coding |
 
-| Package | License | Description | Install |
-|---------|---------|-------------|---------|
-| `@sowonai/crewx-sdk` | Apache-2.0 | Core SDK for building custom AI integrations | `npm install @sowonai/crewx-sdk` |
-| `crewx` | MIT | Full-featured CLI tool for immediate use | `npm install -g crewx` |
+### API Providers
+Connect any API-compatible model — including local LLMs:
 
-**When to use what:**
-- **Use `crewx` CLI** if you want to use AI agents immediately in your terminal, Slack, or IDE
-- **Use `@sowonai/crewx-sdk`** if you're building custom AI tools or integrating SowonAI CrewX into your application
+| Provider | Type | Notes |
+|----------|------|-------|
+| Ollama | Local LLM | Run fully local — zero cloud, zero cost, full privacy |
+| OpenAI API | Cloud API | GPT-4o, o1, etc. |
+| OpenAI-compatible | Cloud/Local | Any endpoint following OpenAI API spec |
 
-### Development
+Mix CLI and API providers in the same team. For example, Claude for planning + Ollama for execution — best of both worlds.
 
-```bash
-# Install dependencies
-npm install
+## Requirements
+
+- **Node.js** >= 22 (required by Copilot CLI provider)
+- **OS**: macOS, Windows, or Linux
+- At least one AI CLI installed: `claude`, `gemini`, `copilot`, or `codex`
+
+## Configuration
 
-# Build all packages
-npm run build
+### Minimal `crewx.yaml`
 
-# Run tests
-npm test
+```yaml
+agents:
+  - id: assistant
+    provider: cli/claude
+    inline:
+      prompt: "You are a helpful coding assistant."
+```
+
+### Full example with skills and workflows
+
+```yaml
+skills:
+  paths:
+    - ./skills          # Custom skill directory
 
-# Build specific package
-npm run build --workspace @sowonai/crewx-sdk
-npm run build --workspace crewx
+agents:
+  - id: lead
+    name: Tech Lead
+    provider: cli/claude
+    skills:
+      include:
+        - code-reviewer
+        - api-designer
+    inline:
+      model: claude-opus-4-6
+      prompt: |
+        You are a tech lead responsible for architecture decisions
+        and code quality.
+
+  - id: dev
+    name: Developer
+    provider: cli/copilot
+    inline:
+      prompt: |
+        You are a full-stack developer.
+        Follow the tech lead's guidance.
 ```
 
-For more information, see:
-- [SDK Development Guide](packages/sdk/README.md)
-- [CLI Development Guide](packages/cli/README.md)
-- [Build & Release Guide](BUILD.md)
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx crewx` | Launch web dashboard |
+| `npx crewx init` | Initialize project with `crewx.yaml` |
+| `npx crewx q "@agent message"` | Query an agent (read-only) |
+| `npx crewx x "@agent message"` | Execute a task (can edit files) |
+| `npx crewx agent list` | List configured agents |
+| `npx crewx doctor` | Check system health |
+| `npx crewx skill list` | List available skills |
+| `npx crewx workflow list` | List workflows |
+| `npx crewx memory index <agent>` | View agent memory |
+| `npx crewx search "query"` | Full-text search |
 
 ## Documentation
 
-### User Guides
-- [📖 CLI Guide](docs/cli-guide.md) - Complete CLI reference
-- [🔌 MCP Integration](docs/mcp-integration.md) - IDE setup and MCP servers
-- [⚙️ Agent Configuration](docs/agent-configuration.md) - Custom agents and advanced config
-- [🌐 Remote Agents](docs/remote-agents.md) - Connect to remote CrewX instances
-- [📚 Template System](docs/templates.md) - Knowledge management and dynamic prompts for agents
-- [📝 Template Variables](docs/template-variables.md) - Dynamic variables in agent configurations
-- [🔧 Tool System](docs/tools.md) - Tool integration and creation guide
-- [🔧 Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
-- [💬 Slack Integration](../../docs/slack-install.md) - Slack bot setup
-
-### Developer Guides
-- [🏗️ SDK API Reference](packages/sdk/README.md) - Build custom integrations
-- [⚙️ CLI Development](packages/cli/README.md) - CLI architecture and development
-- [📦 Build & Release](BUILD.md) - Building and releasing packages
-- [🔧 Development Workflow](docs/development.md) - Contributing guidelines
+- **Web Dashboard**: Launch with `npx crewx` and explore at `http://localhost:8150`
+- **API Reference**: Swagger UI available at `http://localhost:8150/api/docs`
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## License
 
-- **SDK** (`@sowonai/crewx-sdk`): Apache-2.0 License
-- **CLI** (`crewx`): MIT License
-
-Copyright (c) 2025 SowonLabs
-
-## Contributing
+CrewX is built on an open-source CLI engine:
 
-We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting pull requests.
+| Component | License | Notes |
+|-----------|---------|-------|
+| CLI Engine + SDK | Apache-2.0 | Open source — [sowonlabs/crewx](https://github.com/sowonlabs/crewx) |
+| Built-in Tools (`@crewx/*`) | Proprietary | Free to use via npm, source not published |
+| Web UI + Server | Proprietary | Included in this package |
 
-For SDK contributions, please sign our [Contributor License Agreement (CLA)](docs/CLA.md).
+The open-source CLI ([sowonlabs/crewx](https://github.com/sowonlabs/crewx)) is the foundation of this project. New CLI features are developed here first and periodically contributed back to the open-source repository.
 
 ---
 
-Built by [SowonLabs](https://github.com/sowonlabs)
+**[SowonLabs](https://sowonlabs.com)** | [GitHub](https://github.com/sowonlabs/crewx) | hello@sowonlabs.com

package/bin/crewx-lib.js

@@ -0,0 +1,108 @@
+/**
+ * crewx launcher library — testable pure-logic functions extracted from crewx.js.
+ */
+
+/**
+ * Parse --port option from extra CLI args and validate the value.
+ *
+ * @param {string[]} extraArgs - remaining args after route resolution (e.g. ['--port', '3000'])
+ * @returns {{ port: number } | { error: string } | null}
+ *   - `{ port }` when a valid port is found
+ *   - `{ error }` when --port is present but the value is invalid
+ *   - `null` when --port is not specified
+ */
+export function parseWebPort(extraArgs) {
+  const portIdx = extraArgs.indexOf('--port');
+  if (portIdx === -1) return null;
+  const portVal = Number(extraArgs[portIdx + 1]);
+  if (!portVal || portVal < 1 || portVal > 65535) {
+    return { error: 'Invalid port number. Use 1-65535.' };
+  }
+  return { port: portVal };
+}
+
+/**
+ * Determine the route based on CLI arguments.
+ * UI flags (--web, --no-open, --overlay, --electron, --desktop) are checked first.
+ * Any other argument routes to CLI. No arguments → web default (with browser auto-open).
+ *
+ * @param {string[]} args - process.argv.slice(2)
+ * @returns {{ route: string, routeArgs: string[] }}
+ */
+export function resolveRoute(args) {
+  const firstArg = args[0];
+
+  if (firstArg === '--web') return { route: 'web', routeArgs: args.slice(1) };
+  if (firstArg === '--no-open') return { route: 'web', routeArgs: args.slice(1) };
+  if (firstArg === '--overlay') return { route: 'overlay', routeArgs: args.slice(1) };
+  if (firstArg === '--electron') return { route: 'electron-explicit', routeArgs: args.slice(1) };
+  if (firstArg === '--desktop') return { route: 'electron-explicit', routeArgs: args.slice(1) };
+  if (firstArg !== undefined) return { route: 'cli', routeArgs: args };
+  return { route: 'web-default', routeArgs: args };
+}
+
+/**
+ * Forward signals to a child process for clean shutdown.
+ *
+ * Uses an `exited` flag (set by the child's 'exit' event) instead of
+ * `child.killed`, because `child.killed` becomes `true` immediately after
+ * calling `child.kill()` — even if the child process is still running.
+ * This ensures the SIGKILL escalation timer can actually fire.
+ *
+ * On Windows, SIGTERM is equivalent to an immediate kill.
+ *
+ * @param {import('child_process').ChildProcess} child
+ * @param {{ escalateKill?: boolean, detached?: boolean }} options
+ */
+export function setupSignalForwarding(child, { escalateKill = false, detached = false } = {}) {
+  let exited = false;
+  let escalationScheduled = false;
+
+  child.on('exit', () => {
+    exited = true;
+  });
+
+  // When detached, the child runs in its own process group.
+  // Use process.kill(-pid) to kill the entire group (Electron + GPU helpers).
+  // When not detached, use child.kill() for single-process kill.
+  const killChild = (signal) => {
+    try {
+      if (detached) {
+        process.kill(-child.pid, signal);
+      } else {
+        child.kill(signal);
+      }
+    } catch {
+      // Process or process group already terminated
+    }
+  };
+
+  process.on('SIGINT', () => {
+    if (!exited) {
+      killChild('SIGTERM');
+      if (escalateKill && !escalationScheduled) {
+        escalationScheduled = true;
+        setTimeout(() => {
+          if (!exited) killChild('SIGKILL');
+        }, 3000).unref();
+      }
+    }
+  });
+
+  process.on('SIGTERM', () => {
+    if (!exited) killChild('SIGTERM');
+  });
+
+  process.on('SIGHUP', () => {
+    if (!exited) killChild('SIGHUP');
+  });
+
+  // Clean up the child process group when the parent exits unexpectedly
+  if (detached) {
+    process.on('exit', () => {
+      if (!exited) {
+        try { process.kill(-child.pid, 'SIGKILL'); } catch {}
+      }
+    });
+  }
+}