🦀 Cray Code

A powerful, extensible AI agent framework for the terminal — MCP, Skills, Sub-agents, and multi-provider LLM support.

Cray Code is an AI coding assistant framework inspired by Claude Code's architecture. It provides a unified tool interface, full Model Context Protocol (MCP) integration, a flexible skills system, sub-agent orchestration, and plugin extensibility — all running in a beautiful React/Ink terminal UI.

Features

| Feature | Description | |---|---| | 🧠 Multi-Provider | Anthropic, OpenAI, Ollama, OpenRouter, DeepSeek, or any OpenAI-compatible API | | 🔧 Unified Tool System | All operations (file I/O, shell, MCP, agent, skill) share a single, uniform interface | | 🔌 MCP Integration | Full Model Context Protocol support — stdio, SSE, WebSocket transports | | 📜 Skills System | Bundled + disk-based skills with tool restrictions, model overrides, and /skill invocation | | 👾 Sub-Agent Support | Spawn specialized child agents with constrained tool access, receive structured results | | 🧩 Plugin Architecture | Extensible plugin system for commands, skills, MCP servers, and lifecycle hooks | | 💻 Rich Terminal UI | Real-time thinking display, tool call visualization, React/Ink-based REPL | | 💾 Session Management | Session persistence, resumption, and automatic context compaction | | 🔐 Permission System | Four modes: default, acceptEdits, bypass, plan — fine-grained tool-level control | | ⚡ Stream & Async | Async generator event loop, streaming LLM responses, concurrent background agents |

Quick Start

Prerequisites

• Node.js >= 18.0.0
• npm (comes with Node.js)

Install

# Install globally via npm
npm install -g cray-code

# Or install from the repo
git clone https://github.com/WYH/cray-code.git
cd cray-code
npm install
npm run build

First Run

# Run the setup wizard (required first time)
cray --setup

# Start interactive session
cray

# Start with an initial prompt
cray "Review the current codebase"

# Run in a specific directory
cray --dir /path/to/project

Usage

CLI Options

| Option | Description | |---|---| | [prompt] | First message to send, then stay interactive | | -m, --model <model> | Override the configured model | | -d, --dir <directory> | Working directory | | -p, --permission <mode> | Permission mode: default, acceptEdits, bypass, plan | | -v, --verbose | Enable verbose logging | | --max-turns <number> | Max agent loop turns (default: 25) | | --resume <sessionId> | Resume a previous conversation | | --setup | Re-run the setup wizard | | --show-welcome | Display the welcome banner and exit | | --list-sessions | List saved sessions and exit |

Commands (Slash Commands)

Inside the interactive REPL, use / commands:

/help          Show available commands
/model         Change the active model
/config        View or change configuration
/setup         Re-run the setup wizard
/sessions      List and manage sessions
/clear         Clear the conversation
/exit          Exit Cray Code

Programmatic API

Use Cray Code as a library in your own projects:

import CrayCode from 'cray-code';

const cray = new CrayCode({
  cwd: process.cwd(),
  provider: 'anthropic',
  model: 'claude-sonnet-4-6',
  apiKey: process.env.ANTHROPIC_API_KEY,
  permissionMode: 'default',
});

await cray.initialize();

const result = await cray.processMessage('Review this code');
console.log(result.finalResponse);

await cray.shutdown();

Architecture

┌──────────────────────────────────────────────────────┐
│                    CrayCode Class                      │
│  (Orchestrator — EventEmitter-based)                   │
├──────────────────────────────────────────────────────┤
│                        │                               │
│     ┌──────────────────┼──────────────────┐            │
│     ▼                  ▼                  ▼            │
│  ┌──────┐     ┌──────────────┐    ┌──────────┐        │
│  │ Tool │     │  Query Loop  │    │  Skills  │        │
│  │ Pool │     │  (agent      │    │  System  │        │
│  │      │     │   loop)      │    │          │        │
│  └──┬───┘     └──────┬───────┘    └────┬─────┘        │
│     │                │                 │              │
│     ▼                ▼                 ▼              │
│  ┌──────────────────────────────────────────┐         │
│  │              Provider Layer               │         │
│  │  Anthropic │ OpenAI │ Ollama │ OpenRouter │         │
│  │                  DeepSeek │ Custom        │         │
│  └──────────────────────────────────────────┘         │
│                        │                               │
│     ┌──────────────────┼──────────────────┐            │
│     ▼                  ▼                  ▼            │
│  ┌────────┐    ┌──────────────┐    ┌────────────┐     │
│  │  MCP   │    │   Plugins   │    │  React/Ink │     │
│  │Servers │    │             │    │  Terminal  │     │
│  └────────┘    └──────────────┘    │    UI      │     │
│                                    └────────────┘     │
└──────────────────────────────────────────────────────┘

