CoreAI - AI Agent Orchestration Platform

A configurable, team-ready AI agent orchestration platform for Claude Code.

Features

• Markdown-based agent definitions - Define agents in rich Markdown templates with YAML frontmatter
• Variable resolution - Use ${config.*}, ${agent.*}, and ${remote.*} variables in templates
• Core + custom agents - Built-in agent library with support for project-specific customizations
• Team filtering - Configure which agents are available per project
• Override system - Customize core agents without modifying the source

Installation

npm install -g @deimoscloud/coreai

Quick Start

# Initialize a new project
coreai init

# Build agents to .claude/agents/
coreai build

# Build agents and initialize KnowledgeLibrary
coreai build --init-knowledge-library

# Generate Claude skills (slash commands)
coreai skills generate

# List available agents
coreai agents list

# Add agents to your project
coreai agents add react-engineer,database-administrator

# Add all available agents
coreai agents add --all

# Remove agents from your project
coreai agents remove android-engineer

# Show details for a specific agent
coreai agents show backend-engineer

# Check agent status
coreai status

Commands

coreai build

Compile agent definitions to Claude-compatible markdown files.

# Build to default output (.claude/agents/)
coreai build

# Build to custom directory
coreai build --output ./my-agents

# Watch mode (coming soon)
coreai build --watch

coreai agents list

List all available agents.

# List all agents
coreai agents list

# List only core agents
coreai agents list --core

# List only custom/override agents
coreai agents list --custom

coreai agents show <name>

Display details for a specific agent.

# Human-readable output
coreai agents show backend-engineer

# JSON output
coreai agents show backend-engineer --json

# Compiled markdown output
coreai agents show backend-engineer --markdown

coreai agents add

Add agents to your project configuration.

# Add specific agents
coreai agents add android-engineer react-engineer

# Add multiple agents (comma-separated)
coreai agents add android-engineer,react-engineer,database-administrator

# Add all available core agents
coreai agents add --all

# Add without automatic rebuild
coreai agents add react-engineer --no-build

coreai agents remove

Remove agents from your project configuration.

# Remove specific agents
coreai agents remove android-engineer

# Remove multiple agents
coreai agents remove android-engineer,react-engineer

# Remove all agents from config
coreai agents remove --all

# Remove without automatic rebuild
coreai agents remove react-engineer --no-build

coreai status

Show agent states and pending messages.

# Show all agent states
coreai status

# Show detailed message information
coreai status --detailed

# Show status for a specific agent
coreai status --agent backend-engineer

# Initialize KnowledgeLibrary if not exists
coreai status --init

coreai skills

Manage Claude skills (slash commands).

# Generate skills to .claude/commands/
coreai skills generate

# List available skills
coreai skills list

# Generate specific skills only
coreai skills generate --skills implement-feature,create-pr

# Overwrite existing skill files
coreai skills generate --overwrite

Other Commands

# Show version
coreai --version

# Show help
coreai --help

# Validate configuration
coreai validate

# Sync remote context from configured sources
coreai sync
coreai sync --force  # Force refresh all cached content

# Cache management
coreai cache status
coreai cache clear

Configuration

Create a coreai.config.yaml in your project root:

project:
  name: "My Project"
  description: "Brief description of your project"

# Default: [engineering-manager]
# Add agents with: coreai agents add <name>
team:
  agents:
    - engineering-manager
    - backend-engineer
    - frontend-engineer

integrations:
  git:
    provider: github
    config:
      owner: "your-org"
      repo: "your-repo"
      default_branch: main
  issue_tracker:
    provider: jira
    config:
      project_key: "PROJ"
      base_url: "https://your-org.atlassian.net"

quality_gates:
  lint:
    command: npm run lint
    required: true
  test:
    command: npm test
    required: true
  build:
    command: npm run build

Built-in Agents

CoreAI includes these core agents:

| Agent | Type | Description | |-------|------|-------------| | android-engineer | IC Engineer | Native Android development specialist | | backend-engineer | IC Engineer | Server-side development specialist | | database-administrator | Specialist | Database design and optimization expert | | devops-engineer | Specialist | Infrastructure and deployment expert | | engineering-manager | Manager | Team coordination and delivery | | frontend-engineer | IC Engineer | UI/UX implementation specialist | | react-engineer | IC Engineer | React and React ecosystem specialist | | react-native-engineer | IC Engineer | Cross-platform mobile development specialist | | software-security-engineer | Specialist | Application security and secure coding expert | | software-solutions-architect | Specialist | System design and architecture expert | | sre-huawei-cloud-architect | Specialist | Huawei Cloud infrastructure specialist | | sre-iac-specialist | Specialist | Infrastructure as Code expert | | sre-kubernetes-specialist | Specialist | Kubernetes and container orchestration expert | | sre-network-specialist | Specialist | Network architecture and security specialist | | wearos-engineer | IC Engineer | Wear OS smartwatch development specialist |

Custom Agents

Create custom agents as Markdown files in coreai/agents/ directory:

---
name: mobile-engineer
description: React Native mobile development specialist
tools: Read, Write, Edit, Bash, Glob, Grep
---

# Mobile Engineer

## Role

React Native mobile development specialist focused on cross-platform mobile apps.

---

## Your Responsibilities

