Guide · 3 min read

Get a phone push when your agent finishes

You shouldn't have to watch a dashboard to catch the moment an agent finishes or gets stuck. With Dejima it's one command: point it at a push service, and your phone buzzes on every agent event. Here's the one-liner, plus a small server for when you want the messages tidied up.

The one command

Dejima can POST its events straight to a push service. ntfy is the quickest: you pick a topic name, and that's your channel.

dejima webhook subscribe --url https://ntfy.sh/your-private-topic

Install the ntfy app on your phone, subscribe to the same topic, and you're done. The next time an agent finishes a task, gets stuck, or errors, your phone buzzes. No server, no code.

Pick a long, hard-to-guess topic name. Anyone who knows an ntfy topic name can read it.

What you'll get pushed

Dejima POSTs a small JSON object for every event:

{ "type": "agent.task-complete", "island": "web", "agent": "a1",
  "payload": { ... }, "timestamp": "2026-07-01T18:22:04Z" }

The per-agent types are the ones worth a buzz:

• agent.waiting-for-input fires when the agent is stuck and needs you.
• agent.task-complete fires when it finishes what you asked.
• agent.error fires when it hits an error.

Sent straight to ntfy, each push is that raw JSON. Enough to know what happened. If you'd rather they read like "web/a1 finished," add the small server below.

Make it readable (optional)

A plain Node HTTP server, no framework and no SDK, sits between Dejima and ntfy: it keeps the three events you care about and turns each into a one-line message. Save it as notifier.mjs:

import http from 'node:http'

const NTFY = 'https://ntfy.sh/your-private-topic'   // your ntfy topic
const NOTIFY = new Set([
  'agent.waiting-for-input', 'agent.task-complete', 'agent.error',
])

http.createServer((req, res) => {
  if (req.method !== 'POST') { res.writeHead(405).end(); return }
  let body = ''
  req.on('data', c => (body += c))
  req.on('end', async () => {
    res.writeHead(204).end()                    // ack Dejima right away
    let ev
    try { ev = JSON.parse(body) } catch { return }
    if (!NOTIFY.has(ev.type)) return            // only what we care about

    const who = ev.agent ? `${ev.island}/${ev.agent}` : ev.island
    const msg = {
      'agent.waiting-for-input': `${who} needs you`,
      'agent.task-complete':     `${who} finished`,
      'agent.error':             `${who} hit an error`,
    }[ev.type]

    await fetch(NTFY, { method: 'POST', body: msg })   // ntfy shows the body as the push
  })
}).listen(8099, () => console.log('notifier listening on :8099'))

Run it wherever the daemon can reach it, then point the subscription at the server instead of ntfy directly:

node notifier.mjs
dejima webhook subscribe --url http://localhost:8099

Now the pushes read like "web/a1 finished," and you only get the events you asked for.

Where to take it

The same shape works for anything. Swap the fetch for a Slack or Discord incoming webhook. Filter by ev.island to route different projects to different channels. Watch agent.usage to track token spend. And when you want to go past receiving events to actually driving islands, the Python and TypeScript SDKs wrap the same API the CLI uses.

Common questions