Skip to content

Events

Nocturnal tells other apps and agents when something it does is ready, fails or needs you: an agent finished, a deploy went live, CI broke, a plan phase is blocked. Anyone you allow can subscribe, and Nocturnal does not need to know who they are. It also takes in events from your other apps, so one piece of work can be followed from app to app and computer to computer.

You set this up through the MCP server. Ask your assistant, for example: "Send Nocturnal's agent and release events to my CRM's inbox."

What an event looks like

Every event, sent or received, is one JSON envelope:

{
  "specversion": "event/1",
  "id": "evt_3f1c…",
  "type": "agent.done",
  "occurredAt": "2026-11-10T09:12:00.000Z",
  "source": { "app": "nocturnal", "device": "Studio Mac" },
  "traceId": "trc_9a2e…",
  "parentEventId": "evt_77b0…",
  "subject": { "kind": "agent", "id": "…", "title": "Fix the login wall", "url": "https://nocturnal.sh/dashboard?project=…" },
  "line": "“Fix the login wall” finished on nocturnal.",
  "status": "ok",
  "data": { "projectId": "nocturnal", "runMode": "agent", "durationMs": 182000 }
}
  • id is unique and stable: if the same event reaches you twice, it has the same id.
  • status is ok, failed, waiting (it needs a person) or info.
  • traceId names the chain of work this belongs to; parentEventId is the event that caused it.
  • Events carry ids, titles and one plain sentence. They never carry prompts, transcripts, code, logs, tokens or personal records.

Subscribing

subscribe_events takes a public https address, the events you want and an optional label and trace. Events can be exact types (release.live), prefixes (agent.*) or * for everything. Your assistant shows you one line saying where your events will go. Nothing is sent until you agree. The answer includes a secret, shown only once.

Each delivery is a POST with the envelope as the body and these headers:

HeaderValue
X-Event-TypeThe event type
X-Event-IdThe event id; dedupe on it
X-Event-TimestampUnix seconds
X-Event-Signaturev1= + hex HMAC-SHA256 of "<timestamp>.<raw body>" with your secret

Check the signature against the raw body before parsing it, and refuse timestamps more than five minutes off.

Answer with any 2xx. A 5xx, a 429, or no answer within 10 seconds is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then dropped. Any other answer is taken as a no and is not retried. Redirects are not followed. Five failed deliveries in a row switch the subscription off, and Nocturnal sends webhook.disabled so you find out.

event_deliveries shows each attempt and its answer. unsubscribe_events switches a subscription off. Private, loopback and internal addresses are refused.

Receiving events from other apps

create_event_inbox gives a named app (for example fruitful) an inbox. After you agree, it answers once with the inbox address and a token:

https://nocturnal.sh/events/in/<inboxId>

The app POSTs one envelope, or an array of up to 50, with Authorization: Bearer <token>. An app that can only be given a web address can use https://nocturnal.sh/events/in/<inboxId>/<token> instead. If it sends X-Event-Signature, Nocturnal checks it against the token, or against the app's own signing secret once you register it with update_event_inbox. A signature that doesn't match is refused. The same event sent twice is stored once. The inbox answers 202 as soon as the events are stored.

list_inbox_events shows what arrived. A new inbox for the same app replaces its old one.

Following one piece of work

When Nocturnal does work because of an event, or because a request named a traceId, everything that work produces carries the same traceId, with parentEventId pointing at its cause. It only starts a new trace when it wasn't given one.

To act on an incoming event, pass its traceId, and its id as parentEventId, to agent_new, plan_build, script_run, release_run or any other tool that starts work. list_inbox_events hands you both. An agent Nocturnal starts gets them as NOCTURNAL_TRACE_ID and NOCTURNAL_PARENT_EVENT_ID, so it can pass them on to your other apps. Agents Nocturnal starts can read events, but they can't create subscriptions or inboxes.

event_trace lists every event Nocturnal sent or received on one trace, oldest first.

Every event Nocturnal sends

Agents

EventStatusSubjectWhenData
agent.startedinfoagentAn agent run started: a new chat, a follow-up, a queued run, a loop pass, a plan phase or a scheduled job.projectId, projectName, runMode, model, provider
agent.doneokagentAn agent run finished and is not waiting on anyone.projectId, projectName, runMode, model, durationMs
agent.waitingwaitingagentAn agent run stopped to ask the person something: a question, a permission it was denied, or a NEEDS-INPUT marker.projectId, projectName, runMode
agent.failedfailedagentAn agent run ended in an error: sign-in expired, usage limit, credits, a crash, or no response.projectId, projectName, reason, exitCode
agent.stoppedinfoagentA person stopped a running agent.projectId, projectName

Plans

EventStatusSubjectWhenData
plan.createdinfoplanA plan was created on a project.projectId, projectName
plan.startedinfoplanA plan started building: the whole plan in one run, or its first phase.projectId, projectName, sessionId
plan.builtokplanA plan finished building: every phase is done, or the whole-plan build ended.projectId, projectName
stage.doneokstageOne phase of a plan finished.projectId, projectName, planId, planTitle, sessionId
stage.failedfailedstageOne phase of a plan failed.projectId, projectName, planId, planTitle, sessionId
stage.blockedwaitingstageOne phase of a plan is blocked and needs a person before the build can go on.projectId, projectName, planId, planTitle, sessionId
plan.reviewedokplanA review pass on a plan finished, whether it revised the plan or left it unchanged.projectId, projectName, outcome
proposal.waitingwaitingproposalAn agent proposed roadmap changes; they wait for a person to accept or reject them.projectId, projectName, changes, sessionId
proposal.acceptedokproposalA person accepted a roadmap proposal (all of it or some changes).projectId, projectName, applied, outcome
proposal.rejectedinfoproposalA person rejected a roadmap proposal.projectId, projectName
request.submittedwaitingplan-requestA client submitted a plan request (their scope); it waits for review.projectId, projectName
request.acceptedokplan-requestA plan request was accepted and became a plan.projectId, projectName, planId

