@chara-codes/agents

A comprehensive AI agents package for the Chara Codes ecosystem, providing multi-provider AI integration, agentic communication, and extensible tooling for building intelligent applications.

Features

• 🤖 Multi-Provider AI Support - Seamless integration with 9 AI providers
• 🛠️ Extensible Tool System - Rich set of built-in tools with easy extensibility
• 🏃 Process Runner - Manage and monitor long-running development processes
• 📡 Event-Driven Architecture - Real-time communication via typed event emitters
• 🔧 Model Context Protocol (MCP) - Integration with external MCP servers
• 🌐 WebSocket Support - Real-time bidirectional communication
• 💬 Ready-to-Use Agents - Pre-built agents for common tasks

Installation

bun install @chara-codes/agents

Quick Start

Setup

First, initialize your global configuration:

# Initialize global config with all provider variables
chara init
# or
npx @chara-codes/cli init

This creates ~/.chararc in your home directory with all necessary environment variables. Add your API keys to this file.

Example global config structure:

{
  "env": {
    "OPENAI_API_KEY": "your_openai_key_here",
    "ANTHROPIC_API_KEY": "your_anthropic_key_here",
    "GOOGLE_GENERATIVE_AI_API_KEY": "your_google_key_here",
    "DEEPSEEK_API_KEY": "your_deepseek_key_here",
    "OPEN_ROUTER_API_KEY": "your_openrouter_key_here",
    "OLLAMA_API_BASE_URL": "http://localhost:11434",
    "LMSTUDIO_API_BASE_URL": "http://localhost:1234/v1",
    "MOONSHOT_API_KEY": "your_moonshot_key_here",
    "DIAL_API_KEY": "your_dial_key_here",
    "DIAL_API_BASE_URL": "your_dial_base_url_here"
  },
  "defaultModel": "openai:::gpt-4o"
}

Basic Agent Usage

import { chatAgent, initialize } from '@chara-codes/agents';

// Initialize providers (reads from global config or env vars)
await initialize();

// Use the chat agent
const response = await chatAgent({
  model: 'openai:::gpt-4o',
  messages: [{ role: 'user', content: 'Hello, world!' }],
});

for await (const chunk of response.fullStream) {
  process.stdout.write(chunk.textDelta || '');
}

Start the Server

import { startServer } from '@chara-codes/agents';

// Server reads .mcp.json for MCP configuration and auto-detects dev commands
const server = await startServer({
  port: 3031,
  websocket: { enabled: true },
  runner: { enabled: true }
});

console.log('Server running on http://localhost:3031');

Supported AI Providers

The package supports multiple AI providers with automatic configuration and model discovery:

• OpenAI - GPT-4.1, GPT-4o, and other OpenAI models
• Anthropic - Claude 3.7 Sonnet, Claude 4 Sonnet, and other Claude models
• Google - Gemini Pro, Gemini Flash models
• DeepSeek - DeepSeek Chat and reasoning models
• OpenRouter - Access to 100+ models through a single API
• Ollama - Local model execution
• LM Studio - Local model serving
• Moonshot - Chinese AI models (Kimi K2 model)
• DIAL - EPAM AI platform integration

Provider Configuration

Option 1: Global Configuration (Recommended)

Use the Chara CLI to initialize global configuration with all provider environment variables:

# Initialize global config (creates ~/.chararc)
chara init

# Or using npx
npx @chara-codes/cli init

This command creates a global configuration file in your home directory (~/.chararc) with all the necessary environment variables pre-configured. You just need to fill in your API keys.

Option 2: Environment Variables

Alternatively, set up providers using environment variables in your project's .env file:

# OpenAI
OPENAI_API_KEY=your_openai_key

# Anthropic
ANTHROPIC_API_KEY=your_anthropic_key

# Google
GOOGLE_GENERATIVE_AI_API_KEY=your_google_key

# DeepSeek
DEEPSEEK_API_KEY=your_deepseek_key

# OpenRouter
OPEN_ROUTER_API_KEY=your_openrouter_key

# Ollama (local)
OLLAMA_API_BASE_URL=http://localhost:11434

# LM Studio (local)
LMSTUDIO_API_BASE_URL=http://localhost:1234/v1

# Moonshot
MOONSHOT_API_KEY=your_moonshot_key

# DIAL (EPAM)
DIAL_API_KEY=your_dial_key
DIAL_API_BASE_URL=your_dial_base_url

Note: The global configuration takes precedence over environment variables, making it easier to manage API keys across multiple projects.

Dynamic Model Discovery

import { fetchAllModels, getProvider } from '@chara-codes/agents';

// Fetch all available models
const allModels = await fetchAllModels();

// Get specific provider models
const openaiProvider = await getProvider('openai');
const models = await openaiProvider.fetchModels();

Built-in Tools

The package includes a comprehensive set of tools for common AI agent tasks:

File System Tools

• read-file - Read file contents with optional line ranges, automatic outline for large files, security validation
• edit-file - Create, edit, or overwrite files with granular edit operations and diff generation
• move-file - Move or rename files and directories using filesystem operations
• file-system - Unified file system operations with directory stats, file info, and environment analysis
• directory - List directory contents and generate tree structures with .gitignore support
• mkdir - Create directories with recursive parent creation

Development Tools

