Docs/Tutorial

Merlin Agent in Your Terminal

The complete guide to running Merlin Agent in your terminal: install on Windows & Linux, first-run setup, daily commands, token-saving habits, and troubleshooting.

Updated October 2026·Epinoia Arcane Fleet·MIT License

1What is Merlin Agent?

Merlin is a terminal-native, extensible AI agent harness. It runs entirely on your machine, talks to the LLM provider you choose (Z.AI, OpenRouter, Anthropic, Ollama, and more), and executes real actions: edit files, run shell commands, search the web, schedule cron jobs, and carry memories across conversations.

Built by Epinoia Horizon — 100% open source under the MIT license.

2Install (one command)

Windows (PowerShell)

irm https://epinoiahorizon.com/install.ps1 | iex

Close and reopen PowerShell, then verify:

merlin --version

Quick fixes: merlin not recognized → close every terminal window and reopen. Still not → run the installer once more (it repairs non-admin PATH). Antivirus flags it → allow it; the installer comes from the public repo epinoiahorizon/Merlin-Agent.

Linux / WSL

curl -fsSL https://epinoiahorizon.com/install.sh | bash
source ~/.bashrc   # or open a new terminal
merlin --version

On Windows but want the Linux experience too? Run wsl --install in PowerShell, reboot, then run the Linux installer inside WSL. Native-Windows Merlin and WSL Merlin coexist fine — separate homes.

Requirements: Python 3.10+ (installed automatically if missing) and an internet connection. Everything else is handled by the installer.

3First-run setup (2 minutes)

merlin setup

The wizard asks for your provider & model (Z.AI, OpenRouter, Anthropic, local Ollama, and more), then your API key — stored at ~/.merlin/.env (Windows: %LOCALAPPDATA%\merlin\.env) and never sent anywhere except your provider.

merlin doctor   # health check
merlin model    # switch models anytime

4Everyday use

merlin                              # interactive chat
merlin chat -q "what is port 443?"  # one-shot question
merlin --continue                   # resume last session
merlin --resume <session-id>        # resume a specific one

Key in-session commands:

CommandWhat it does
/helpList every command
/modelSwitch models mid-session
/compactCompress context when the session gets heavy (saves tokens)
/sessionsList past sessions
/skillsList loadable skills
/skinChange the theme
/exitQuit

5Core capabilities

Coding

"Review app.py, fix the bugs, run the tests" — Merlin reads, edits, runs, and reports back.

Web research

"Find the official docs for X, summarize in 5 points with links."

Automation

Schedule cron jobs from inside a session, e.g. a daily data-integrity check.

Persistent memory

"Remember: my main repo lives at Y" — recalled in later sessions.

Skills

On-demand add-ons — e.g. caveman compresses replies while keeping numbers, paths, and code intact.

6Saving tokens

HabitEffect
Fresh session per topicBiggest lever — long sessions re-send the whole history every turn
/compactCompress a long session you must keep going
Right model per taskSmall/flash models for routine work, big ones for heavy lifting
caveman skillCompressed replies (numbers, paths, code stay verbatim)
No-agent cronScheduled tasks without an LLM = zero tokens

7Config & file locations

WhatLinux / WSLWindows
Config~/.merlin/config.yaml%LOCALAPPDATA%\merlin\config.yaml
API keys~/.merlin/.env%LOCALAPPDATA%\merlin\.env
Skills~/.merlin/skills/%LOCALAPPDATA%\merlin\skills\
Memory~/.merlin/memories/%LOCALAPPDATA%\merlin\memories\
Session history~/.merlin/state.db%LOCALAPPDATA%\merlin\state.db

Don't hand-edit config.yaml unless you're sure — one bad indent can break it. Use merlin config set <key> <value>. Update Merlin with merlin update.

8Bonus: Merlin on Telegram

# 1) create a bot via @BotFather on Telegram, keep the token
merlin config set channels.telegram.token <TOKEN>
merlin config set channels.telegram.enabled true
merlin gateway run

Needs an always-on machine (a VPS or your own PC).

9Troubleshooting

SymptomFix
command not found: merlinOpen a new terminal; on Linux make sure ~/.local/bin is on PATH
401 / 403 from providerBad or expired API key → rerun merlin setup
429 rate limitQuota exhausted — wait, switch models, or upgrade your plan
Chat "forgets" thingsSession too long → /compact or start a fresh one
Broken emoji / glyphsUse Windows Terminal or a Nerd Font

Bugs & feature requests: github.com/epinoiahorizon/Merlin-Agent/issues