Processes

EventStatusSubjectWhenData
process.startedinfoprocessA managed long-running process (a dev server, a worker) was started. Automatic restarts are not reported.projectId, projectName
process.crashedfailedprocessA managed process exited without being asked to. Reported once per crash streak; Nocturnal keeps restarting it.projectId, projectName, restarts
process.stoppedinfoprocessA managed process was stopped on request.projectId, projectName

Scripts

EventStatusSubjectWhenData
script.doneokscriptA project script (build, test, deploy, …) finished with exit code 0.projectId, projectName, scriptId, runId, exitCode
script.failedfailedscriptA project script failed or was stopped before it finished.projectId, projectName, scriptId, runId, exitCode

Git

EventStatusSubjectWhenData
commit.createdokcommitA commit was made through Nocturnal (the dashboard, the CLI or a tool call).projectId, projectName, branch
branch.createdinfobranchA branch was created through Nocturnal.projectId, projectName
branch.pushedokbranchA branch was pushed to its remote through Nocturnal.projectId, projectName
branch.mergedokbranchA branch was merged into the current one through Nocturnal.projectId, projectName, into
merge.conflictedwaitingbranchA pull or merge stopped on conflicts that a person (or an agent they send) has to resolve.projectId, projectName, files

GitHub

EventStatusSubjectWhenData
pr.openedinfopull-requestA pull request was opened through Nocturnal.repo, head, base
pr.mergedokpull-requestA pull request was merged through Nocturnal.repo
ci.passedokci-runA GitHub Actions run on a watched project completed successfully.projectId, projectName, branch, commit, workflow
ci.failedfailedci-runA GitHub Actions run on a watched project completed without succeeding.projectId, projectName, branch, commit, workflow, conclusion

Issues

EventStatusSubjectWhenData
issue.createdinfoissueA GitHub issue was filed through Nocturnal.repo, number
issue.closedokissueA GitHub issue was closed through Nocturnal.repo, number
issue.commentedinfoissueA comment was added to a GitHub issue through Nocturnal.repo, number

Versions

EventStatusSubjectWhenData
version.cutokversionA version was cut and its changelog entry written.projectId, projectName, version
version.deployedokversionA version was marked as deployed to an environment.projectId, projectName, version, environment

Deploys

EventStatusSubjectWhenData
release.startedinforeleaseA deploy to a target started.projectId, projectName, target, production
release.liveokreleaseA deploy to a production target succeeded: the change is live.projectId, projectName, target
release.deployedokreleaseA deploy to a non-production target (staging, test) succeeded.projectId, projectName, target
release.failedfailedreleaseA deploy failed or was interrupted.projectId, projectName, target, production
preview.readyokpreviewA preview deploy of a chat's work is up.projectId, projectName, sessionId, provider
preview.failedfailedpreviewA preview deploy of a chat's work failed.projectId, projectName, sessionId

Jobs

EventStatusSubjectWhenData
job.createdinfojobA scheduled job was created.projectId, projectName
job.raninfojobA scheduled job fired and started its agent. The agent's own events follow on the same trace.projectId, projectName, sessionId
job.failedfailedjobA scheduled job was due but could not start its agent.projectId, projectName

Projects

EventStatusSubjectWhenData
project.createdinfoprojectA project was created or imported.—
project.adoptedokprojectA project was adopted: Nocturnal wrote its .nocturnal/project.json.—
project.archivedinfoprojectA project was archived.—

Brain

EventStatusSubjectWhenData
brain.refreshedokbrainA Brain refresh finished: what the project knows about itself was re-read.projectId, projectName, outcome, facts
brain.failedfailedbrainA Brain refresh failed or was interrupted.projectId, projectName
decision.recordedinfodecisionA decision was recorded in a project's Brain.projectId, projectName

Changes

EventStatusSubjectWhenData
change.verifiedokchangeA person marked a change as working.projectId, projectName
change.problemfailedchangeA person reported a problem with a change.projectId, projectName

Sync

EventStatusSubjectWhenData
sync.conflictwaitingplanA plan was edited on two computers at once; a person has to choose which version to keep.projectId, projectName

Usage

EventStatusSubjectWhenData
usage.highinfousage-windowA Claude or ChatGPT plan window crossed 80% used.provider, window, usedPercent, resetsAt
usage.limitedwaitingusage-windowA Claude or ChatGPT plan window hit its limit; agents on it wait until it resets.provider, window, resetsAt

Billing

EventStatusSubjectWhenData
trial.startedinfoaccountA Nocturnal Pro trial started on the account.—
payment.receivedokaccountA Nocturnal Pro payment went through.periodEnd
payment.failedfailedaccountA Nocturnal Pro payment failed; the card needs attention.—
pro.cancelledinfoaccountNocturnal Pro was cancelled; it runs to the end of the paid period and does not renew.periodEnd
pro.endedinfoaccountNocturnal Pro ended on the account.—

Events

EventStatusSubjectWhenData
webhook.disabledwaitingevent-subscriptionAn event subscription was switched off after five failed deliveries in a row; it needs a person to fix the address and subscribe again.url, label