• terminal - Execute shell commands with real-time output streaming and timeout protection
• grep - Search file contents with regex patterns, context lines, and glob filtering
• find - Find files by glob patterns with comprehensive filtering and .gitignore support
• dev-server - Manage and diagnose development processes with HTTP testing and log capture
• examination - Analyze code and project diagnostics with TypeScript, ESLint, Prettier, and Biome support

Utility Tools

• fetch - HTTP requests with automatic HTML-to-Markdown conversion
• thinking - Structured engineering-focused problem-solving with sequential thoughts and branching

Tool Usage Example

import { tools } from '@chara-codes/agents';

// Read a file
const fileContent = await tools['read-file'].execute({
  path: 'src/index.ts',
  startLine: 1,
  endLine: 50
});

// Execute a command
const result = await tools.terminal.execute({
  command: 'npm test',
  cd: './my-project'
});

Runner Service

The runner service manages long-running processes like development servers with real-time monitoring and logging.

Basic Usage

import { runnerService } from '@chara-codes/agents';

// Start a development server
const processId = await runnerService.start({
  command: 'npm run dev',
  cwd: './my-app'
});

// Monitor the process
runnerService.getStatus(processId);

Runner Events

import { appEvents } from '@chara-codes/agents';

// Listen to runner events
appEvents.on('runner:started', (data) => {
  console.log(`Process ${data.processId} started`);
});

appEvents.on('runner:output', (data) => {
  console.log(`[${data.type}] ${data.chunk}`);
});

appEvents.on('runner:stopped', (data) => {
  console.log(`Process stopped with code ${data.exitCode}`);
});

Event System

The package uses a typed event emitter for real-time communication:

Available Events

• tool:calling - Tool execution events
• runner:started - Process start events
• runner:stopped - Process termination events
• runner:output - Process output streams
• runner:error - Process error events
• runner:status - Process status updates

Event Usage

import { appEvents } from '@chara-codes/agents';

// Listen to specific events
appEvents.on('tool:calling', (data) => {
  console.log(`Calling tool: ${data.name}`);
});

// Pattern-based listening
appEvents.onPattern('runner:*', (eventName, data) => {
  console.log(`Runner event: ${eventName}`, data);
});

// Emit custom events
appEvents.emit('runner:restart', {
  processId: 'my-process',
  newCommand: 'npm run dev:new'
});

Model Context Protocol (MCP)

Integration with external MCP servers for extended functionality is configured via your project's .mcp.json file.

MCP Configuration

Add an mcpServers object to your .mcp.json file. The server will automatically detect and connect to the configured servers upon start.

Example .mcp.json with MCP servers:

{
  "dev": "npm run dev",
  "mcpServers": {
    "file-system-tools": {
      "command": "npx",
      "args": ["-y", "@model-protocol/server-filesystem", "./"],
      "enabled": true
    },
    "another-remote-server": {
      "url": "https://example.com/mcp-sse-endpoint",
      "enabled": true,
      "headers": {
        "x-api-key": "your-secret-key"
      }
    }
  }
}

MCP Tools

MCP tools are automatically integrated with the local tool system:

import { tools } from '@chara-codes/agents';

// Local and MCP tools are merged automatically
const allTools = tools; // Includes both local and MCP tools

Pre-built Agents

Chat Agent

General-purpose conversational agent with tool access:

import { chatAgent } from '@chara-codes/agents';

const response = await chatAgent({
  model: 'anthropic:::claude-3-5-sonnet-20241022',
  messages: [
    { role: 'system', content: 'You are a helpful coding assistant.' },
    { role: 'user', content: 'Help me debug this function' }
  ],
  maxSteps: 5
});

Git Agent

Specialized agent for Git operations:

import { gitAgent } from '@chara-codes/agents';

const response = await gitAgent({
  model: 'openai:::gpt-4o',
  messages: [
    { role: 'user', content: 'Reset the repository to the last commit' }
  ]
});

Beautify Agent

Code formatting and beautification:

import { beautifyAgent } from '@chara-codes/agents';

const response = await beautifyAgent({
  model: 'deepseek:::deepseek-chat',
  code: 'function messy(){return"hello world"}',
  language: 'javascript'
});

WebSocket Integration

Real-time communication with client applications:

Server Setup

const server = await startServer({
  websocket: {
    enabled: true,
    endpoint: '/ws'
  }
});

Client Connection

const ws = new WebSocket('ws://localhost:3031/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data.event, data.data);
};

// Send runner commands
ws.send(JSON.stringify({
  event: 'runner:restart',
  data: { processId: 'my-process' }
}));

API Endpoints

The server provides RESTful endpoints:

• POST /api/chat - Chat with agents
• GET /api/status - Server status
• GET /api/models - Available models
• GET /api/providers - Provider information
• POST /api/beautify - Code beautification
• POST /api/git/reset - Git operations

Configuration

Project Configuration (.mcp.json)

{
  "dev": "npm run dev",
  "build": "npm run build",
  "test": "npm test"
}

Development

Install Dependencies

bun install

Run Development Server

bun run src/index.ts

Run Tests

bun test

Watch Mode

bun run ddev

Architecture

The package is built with a modular architecture:

src/
├── agents/          # Pre-built AI agents
├── controllers/     # HTTP API controllers
├── mcp/            # Model Context Protocol integration
├── providers/      # AI provider implementations
├── services/       # Core services (events, runner)
├── tools/          # Built-in tool implementations
└── utils/          # Utility functions

License

Apache License 2.0

Copyright (c) 2025 Chara Codes

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See the main LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

For detailed contribution guidelines, see CONTRIBUTING.md.