CHAD — Coding, Hardware, and Automation Designer

A desktop-native, fully local AI system built as a cluster of specialized AIs working together through a shared tool framework.

🧠 What is CHAD?

CHAD is not a single monolithic model — it's a cluster of specialized AI models, each with a clear responsibility:

• mistral-small — Planning and orchestration
• qwen2.5-coder:14b — Fast implementation
• qwen2.5-coder:32b — Deep reasoning and architecture
• llava — Vision and UI understanding

These models work together, coordinated by the planner, which decides which AI handles each task and which tools are needed.

🎯 Design Philosophy

Clustered, Not Monolithic

Different tasks require different strengths. CHAD uses:

• Smaller, specialized models that are more predictable
• Independent models that can be swapped or upgraded
• Better scaling than a single large model

Tool-Driven, Not Unrestricted

All actions go through explicit tools:

• ✅ Permission-based
• ✅ Auditable
• ✅ Extensible
• ✅ Safe by default

Local, Not Cloud

• 100% local execution (Ollama)
• No cloud model inference
• Your code stays on your machine
• Works offline

🚀 Quick Start

Prerequisites

1. Node.js 18+ and npm
2. Ollama running locally with models:

   ollama pull mistral-small
   ollama pull qwen2.5-coder:14b
   ollama pull qwen2.5-coder:32b
   ollama pull llava

Optional: OpenAI-compatible local gateway + AI SDK (recommended for strict planner JSON)