- Implement mobile features using React Native
- Ensure cross-platform compatibility (iOS and Android)
- Optimize mobile performance and user experience

Overriding Core Agents

To customize a core agent, create a file with the same name in coreai/agents/:

---
name: backend-engineer
description: Custom backend engineer for our Python stack
tools: Read, Write, Edit, Bash, Glob, Grep
---

# Backend Engineer

## Role

Custom backend engineer specializing in our Python/FastAPI stack.

<!-- Your custom agent content here -->

Variable Resolution

Agent templates support three variable namespaces:

${config.*} - Project Configuration

Working on project: ${config.project.name}

${agent.*} - Agent Self-Reference

You are the ${agent.name}, responsible for ${agent.role}

${remote.*} - Remote Content

Reference the architecture documentation: ${remote.documentation}

Skills (Claude Slash Commands)

CoreAI generates Claude Code slash commands that integrate with your project configuration.

Built-in Skills

| Skill | Description | |-------|-------------| | implement-feature | Implement a feature following project workflow | | create-pr | Create a pull request with proper formatting | | review-code | Review code changes for quality and standards | | run-quality-gates | Run configured lint, test, and build commands |

Generating Skills

# Generate all skills
coreai skills generate

# List available skills
coreai skills list

# Generate to custom directory
coreai skills generate --output ./my-commands

Generated skills are placed in .claude/commands/ and become available as /skill-name in Claude Code.

Custom Skills

Create custom skills in coreai/skills/ directory:

---
name: deploy
description: Deploy the application to staging
category: custom
---

Deploy the application following the deployment checklist:

1. Run all quality gates
2. Build the production bundle
3. Deploy to staging environment
4. Run smoke tests

MCP Server Integration

CoreAI integrates with Model Context Protocol (MCP) servers for enhanced functionality.

Automatic Discovery

The CLI automatically discovers MCP servers from:

1. Project-level: mcp.json, .mcp.json, .claude/mcp.json
2. Global config: ~/.config/claude/mcp.json, ~/.claude/mcp.json
3. Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Supported MCP Servers

| Server | Integration | |--------|-------------| | @modelcontextprotocol/server-github | GitHub issues, PRs, repositories | | @anthropic/mcp-server-jira | Jira issue tracking | | @anthropic/mcp-server-confluence | Confluence documentation | | @modelcontextprotocol/server-filesystem | Local file operations |

Configuration Example

Create .claude/mcp.json in your project:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    }
  }
}

Native Fallbacks

When MCP servers are unavailable, CoreAI falls back to native adapters:

• GitHub: Uses gh CLI or GitHub REST API
• Filesystem: Direct file system operations

KnowledgeLibrary

The KnowledgeLibrary provides persistent state management for agents.

Structure

KnowledgeLibrary/
├── context.txt              # Project context
├── architecture.txt         # Architecture overview
├── prd.txt                  # Product requirements
└── backend-engineer/        # Per-agent directories
    ├── inbox/               # Incoming messages
    │   └── processed/       # Processed messages
    ├── outbox/              # Outgoing messages
    ├── context/             # Agent-specific context
    │   └── current.txt      # Current working state
    ├── control/             # Control files
    │   ├── objectives.txt   # Current objectives
    │   ├── decisions.txt    # Key decisions
    │   └── dependencies.txt # Dependencies
    ├── history/             # Historical records
    └── tech/                # Technical notes

Initializing

# Initialize during build
coreai build --init-knowledge-library

# Or initialize separately
coreai status --init

Checking Status

# View all agents
coreai status

# Detailed view with messages
coreai status --detailed

# JSON output for scripting
coreai status --json

Project Structure

your-project/
├── coreai.config.yaml          # Project configuration
├── coreai/
│   ├── agents/                 # Custom agent definitions
│   │   └── my-agent.md
│   └── skills/                 # Custom skill templates
│       └── my-skill.md
├── .claude/
│   ├── mcp.json                # MCP server configuration
│   ├── agents/                 # Compiled agents (generated)
│   │   ├── backend-engineer.md
│   │   └── my-agent.md
│   └── commands/               # Generated skills (slash commands)
│       ├── implement-feature.md
│       └── create-pr.md
├── .coreai/
│   └── cache/                  # Remote content cache
└── KnowledgeLibrary/           # Agent state management
    ├── context.txt
    └── backend-engineer/
        ├── inbox/
        ├── outbox/
        └── context/

Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/DeimosCloud/coreai.git
cd coreai

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run CLI locally
npm run cli -- --help
npm run cli -- agents list

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

Roadmap

See IMPLEMENTATION_PLAN.md for detailed implementation status.

Phase 1 (Complete)

• Project foundation (TypeScript, CLI, configuration)
• Agent schema and validation
• Variable resolution system
• Agent compiler (Markdown templates to Claude-compatible output)
• Agent CLI commands (build, list, show)
• Integration adapter framework
• MCP integration layer with server discovery
• Shared context and caching
• Skill generation (Claude slash commands)
• KnowledgeLibrary (local agent state management)
• Complete CLI binary

Phase 2 (Planned)

• Real-time agent collaboration
• Advanced MCP server integrations
• Remote context syncing with Confluence/Notion
• Agent workflow orchestration
• Multi-project support

License

MIT