Next steps

You have a working agent under the daemon. Pick what's next based on what you want to do.

---

Make failures loud

The example in first-agent.md already wired a desktop banner. The rest of the built-in drivers (slack, ntfy, pushover, telegram, imessage) follow the same shape — a [[notifiers]] block, no plugin install, no subprocess fork:

[[notifiers]]
driver = "slack"
webhook_url = "${SLACK_WEBHOOK_URL}"
events = ["given_up", "recovered"]

Note the ${VAR}. A Slack webhook URL is the credential, and an agent.toml lives in a repo — put the value in ~/.config/dotagent/secrets.env (mode 0600) and dotagent resolves it at send time. The same holds for ntfy.token/base_url/topic, pushover.token/user, and telegram.bot_token.

→ Read: concepts/notifications.md for every driver, per-driver message size caps, the tiered-notify pattern (desktop on every fail, phone only on given_up), and rate-limit semantics. concepts/secrets.md covers the secrets file.

---

Make output go somewhere

A sink plugin persists the agent's stdout. Three come pre-installed:

• sink-file — write to a file (overwrite or append).
• sink-roam — publish hierarchical content to Roam Research, idempotent via marker_regex.
• sink-outl — same shape as sink-roam but targets Outl, with a single batched delete + write call.

[[on_success]]
plugin = "sink-file"
config = { path = "/Users/me/reports/daily.md", mode = "overwrite" }

→ Read: docs/plugins/sink-file.md, docs/plugins/sink-roam.md, docs/plugins/sink-outl.md, and the overview at concepts/plugins.md.

---

Gate the run on something external

A preflight plugin fails the run before spawning the agent. Built-ins:

• preflight-warp — abort if Cloudflare WARP isn't connected.
• preflight-cmd — generic: run any command, gate on exit code + stdout match.

[[preflight]]
plugin = "preflight-cmd"
config = { command = "aws", args = ["sts", "get-caller-identity"], expect_exit = 0 }

→ Read: docs/plugins/preflight-cmd.md, docs/plugins/preflight-warp.md.

---

Run it on demand, not only on schedule

Every agent you install is already a callable tool:

dotagent mcp     # JSON-RPC over stdio, one tool per agent

Point Claude Code or Claude Desktop at it and you can ask for any agent by name:

{ "mcpServers": { "dotagent": { "command": "dotagent", "args": ["mcp"] } } }

For a chat front end, inbound Telegram hands messages to a dispatcher agent whose stdout goes back to the conversation. Off until you configure it, and it changes the threat model — read V8 first.

→ Read: docs/reference/mcp.md, docs/concepts/telegram.md, docs/concepts/triggers.md.

---

Schedule like a grown-up

The tutorial used type = "interval" for speed. Production agents usually want cron-style schedules with weekdays + hours + minute:

[[schedules]]
id = "daily"
type = "cron"
weekdays = [1, 2, 3, 4, 5]      # Mon-Fri (0 = Sun, 6 = Sat — matches launchd)
hours = [8]
minute = 30

Plus retry policy:

[defaults]
max_retries = 3
retry_backoff_minutes = [5, 15, 30]
stale_after_minutes = 120         # don't bother retrying a stale window

→ Read: reference/agent-spec.md for the full manifest schema. concepts/agents.md for the patterns (digest / triage / generator / watchdog).

---

See into the daemon

Out of the box you get structured JSON logs, daily rotation, and a sharded log per agent — zero config. To export traces to Honeycomb / Grafana Tempo / Jaeger / Datadog, two lines of config.toml:

[telemetry]
otlp_endpoint = "https://api.honeycomb.io:443"

export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=YOUR_KEY"
dotagent reload

→ Read: guides/observability.md for log schema, vendor recipes, jq queries. → Or just tweak retention: guides/config-reference.md.

---

Add many agents

agents/<name>/ is one directory per agent. Add a second:

mkdir -p ~/.config/dotagent/agents/hn-morning
# … drop your agent.toml + entry script …
dotagent doctor                  # validates every agent at once
dotagent reload                  # daemon picks up the new one on next tick

For inspiration:

• examples/disk-alert/ — pure-shell agent with tiered notifications
• examples/hn-digest/ — bash agent that calls claude -p, with the guards an LLM step needs (see guides/llm-agents.md)
• examples/hello-{fish,python,go,rust}/ — minimal "hello" variants per language
• The fish framework's gallery — 9 production agents listed in concepts/agents.md#examples-gallery

→ Read: concepts/agents.md — patterns, extending, connecting agents.

---

Migrate from Fish / cron

If you came from the lib/agent.fish framework, every concept maps 1-to-1:

→ Read: guides/migrating-from-fish.md.

If you came from cron (no framework), the pattern is:

1. Move the script body into agents/<name>/agent.sh.
2. Write an agent.toml that recreates your cron line in the [[schedules]] block.
3. Remove the cron entry; let the daemon take over.

There's no separate cron migration guide today — the Fish guide is the closest thing, and cron ↔ launchd weekday differences are flagged in Troubleshooting.

---

Operate the daemon

How to install/start/stop/reload across macOS launchd + Linux systemd, with diagnostics for "is this thing on?":

→ Read: guides/daemon-lifecycle.md.

---

Something broke

A sintoma → diagnostic decision tree covering:

• Daemon won't start
• doctor errors
• Agent never runs
• Agent runs but fails
• Notifier / sink not working
• Logs / audit / plugin issues
• Performance

→ Read: guides/troubleshooting.md.

---

Read the source

When the docs disagree with the code, the code wins. Worth bookmarking:

Question	Crate / module
"What does the daemon actually do?"	crates/dotagent/src/commands/daemon.rs
"How does the runner spawn agents?"	crates/dotagent-runner/src/lib.rs
"How are heartbeats serialized?"	crates/dotagent-core/src/heartbeat.rs
"How does scheduling math work?" (pure functions, no IO)	crates/dotagent-scheduler/src/lib.rs
"What audit events exist?"	crates/dotagent-core/src/audit.rs
"What's in agent.toml?"	crates/dotagent-core/src/manifest.rs

For contributor onboarding: CLAUDE.md at the repo root.

---

Read the FAQ

Quick answers to the recurring questions (docs/faq.md):

• Windows? root? cron → dotagent? debug without the daemon? multiple users? sandbox? when is 1.0? why not just cron?

---

That's the menu. Each section above is an entry point into a deeper guide — pick the one closest to what you actually need, and ignore the rest until later.