# Teletraan Framework

Teletraan is a self-hosted AI agent framework for macOS that runs persistent Claude Code agents alongside optional service modules (calendar, notifications, status monitoring, and more). A channel server bridges your web dashboard to your agents in real time, while PM2 keeps everything running in the background.

## Quick Start

```bash
git clone <repo-url> teletraan-framework
cd teletraan-framework
./install.sh
```

## What You Get

- **Conductor agent** — a persistent Claude Code session reachable via a web dashboard
- **Channel server** — HTTP + WebSocket bridge between agents and the UI (port 7100)
- **Module system** — opt-in services (calendar, notifications, system status, Telegram bridge)
- **Two installer modes** — guided CLI wizard or AI-guided agent walkthrough (`--agent`)
- **PM2 process management** — all services start on boot via macOS launchd
- **Hook system** — pre/post tool-use hooks keep the dashboard in sync with agent activity
- **Inter-agent dispatch** — conductor can spawn and communicate with specialist agents

## Requirements

- macOS 13 Ventura or later
- An [Anthropic](https://console.anthropic.com) account with an API key
- Homebrew (installed automatically if missing)
- Node.js 22+ (installed automatically if missing)

## Installation

### Option 1: CLI Installer (recommended)

```bash
./install.sh
```

Walks you through a step-by-step wizard in your terminal. Installs prerequisites, lets you choose modules, and starts all services.

### Option 2: AI-Guided Installer

```bash
./install.sh --agent
```

Launches a Claude Code agent that performs the installation interactively, explaining each step in plain language.

### Option 3: Docker (coming soon)

A Docker Compose setup is planned for Linux and non-macOS environments.

## Project Structure

```
teletraan-framework/
├── install.sh              # Main installer entry point
├── installer/              # CLI installer (Node.js)
│   ├── index.js            # Orchestrates the full install flow
│   ├── prereqs.js          # Prerequisite checks and installation
│   ├── prompts.js          # Interactive terminal prompts
│   ├── modules.js          # Module copy/build/register logic
│   ├── post-install.js     # PM2 setup and health checks
│   └── templates.js        # {{VARIABLE}} template substitution
├── agent-installer/        # AI-guided installer (Claude Code agent)
│   ├── CLAUDE.md           # Installer agent personality and flow
│   ├── install-tools.js    # MCP tools the installer agent calls
│   └── start.sh            # Launches the installer agent
├── core/
│   ├── agents/
│   │   ├── conductor/      # Conductor agent templates
│   │   └── create-agent.sh.template
│   └── tools/
│       └── channel-server/ # HTTP + WebSocket bridge (TypeScript)
├── modules/                # Optional service modules
│   ├── calendar/           # Google Calendar sync (port 8084)
│   ├── notifications/      # In-app notification store (port 8087)
│   ├── status/             # Host/service/site monitoring (port 8086)
│   └── telegram-bridge/    # Telegram ↔ conductor routing
├── config/
│   ├── manifest.json       # Registry of installed modules
│   └── system.json.example # Example system configuration
├── scripts/
│   ├── add-module.sh       # Install a module post-setup
│   ├── remove-module.sh    # Remove an installed module
│   ├── health-check.sh     # Check all service health endpoints
│   └── backup.sh           # Back up databases and config
└── docs/
    ├── ARCHITECTURE.md     # System design and message flow
    ├── SETUP.md            # Detailed installation walkthrough
    ├── MODULES.md          # Module guide and custom module creation
    ├── AGENTS.md           # Agent creation and configuration
    └── TROUBLESHOOTING.md  # Common issues and fixes
```

## License

MIT — see LICENSE for details.
