Documentation.

Everything you need to get Max running, configured, and doing useful things.

Installation.

Prerequisites

• Node.js v18+ — node --version
• npm — comes with Node.js
• GitHub Copilot CLI — Max uses the Copilot SDK which requires an active Copilot subscription. Install with npm install -g @github/copilot
• gogcli (optional) — enables Gmail, Calendar, Drive skills. brew install steipete/tap/gogcli

One-line install

Or install with npm

Setup.

After installing, run the interactive setup wizard:

The wizard walks you through:

1. Model selection — pick your default Copilot model (you can switch anytime later)
2. Telegram setup (optional) — create a bot via @BotFather, lock it down to your user ID, and configure it

Configuration is saved to ~/.max/.env. You can re-run max setup anytime to reconfigure.

Running Max.

Typical workflow: Start the daemon in one terminal with max start, then open a second terminal and run max tui to chat. Or just message Max on Telegram from your phone.

Commands.

Slash commands work in both the TUI and Telegram. They're instant — they don't go through the AI, so they're great for quick actions.

Talking to Max.

Anything that isn't a slash command gets sent to Max as a natural language message. Max decides how to handle it:

• Direct answer — simple questions, math, general knowledge
• Worker session — coding tasks, file operations, debugging (Max spins up a Copilot CLI)
• Skill usage — if Max has a skill for it (email, calendar, etc.), he follows the skill's instructions
• Skill learning — if Max doesn't know how, he researches available CLI tools and teaches himself

Messages are tagged with their source channel — [via telegram] or [via tui] — so Max can adapt his response style. Telegram gets shorter responses; TUI gets more detail.

Worker Sessions.

Workers are the backbone of Max's coding ability. Each worker is a full Copilot CLI session running in a specific directory with full access to files, terminal, git, and tools.

• Workers run in the background — Max dispatches the task and returns immediately
• When a worker finishes, Max receives the result and relays it to you
• Multiple workers can run simultaneously
• You can check on workers with /workers or ask Max "what's the status of the auth-fix session?"

You don't need to manage workers directly — just tell Max what you need done and where, and he handles the rest.

Skills.

Skills are markdown instruction files (SKILL.md) that teach Max how to use external tools. They're stored in ~/.max/skills/.

Using skills

Just ask Max to do something. If he has a skill for it, he'll use it automatically. Ask "what skills do you have?" or use /skills to see what's available.

Learning new skills

When you ask Max to do something he doesn't know how to do, he'll:

1. Spin up a worker to research what CLI tools are available on your machine
2. Figure out how to accomplish the task
3. Save the instructions as a SKILL.md so he remembers for next time
4. Do the task

You can also explicitly teach Max: "Learn how to use kubectl" and he'll research it and create a skill.

Community skills

Max can discover and install skills from the open source community skill library. Just say "find me a skill for X".

Bundled skills

Max ships with the gogcli skill for Google services (Gmail, Calendar, Drive, Contacts, Tasks, Sheets) — requires gogcli to be installed.

Memory.

Max has a three-layer memory system:

Layer 1: Persistent session

Max maintains a single long-running orchestrator session using the Copilot SDK's infinite sessions. The SDK automatically compacts context in the background when it fills up, preserving important information. This means Max naturally remembers your conversation across messages — no manual history injection needed.

Layer 2: Long-term memory (SQLite)

For facts that should survive even a full session reset, Max has a memories table in SQLite. Things like your preferences, project context, people you work with, and routines. These are injected into Max's system prompt so he always has access.

Max saves memories two ways:

• Explicitly — when you say "remember that I prefer TypeScript" or "remember that Sarah is my manager"
• Proactively — Max automatically saves important facts he picks up in conversation

Memory categories: preference, fact, project, person, routine

Use /memory to see everything Max has remembered. Ask Max to "forget #42" to remove a specific memory.

Layer 3: Conversation log

All messages are logged to SQLite with their source channel (Telegram, TUI, background). This provides cross-channel awareness — if you tell Max something on Telegram, the TUI session knows about it too.

Models.

Max can use any model available through your Copilot subscription. Switch models in two ways:

• Slash command: /model claude-sonnet-4.5
• Natural language: "Switch to GPT-4.1" — Max will use the switch_model tool

Ask Max "what models are available?" to see the full list with billing multipliers. The model choice persists across restarts.

Default model: claude-sonnet-4.5

Environment Variables.

Configuration lives in ~/.max/.env. You can edit it directly or use max setup.

Telegram Setup.

Telegram is optional but lets you talk to Max from your phone anywhere.

1. Open @BotFather on Telegram and send /newbot
2. Choose a name and username for your bot
3. Copy the bot token
4. Get your user ID from @userinfobot — send it any message and it replies with your ID
5. Run max setup and enter both values when prompted

We also recommend disabling group joins: in @BotFather, go to /mybots → your bot → Bot Settings → Allow Groups → disable.

How It Works.

Max is a Node.js daemon process built on the GitHub Copilot SDK. Here's the architecture:

• Daemon (max start) — the main process. Starts the SDK client, orchestrator, HTTP API, and Telegram bot.
• Orchestrator — a persistent Copilot session that receives all messages, decides what to do, and dispatches work. Runs in a single infinite session with automatic compaction.
• Workers — full Copilot CLI sessions created on demand for coding tasks. Each runs in its own directory with full tool access.
• HTTP API — Express server on port 7777. The TUI connects via SSE for streaming; slash commands hit REST endpoints.
• TUI (max tui) — a readline-based terminal interface that connects to the daemon's SSE stream.
• Telegram Bot — Grammy-based bot that forwards messages to the orchestrator and relays responses.
• SQLite — stores worker state, conversation log, long-term memories, and daemon state at ~/.max/max.db.

All data lives in ~/.max/:

Copilot SDK.

Max is built on the GitHub Copilot SDK (@github/copilot-sdk). Key SDK features Max uses:

• Infinite sessions — automatic context compaction at 80% utilization, blocking at 95%. Max's orchestrator runs in a single persistent session that never runs out of context.
• Session resume — resumeSession() lets Max pick up where he left off after a restart, preserving conversation history.
• Tool system — Max's built-in tools (remember, recall, workers, model switching, etc.) are defined via defineTool() with Zod schemas.
• Streaming — real-time response streaming via assistant.message_delta events.
• MCP servers — Max can connect to MCP tool servers for extended capabilities.
• Skill directories — the SDK discovers and loads SKILL.md files from configured directories.
• Model listing — client.listModels() returns all available models with capabilities and billing info.

For more on the SDK: Getting Started · GitHub Repository

For more on Copilot CLI: Documentation · Features