Skip to content

README.md

Latest commit

 

History

History
384 lines (285 loc) · 10.1 KB

README.md

File metadata and controls

384 lines (285 loc) · 10.1 KB
Raw

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.

CHAD Architecture

🧠 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

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