Background Daemon
AgentLoop runs work in a local background daemon. The daemon hosts the orchestrator, manages agent processes, persists task state, and stays running even when the desktop window is closed. You don’t normally interact with it directly — the desktop app drives it for you.
Why a Daemon?
A separate background process means:
- Long-running work survives — Closing the desktop window (or briefly losing focus) doesn’t kill in-flight agent work
- System tray lifecycle — The desktop app can fully close while the daemon continues, then re-open instantly when you click the tray icon
- Persistent state — Task history, conversation threads, and orchestrator state outlive any single window session
- One-machine, multi-window — Multiple desktop windows can connect to the same daemon
Daemon Lifecycle
Default Behavior
You don’t normally need to think about the daemon — it just works:
- You open the desktop app
- The app starts the daemon if it isn’t already running
- The app connects to the daemon and renders the UI
- You close the window — the daemon keeps running so any in-progress agents can finish
- You re-open the window from the tray (or app menu) — it reconnects instantly
When you fully Quit the app from the tray menu, the daemon shuts down gracefully after letting in-progress agents wrap up.
Use Cases
| Use Case | Description |
|---|---|
| Long-running tasks | Start a large refactor, close the window, come back later — work continues |
| Tray-resident development | Keep AgentLoop in the system tray; click in any time to check progress |
| Persistent sessions | Conversation history and task state persist across window restarts |
| CI/CD-style work overnight | Set up a project, toggle the runner on, walk away — agents process the queue until done |
Auto-Restart on Updates
When AgentLoop installs an update, the daemon detects the new binary and auto-restarts itself the next time it’s safe to do so. You don’t need to manually restart anything.
Data & Logs
| Location | Purpose |
|---|---|
~/.config/agentloop/ | Database, credentials, and settings |
~/.config/agentloop/logs/ | Daemon and agent logs |
./.agentloop/ | Per-project state (created next to each repo) |
Troubleshooting
Window won’t connect to daemon
- Quit AgentLoop fully from the tray menu and re-open
- Check
~/.config/agentloop/logs/for daemon errors
Agents seem stuck
- The orchestrator includes self-healing for orphaned and stale work — give it a few seconds
- If an agent is genuinely hung, you can re-run the task from its detail dialog in the Tasks view
Daemon won’t start
- Check disk space (the daemon needs to write to
~/.config/agentloop/) - Check the logs for permission errors
The daemon’s recovery mechanisms run automatically. If the process crashes, it can resume from the last known good state when restarted.