CHAD can also talk to an OpenAI-compatible local gateway (for example at http://localhost:1234/v1) and uses Vercel AI SDK to make the planner emit schema-validated JSON.

• Environment
  • CHAD_LLM_PROVIDER: openai-compatible
  • CHAD_OPENAI_BASE_URL: defaults to http://localhost:1234/v1 when CHAD_LLM_PROVIDER is OpenAI-compatible
  • CHAD_OPENAI_NO_AUTH: set true for local gateways that don’t require an API key
  • CHAD_USE_AI_SDK: set false to disable AI SDK and fall back to raw /chat/completions

Installation

# Clone the repository
git clone https://github.com/yourusername/chad.git
cd chad

# Install dependencies
npm install

# Install Open WebUI dependencies
cd open-webui
npm install
cd ..

# Build and start CHAD
npm start

CHAD will:

1. Show the splash screen with loading progress
2. Start Open WebUI dev server
3. Initialize the AI cluster and tools
4. Launch the main window

🏗️ Architecture

┌─────────────────────────────────────────────┐
│           Open WebUI (Frontend)             │
│         Vite + Svelte + Tailwind            │
└─────────────────┬───────────────────────────┘
                  │ window.chad API
                  │ (IPC Bridge)
┌─────────────────┴───────────────────────────┐
│          Electron Main Process              │
│                                             │
│  ┌───────────────────────────────────────┐ │
│  │         Orchestrator                  │ │
│  │  • Task management                    │ │
│  │  • Tool approval                      │ │
│  │  • Model coordination                 │ │
│  └───────────┬─────────────┬─────────────┘ │
│              │             │                │
│  ┌───────────┴─────┐  ┌───┴──────────────┐ │
│  │   AI Cluster    │  │  Tool Registry   │ │
│  │                 │  │                  │ │
│  │ • Planner       │  │ • Filesystem     │ │
│  │ • Coder         │  │ • Terminal       │ │
│  │ • Architect     │  │ • Web            │ │
│  │ • Vision        │  │ • Custom...      │ │
│  └─────────────────┘  └──────────────────┘ │
│              │                              │
└──────────────┼──────────────────────────────┘
               │
       ┌───────┴────────┐
       │  Ollama API    │
       │  (localhost)   │
       └────────────────┘

🤖 AI Cluster Roles

Planner (mistral-small)

Role: Central coordinator and reasoning engine

Responsibilities:

• Interpret user intent
• Break requests into steps
• Decide which tools are needed
• Delegate tasks to specialized AIs
• Coordinate multi-step workflows

Does NOT: Write code directly

Coder (qwen2.5-coder:14b)

Role: Fast implementation for everyday development

Best for:

• React, TypeScript, Node.js
• UI components
• Scripts and utilities
• Day-to-day coding tasks

Architect (qwen2.5-coder:32b)

Role: Complex reasoning and architectural decisions

Best for:

• Large refactors
• Cross-system reasoning
• Architecture decisions
• High-risk changes

When to use: Selectively, not continuously (it's slower)

Vision (llava)

Role: Visual understanding

Best for:

• Analyzing screenshots
• Describing UI layouts
• Converting mockups to code

🛠️ Tool Framework

CHAD provides explicit, permission-based tools that AIs can request.

Filesystem Tools

// Read files
window.chad.tools.execute('fs_read', { path: 'path/to/file.ts' });

// Write files (requires approval)
window.chad.tools.execute('fs_write', {
  path: 'path/to/file.ts',
  content: '...'
});

// Search files
window.chad.tools.execute('fs_search', {
  path: '.',
  pattern: '*.tsx'
});

// Patch files (safer than full write)
window.chad.tools.execute('fs_patch', {
  path: 'path/to/file.ts',
  find: 'old code',
  replace: 'new code'
});

Terminal Tools

// PowerShell (requires approval)
window.chad.tools.execute('terminal_powershell', {
  command: 'npm install',
  cwd: 'path/to/project'
});

// WSL (requires approval)
window.chad.tools.execute('terminal_wsl', {
  command: 'ls -la',
  cwd: '/home/user'
});

Web Tools

// Search the web
window.chad.tools.execute('web_search', {
  query: 'React best practices 2024',
  numResults: 5
});

// Fetch URL content
window.chad.tools.execute('web_fetch', {
  url: 'https://api.example.com/data'
});

Creating Custom Tools

See docs/TOOL_DEVELOPMENT.md for a guide on creating custom tools.

💬 Using CHAD

From Open WebUI

CHAD's API is available via window.chad:

// Chat with the orchestrator
const response = await window.chad.chat(
  "Refactor the auth system to use JWT"
);

// Chat with a specific model
const code = await window.chad.model.chat('coder', [
  { role: 'user', content: 'Write a React hook for data fetching' }
]);

// List available models
const models = await window.chad.model.list();

// Execute tools
const fileContent = await window.chad.tools.execute('fs_read', {
  path: 'src/main.ts'
});

// Check health
const health = await window.chad.health();

Tool Approval Flow

When an AI requests a destructive tool (write files, execute commands), CHAD emits an approval request:

window.chad.tools.onApprovalRequest((request) => {
  // Show UI to user
  const approved = confirm(`Allow ${request.tool}?`);
  
  // Send approval
  window.chad.tools.approve({
    taskId: request.taskId,
    toolName: request.tool,
    params: request.params,
    approved
  });
});

📚 Documentation

• API Documentation — Complete API reference
• Open WebUI Integration — Integration guide
• Tool Development — Creating custom tools
• Architecture Deep Dive — System design details

🔧 Development

# Build TypeScript
npm run build

# Watch mode
npm run watch

# Start CHAD
npm start

# Package for distribution
npm run package

🎨 Customization

Adding New Models

Edit src/ai/cluster.ts:

this.models.set("newModel", {
  name: "newModel",
  role: "Description",
  model: "ollama-model-name",
  responsibilities: [...]
});

Adding New Tools

Create a tool file in src/tools/:

// src/tools/mytools.ts
import { registry, Tool } from "./registry";

const myTool: Tool = {
  name: "my_tool",
  description: "Does something useful",
  parameters: { ... },
  requiresApproval: false,
  execute: async (params) => {
    // Implementation
  }
};

export function registerMyTools() {
  registry.register(myTool);
}

Then register in src/tools/index.ts.

🛡️ Security

CHAD is designed with security in mind:

• No unrestricted access — All actions go through explicit tools
• Permission-based — Destructive operations require approval
• Auditable — All tool calls are logged
• Local execution — No data leaves your machine

🔮 Future Plans

• Hardware automation tools
• Additional API integrations
• Custom subagent creation
• Model swapping UI
• Enhanced task monitoring
• Tool analytics and history

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Open WebUI — Frontend framework
• Ollama — Local model inference
• Electron — Desktop framework
• qwen2.5-coder — Excellent coding models
• mistral-small — Reliable reasoning

---

CHAD: Because coding should be collaborative, even when it's just you and your AIs.