heymax

Max

AI orchestrator powered by Copilot SDK — control multiple Copilot CLI sessions from Telegram or a local terminal.

Highlights

• Always running — persistent daemon, not a chat tab. Available from your terminal or your phone.
• Remembers like a person — Max keeps a personal wiki at ~/.max/wiki/ that grows with every conversation. Per-entity pages (people/burke.md, projects/myapp.md) with frontmatter, tags, and [[cross-links]]. A relevance-ranked index is injected into context on every message, and Max writes daily conversation summaries on his own.
• Codes while you're away — spins up real Copilot CLI worker sessions in any directory and reports back when they're done.
• Learns any skill — pulls from skills.sh or builds new skills on demand.
• Your Copilot subscription — works with any model your subscription includes (Claude, GPT, Gemini, …). Auto mode picks the right tier per message.

Install

curl -fsSL https://raw.githubusercontent.com/burkeholland/max/main/install.sh | bash

Or install directly with npm:

npm install -g heymax

Upgrading

If you already have Max installed:

max update

Or manually: npm install -g heymax@latest. Your ~/.max/ config carries forward automatically — SQLite memories are migrated to wiki pages, bundled agents are synced (your customizations preserved), and no data is lost.

Quick Start

1. Run setup

max setup

This creates ~/.max/ and walks you through configuration (Telegram bot token, etc.). Telegram is optional — you can use Max with just the terminal UI.

2. Make sure Copilot CLI is authenticated

copilot login

3. Start Max

max start

4. Connect via terminal

In a separate terminal:

max tui

5. Talk to Max

From Telegram or the TUI, just send natural language:

• "Start working on the auth bug in ~/dev/myapp"
• "What sessions are running?"
• "Check on the api-tests session"
• "Kill the auth-fix session"
• "What's the capital of France?"

Commands

Command	Description
max start	Start the Max daemon
max tui	Connect to the daemon via terminal
max setup	Interactive first-run configuration
max update	Check for and install updates
max help	Show available commands

Flags

Flag	Description
--self-edit	Allow Max to modify his own source code (use with max start)

TUI commands

Command	Description
/model [name]	Show or switch the current model
/memory	Show the wiki index (everything Max has stored)
/skills	List installed skills
/workers	List active worker sessions
/copy	Copy last response to clipboard
/status	Daemon health check
/restart	Restart the daemon
/cancel	Cancel the current in-flight message
/clear	Clear the screen
/help	Show help
/quit	Exit the TUI
Escape	Cancel a running response

How it Works

Max runs a persistent orchestrator Copilot session — an always-on AI brain that receives your messages and decides how to handle them. For coding tasks, it spawns worker Copilot sessions in specific directories. For simple questions, it answers directly.

You can talk to Max from:

• Telegram — remote access from your phone (authenticated by user ID)
• TUI — local terminal client (no auth needed)

Memory

Max maintains a personal wiki at ~/.max/wiki/ instead of a flat list of memories. Knowledge is organized into per-entity markdown pages (e.g. pages/people/burke.md, pages/projects/myapp.md) with YAML frontmatter, tags, and [[wiki links]] between related pages.

• remember — fuzzy-matches existing pages and merges new facts in instead of duplicating
• recall / wiki_search / wiki_read — Max searches a ranked index first, then drills into specific pages
• forget — line removal, section rewrite, or whole-page deletion
• Index-first context — every message carries a relevance + recency-ranked table of contents of the wiki, so Max sees what he knows without force-feeding stale page bodies into every prompt
• Episodic memory — after long enough conversations, Max writes a daily summary to pages/conversations/YYYY-MM-DD.md asynchronously, never blocking your reply
• Migration — older SQLite-based memories are migrated and reorganized into entity pages on first launch; originals are archived to sources/migrated-archive/

Architecture

Telegram ──→ Max Daemon ←── TUI
                │
          Orchestrator Session (Copilot SDK)
                │
      ┌─────────┼─────────┐
   Worker 1  Worker 2  Worker N

• Daemon (max start) — persistent service running Copilot SDK + Telegram bot + HTTP API
• TUI (max tui) — lightweight terminal client connecting to the daemon
• Orchestrator — long-running Copilot session with custom tools for session management
• Workers — child Copilot sessions for specific coding tasks

Development

# Clone and install
git clone https://github.com/burkeholland/max.git
cd max
npm install

# Watch mode
npm run dev

# Build TypeScript
npm run build