Fetches recent log output and errors from agent journals. Use when the user asks for logs, errors, 'what happened', 'why did it crash', 'show me what went wrong', debug output, failure details, 'check the logs', or 'show me the recent logs'.
When the user asks for logs, wants to see what an agent did, or is debugging a problem — fetch and display recent journal output.
If the user named an agent, use that. Otherwise, ask: "Which agent's logs do you want?" Then list options:
clerk agent list 2>/dev/null || ls ~/.clerk/agents/
Try clerk CLI first, fall back to journalctl:
clerk agent logs <name> --lines 50 2>/dev/null \
|| journalctl --user -u "clerk-<name>" -n 50 --no-pager 2>/dev/null \
|| journalctl --user -u "clerk-<name>.service" -n 50 --no-pager 2>/dev/null \
|| echo "No logs found for clerk-<name>"
Show the log output in a code block. While presenting, call out:
Errors (lines with ERROR, FAIL, fatal, panic, unhandled, exit code non-zero):
Restarts (lines mentioning "started", "activated", "Main process exited"):
Tool use (lines mentioning tool names like Bash, Edit, Write):
| Error pattern | Likely cause | Fix |
|---|---|---|
TELEGRAM_BOT_TOKEN not set / empty | Bot token unresolved from vault | clerk vault list — check token is stored |
connect ECONNREFUSED | MCP server not running (Hindsight, etc.) | Start the MCP server |
session expired / 401 | Claude API auth expired | clerk auth login |
Cannot find module | Node dependency missing | npm install in agent dir |
systemd[...]: start request repeated too quickly | Crash loop | Fix underlying error; systemctl --user reset-failed clerk-<name> |
ENOENT settings.json | Agent not fully scaffolded | clerk agent reconcile <name> |
After showing 50 lines, offer:
journalctl --user -u clerk-<name> -n 200 --no-pager)"journalctl --user -u clerk-<name> --since '1 hour ago')"journalctl --user -u clerk-<name> -f)" — note: live follow isn't possible via Telegram, but user can run it locallyFor scheduled task failures, logs are in separate units:
journalctl --user -u "clerk-<name>-cron-<N>.service" -n 20 --no-pager
If the user asks "why didn't my morning briefing run", check cron service logs.