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

Upgrading from a previous version

If you already have Max installed, just run:

Or upgrade manually with npm install -g heymax@latest. Your existing configuration in ~/.max/.env is fully backward-compatible — no changes needed.

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
• Delegate to an agent — coding tasks go to @coder, design work to @designer, general tasks to @general-purpose
• 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

You can also address agents directly with @mentions: @coder fix the login bug or @designer make the landing page responsive.

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.

Agents.

Max delegates work to specialist agents — each one runs in its own Copilot CLI session with full tool access. Max acts as the orchestrator: he receives your messages, decides which agent should handle the work, and dispatches the task.

Built-in agents

How to use agents

You can talk to agents in two ways:

• Let Max decide — just describe what you need and Max routes to the right agent automatically
• @mention directly — @coder fix the auth bug in ~/dev/myapp or @designer make the header responsive

Agent tasks run in the background. Max dispatches the task and responds immediately — you don't wait for the agent to finish. When the agent completes, Max relays the results. Multiple agents can work in parallel.

Agent definition files

Each agent is defined by a simple .agent.md file in ~/.max/agents/. The file has YAML frontmatter for configuration and a markdown body for the system prompt:

Frontmatter fields

Changing an agent's model

Edit the model: field in the agent's .agent.md file. For example, to switch @coder to Claude:

Set model: auto to let the orchestrator pick the best model per task. Changes take effect on the next agent session — no restart needed.

Creating custom agents

Ask Max to create one, or use the create_agent tool directly:

Or create the file manually: add a your-agent.agent.md file to ~/.max/agents/ with the frontmatter format above.

Bundled agent updates

When Max updates, bundled agent definitions are synced automatically. If you've customized a built-in agent (edited the file), your changes are preserved — Max only overwrites agents that haven't been modified since the last sync. Built-in agents (max, coder, designer, general-purpose) cannot be deleted, but you can freely edit them.

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 wiki-based memory system that stores knowledge as interlinked markdown pages — organized like a personal Obsidian vault, not a flat list of facts.

Wiki knowledge base

Max maintains a personal wiki at ~/.max/wiki/ — a living knowledge base that grows with every conversation. Preferences, people, projects, routines — organized into searchable markdown pages with YAML frontmatter, automatically indexed, and injected into context.

Entity pages, not flat dumps

Max keeps a dedicated page per entity — pages/people/burke.md, pages/projects/max.md — instead of one giant people.md. New facts are merged into the right page, related entities are cross-linked with [[wiki links]], and pages carry tags + created/updated dates in frontmatter.

Max saves knowledge two ways:

• Explicitly — when you say "remember that I prefer TypeScript" or "remember that Sarah is my manager", Max uses the remember tool. It fuzzy-matches existing pages, slugifies the entity, and routes the fact to the correct page rather than creating duplicates.
• Proactively — Max picks up important facts in conversation and files them away on his own, no permission required.

For structured, longer-form knowledge, Max uses wiki_update to create or edit full pages. You can also ask Max to search his wiki (wiki_search), read specific pages (wiki_read), ingest external content like URLs or documents (wiki_ingest), or run wiki_lint to find broken links and orphan pages.

Index-first context injection

Every message Max receives is paired with a ranked table of contents of his entire wiki — pages scored by keyword relevance to the current message, recency (last 7 days get a boost), and tags. Max sees the index first, then uses wiki_read to drill into specific pages as needed. No more force-feeding stale page content into every prompt.

Episodic memory

After roughly every 10 turns of conversation (with a 30-minute idle gap), a lightweight background writer summarizes the session into a daily conversation page at pages/conversations/YYYY-MM-DD.md — with cross-references back to the people, projects, and decisions involved. This runs asynchronously after responses are delivered, so it never blocks you.

Forgetting

Ask Max to "forget that" and the forget tool picks the right surgery: removing a single line, rewriting a section of a synthesized entity page, or deleting a whole page. Use /memory to see the current wiki index.

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.

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. The log is also what feeds the episodic writer.

Migration from SQLite memories

If you're upgrading from an older version that used flat SQLite-based memories, Max automatically migrates them into wiki pages on first launch, then runs a one-time reorganization pass that splits flat dumps into per-entity pages and archives the originals to sources/migrated-archive/. No action needed.

Models.

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

• Slash command: /model claude-sonnet-4.6
• 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.6

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.
• Agents — specialist Copilot CLI sessions (@coder, @designer, @general-purpose, and custom agents). Each has its own model, system prompt, and full tool access. Defined by .agent.md files in ~/.max/agents/.
• 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 agent task state, conversation log, and daemon state at ~/.max/max.db. Long-term knowledge lives in the wiki at ~/.max/wiki/, not in SQLite.

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