# CrewX

> Build your AI agent team — bring any model, orchestrate any workflow

[![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)

## What is 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.

- **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
npx crewx
```

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

```bash
npx crewx init
```

This creates a `crewx.yaml` in your project with default agents and settings.

### Talk to your agents

```bash
# Ask a question (query mode)
npx crewx q "@claude review this codebase"

# Execute a task (agents can edit files)
npx crewx x "@copilot implement login component"

# Multi-agent collaboration
npx crewx q "@claude @gemini compare approaches for caching"
```

## Key Features

### BYOA (Bring Your Own AI)

Use your existing AI subscriptions — or run fully local with Ollama. No vendor lock-in.

| 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 |

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.

### Agent Teams

Define your team in `crewx.yaml`:

```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.
```

### Thread Conversations

Thread-based conversations keep context across multiple interactions. Agents remember previous messages and can build on each other's work.

```bash
# Start a thread
npx crewx q "@reviewer review PR #42" --thread="pr-42-review"

# Continue the conversation
npx crewx q "@implementer fix the issues found" --thread="pr-42-review"
```

### Semantic Workflows

Define agent collaboration as semantic workflow YAML — branching, parallel execution, approval gates, and loops:

```yaml
# 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
```

### Built-in Tools

Each tool is a standalone npm package — install individually or use all out of the box:

| 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 |

### Desktop & 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 Cases

### Development Workflow Automation
Set up AI-powered code review, testing, and deployment pipelines. Multiple agents handle different stages of your development process.

### Team Productivity
Distribute tasks across specialized agents. A reviewer checks code quality while an implementer writes features — in parallel.

### 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.

## Supported Providers

### CLI Providers
Use AI tools you already have installed:

| 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 |

### API Providers
Connect any API-compatible model — including local LLMs:

| 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 |

Mix CLI and API providers in the same team. For example, Claude for planning + Ollama for execution — best of both worlds.

## 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

### Minimal `crewx.yaml`

```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

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.
```

### 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

- **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

CrewX is built on an open-source CLI engine:

| 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 |

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.

---

**[SowonLabs](https://sowonlabs.com)** | [GitHub](https://github.com/sowonlabs/crewx) | hello@sowonlabs.com