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.
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:
| Command | What it does |
|---|---|
| /help | List every command |
| /model | Switch models mid-session |
| /compact | Compress context when the session gets heavy (saves tokens) |
| /sessions | List past sessions |
| /skills | List loadable skills |
| /skin | Change the theme |
| /exit | Quit |
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
| Habit | Effect |
|---|---|
| Fresh session per topic | Biggest lever — long sessions re-send the whole history every turn |
| /compact | Compress a long session you must keep going |
| Right model per task | Small/flash models for routine work, big ones for heavy lifting |
| caveman skill | Compressed replies (numbers, paths, code stay verbatim) |
| No-agent cron | Scheduled tasks without an LLM = zero tokens |
7Config & file locations
| What | Linux / WSL | Windows |
|---|---|---|
| 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
| Symptom | Fix |
|---|---|
| command not found: merlin | Open a new terminal; on Linux make sure ~/.local/bin is on PATH |
| 401 / 403 from provider | Bad or expired API key → rerun merlin setup |
| 429 rate limit | Quota exhausted — wait, switch models, or upgrade your plan |
| Chat "forgets" things | Session too long → /compact or start a fresh one |
| Broken emoji / glyphs | Use Windows Terminal or a Nerd Font |
Bugs & feature requests: github.com/epinoiahorizon/Merlin-Agent/issues