Core Components

Tool System (Tool.ts)

Every tool follows the same interface — file operations, shell commands, MCP calls, skills, and sub-agents all conform to ToolDef<Input, Output>. This uniform design means the LLM interacts with all capabilities through a single, predictable pattern.

Query Loop (query.ts)

The core agent loop uses an async generator pattern that yields typed QueryEvents. The React/Ink UI consumes these events via for-await and renders real-time updates — thinking, tool calls, results, and errors.

MCP Integration

Full Model Context Protocol support via @modelcontextprotocol/sdk. Connect external tools dynamically — databases, APIs, file systems, and more — through stdio, SSE, or WebSocket transports.

Skills System

Skills are markdown files with frontmatter that define how the model should behave. They can restrict tools, override models, inject context, or spawn sub-agents. Skills are loaded from:

• Bundled — built-in skills shipped with Cray Code
• Disk — user-created skills in the project directory
• Plugin — skills contributed by plugins

Sub-Agent Support

The AgentTool spawns child agents with constrained tool access, preventing infinite recursion while enabling complex parallel workflows. Sub-agents run in isolation with their own context and return structured results.

Plugin Architecture

Plugins extend Cray Code with custom commands, skills, MCP servers, and lifecycle hooks (sessionStart, sessionEnd). The plugin registry discovers and loads plugins at startup.

Configuration

Configuration is stored in ~/.cray/settings.json:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "apiKey": "sk-...",
  "baseUrl": "",
  "setupComplete": true,
  "permissionMode": "default",
  "maxTurns": 25,
  "verbose": false
}

Environment variables:

• CRAY_API_KEY — API key (overrides config)
• CRAY_MODEL — Default model (overrides config)

Provider Support

| Provider | Type | API Key Required | |---|---|---| | Anthropic | Native | Yes | | OpenAI | OpenAI-compatible | Yes | | Ollama | OpenAI-compatible | No | | OpenRouter | OpenAI-compatible | Yes | | DeepSeek | OpenAI-compatible | Yes | | Custom | OpenAI-compatible | Configurable |

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Development mode (with hot-reload via tsx)
npm run dev

# Run tests
node run_test.mjs

Project Structure

cray-code/
├── src/
│   ├── index.ts          # CLI entry point & REPL
│   ├── cray.ts           # Main orchestrator class
│   ├── Tool.ts           # Core tool abstraction
│   ├── tools.ts          # Tool registry & assembly
│   ├── query.ts          # Agent loop (LLM calls + tool execution)
│   ├── queryStream.ts    # Streaming variant
│   ├── context.ts        # Tool context builder
│   ├── setup.ts          # First-run setup wizard
│   ├── tools/            # Built-in tool implementations
│   ├── services/         # MCP, session, config, compaction services
│   ├── commands/         # Slash command system
│   ├── skills/           # Skills system (bundled + disk)
│   ├── plugins/          # Plugin discovery & registry
│   ├── screens/          # React/Ink terminal screens
│   ├── types/            # TypeScript type definitions
│   └── branding/         # Logo & theme
├── dist/                 # Compiled output
├── install.sh            # Unix installer
├── install.ps1           # Windows installer
├── package.json
└── tsconfig.json

Building & Publishing

# Build for production
npm run build

# Create npm tarball
npm run pack:tarball

# Create tarball and install locally
npm run pack:install-local

# Publish to npm
npm publish

Skills

Skills are markdown-based instructions that guide the AI's behavior. They support:

• Tool restrictions — limit the AI to specific tools
• Model overrides — use a different model for specific tasks
• Context injection — inject content inline or fork a sub-agent
• User invocation — invoke via /skill-name in the REPL
• Argument substitution — {{arg}} templates in skill content

Creating a Skill

Create a SKILL.md file with frontmatter:

---
name: my-skill
description: Does something useful
allowedTools: [read, write, bash]
model: claude-sonnet-4-6
---

Follow these instructions when this skill is active:
1. Read the relevant files
2. Analyze the problem
3. Apply the fix

License

MIT — see LICENSE for details.

Acknowledgements

• Inspired by Claude Code by Anthropic
• Built on Model Context Protocol
• Terminal UI powered by React & Ink