Socket API

Socket API (legacy overview)

This page remains available for compatibility with the original documentation URL. The expanded reference is now organized under the API Reference.

This document describes Crona’s local daemon IPC surface.

The protocol and method names still use kernel for the internal daemon process. Product docs usually call the same process the local daemon or background daemon.

It is an open-source reference for contributors and advanced users, not a promise of long-term network API stability before 1.0.0.

Transport

Crona uses a local request/response transport between clients and the local daemon.

• Unix-domain sockets on Unix-like platforms
• named pipes on Windows

The transport is local-only. The canonical wire envelopes live in shared/protocol/ipc.go.

Wire Envelopes

Request

{
  "id": "string",
  "method": "string",
  "params": {}
}

• id: client-generated correlation ID
• method: RPC method name
• params: optional JSON payload

Response

{
  "id": "string",
  "result": {},
  "error": {
    "code": "string",
    "message": "string",
    "data": {}
  }
}

• result is omitted on error
• error is omitted on success
• error.data is optional structured metadata for client-recoverable errors

Event

{
  "type": "string",
  "payload": {}
}

Event envelopes are pushed after events.subscribe.

Source Of Truth

Use these files as the canonical contract:

• shared/protocol/ipc.go
• shared/protocol/methods.go
• shared/dto/requests.go
• shared/types/domain.go
• shared/types/events.go

Compatibility Note

• The local daemon IPC surface is shared across Crona clients.
• It is intentionally documented because the project is open source.
• Before 1.0.0, use the shared Go types and method constants as the source of truth over any prose doc.
• Check GUI compatibility against kernel.info.get -> protocolVersion.
• protocolVersion is independent from the Crona release version and only changes when the local IPC contract or its client-visible semantics change.
• The current local IPC protocol is 1.5.

kernel.info.get is the expected GUI handshake:

• protocolVersion for compatibility checks
• runtime transport and endpoint details
• running release channel metadata

RPC Methods

Request DTO names below refer to types in shared/dto/requests.go. Result payloads are returned as JSON objects or arrays matching the shared domain/DTO types used by the local daemon handlers.

Event Subscription

Method	Request	Result	Notes
events.subscribe	dto.Empty	stream subscription ack	Starts the event stream.

Health And Kernel

Method	Request	Result	Notes
health.get	dto.Empty	health status object	Kernel health and readiness.
kernel.info.get	dto.Empty	kernel info object	Runtime metadata, transport, endpoint, install metadata, and protocolVersion.
kernel.shutdown	dto.Empty	dto.OKResponse	Graceful local shutdown.
kernel.restart	dto.Empty	dto.OKResponse	Restarts the local daemon.
kernel.dev.seed	dto.Empty	dto.OKResponse	Dev-only sample data seed.
kernel.dev.clear	dto.Empty	dto.OKResponse	Dev-only local data clear.
kernel.data.wipe	dto.ConfirmDangerousActionRequest	dto.OKResponse	Wipes runtime data after explicit confirmation.

Updates

Method	Request	Result	Notes
update.status.get	dto.Empty	update status object	Current version, channel, availability, notes metadata.
update.check	dto.Empty	update status object	Performs a refresh against the configured source.

Alerts

Method	Request	Result	Notes
alerts.status.get	dto.Empty	alert status object	Active backend, capability flags, and runtime support for alerts/sound.
alerts.test_notification	dto.Empty	dto.OKResponse	Sends a sample alert through the current backend.
alerts.test_sound	dto.Empty	dto.OKResponse	Plays the selected bundled alert preset when supported.
alerts.notify	types.AlertRequest	dto.OKResponse	Delivers one structured alert request through the local daemon alerts layer.
alerts.delivery.subscribe	types.AlertDeliveryCapability	alert.delivery stream	Claims native alert delivery while the stream remains connected. Delivered alerts can include companion actions when the backend has something actionable to offer.
alerts.delivery.ack	types.AlertDeliveryAck	dto.OKResponse	Acknowledges notification and sound delivery independently; actionable companion deliveries may also include actionId and actionSeconds. Break deferral accepts the companion preference values 30, 60, or 120 seconds only. Empty action ACKs decline deferral, while a missing ACK triggers notification fallback.
alerts.reminders.list	dto.Empty	reminder list	Lists scheduled local alert reminders.
alerts.reminders.create	dto.AlertReminderCreateRequest	reminder object	Creates a scheduled reminder rule.
alerts.reminders.update	dto.AlertReminderUpdateRequest	reminder object	Updates one scheduled reminder rule.
alerts.reminders.delete	dto.AlertReminderIDRequest	dto.OKResponse	Deletes one scheduled reminder rule.
alerts.reminders.toggle	dto.AlertReminderToggleRequest	reminder object	Enables or disables one scheduled reminder rule.

Alert behavior notes:

• the local daemon, not the TUI, decides when alerts fire
• scheduled reminders are local-only and only fire while the local daemon is running
• reminder kinds are checkin_reminder and daily_plan_reminder; check-in reminders are suppressed after today’s check-in exists, and daily-plan reminders are suppressed after today’s plan contains an item
• focus inactivity alerts are local-daemon-owned; TUI clients may call timer.activity.touch to report recent user input while a focus session is active
• AlertStatus reflects the current OS helper/backend that the local daemon detected at runtime

Repositories

Method	Request	Result	Notes
repo.list	dto.Empty	[]types.Repo	Lists repos.
repo.create	dto.CreateRepoRequest	repo object	Creates a repo.
repo.update	dto.UpdateRepoRequest	repo object	Updates a repo.
repo.delete	dto.NumericIDRequest	dto.OKResponse	Deletes a repo.

Streams

Method	Request	Result	Notes
stream.list	dto.ListStreamsQuery	[]types.Stream	Lists streams for a repo.
stream.create	dto.CreateStreamRequest	stream object	Creates a stream.
stream.update	dto.UpdateStreamRequest	stream object	Updates a stream.
stream.delete	dto.NumericIDRequest	dto.OKResponse	Deletes a stream.

Issues And Daily Planning

Method	Request	Result	Notes
issue.list	dto.ListIssuesQuery	issue list	Lists issues for a stream.
issue.list_all	dto.Empty	issue-with-meta list	Lists issues across the workspace.
issue.create	dto.CreateIssueRequest	issue object	Creates an issue.
issue.update	dto.UpdateIssueRequest	issue object	Updates an issue.
issue.delete	dto.NumericIDRequest	dto.OKResponse	Deletes an issue.
issue.change_status	dto.ChangeIssueStatusRequest	issue object	Applies a lifecycle transition.
issue.status_transitions	dto.NumericIDRequest	dto.IssueStatusTransitionsResponse	Returns daemon-authoritative valid lifecycle transitions for an issue.
issue.set_todo	dto.SetIssueTodoRequest	issue object	Sets a todo date.
issue.clear_todo	dto.NumericIDRequest	issue object	Clears a todo date.
issue.daily_summary	dto.DailyIssueSummaryQuery	daily summary object	Summary for an arbitrary date.
issue.today_summary	dto.Empty	daily summary object	Today’s summary shortcut.
daily_plan.get	dto.DailyPlanQuery	daily plan object	Returns planned issues and supporting daily data.

Habits

Method	Request	Result	Notes
habit.list	dto.ListHabitsQuery	habit list	Lists habits for a stream.
habit.list_due	dto.ListHabitsDueQuery	due-habit list	Lists habits due for a date.
habit.create	dto.CreateHabitRequest	habit object	Creates a habit.
habit.update	dto.UpdateHabitRequest	habit object	Updates a habit.
habit.delete	dto.NumericIDRequest	dto.OKResponse	Deletes a habit.
habit.complete	dto.HabitCompletionUpsertRequest	completion object	Marks or logs habit completion.
habit.uncomplete	dto.HabitCompletionUpsertRequest	completion object	Removes completion status.
habit.history	dto.HabitHistoryQuery	history list	Habit completion history.

Momentum

Method	Request	Result	Notes
momentum.list	dto.Empty	habit streak definition list	Lists the configured custom momentum definitions.
momentum.create	dto.HabitStreakDefinitionRequest	habit streak definition object	Creates a new custom momentum definition.
momentum.update	dto.HabitStreakDefinitionRequest	habit streak definition object	Updates one custom momentum definition.
momentum.delete	dto.HabitStreakDefinitionDeleteRequest	dto.OKResponse	Deletes one custom momentum definition.
momentum.range	dto.MomentumRangeRequest	momentum card list	Returns momentum cards with the current series window.
momentum.detail	dto.MomentumDetailRequest	momentum detail object	Returns the selected definition, current bucket, and contributor breakdown.

Momentum behavior notes:

• Habit targets count habit-completion history against the selected habit set.
• Context targets count ended sessions that fall within the selected repo, stream, or repo-wide context set.
• any mode treats the selected targets as alternatives, while all mode requires all selected targets to contribute to the threshold.
• momentum.detail uses the same normalization and series logic as the card surface, but expands the result with current-bucket metadata, resolved target summary, and contributor rows.

Check-Ins And Metrics

Method	Request	Result	Notes
checkin.get	dto.DailyCheckInQuery	check-in object	Gets one day’s check-in.
checkin.upsert	dto.DailyCheckInUpsertRequest	check-in object	Creates or updates a check-in.
checkin.delete	dto.DeleteByDateRequest	dto.OKResponse	Deletes a daily check-in.
checkin.range	dto.DateRangeQuery	check-in list	Lists check-ins in a range.
metrics.range	dto.DateRangeQuery	metrics range object	Per-day metrics for a date window.
metrics.rollup	dto.DateRangeQuery	metrics rollup object	Aggregate rollups for a date window.
metrics.streaks	dto.DateRangeQuery	streak summary object	Streak calculations over a date window.
metrics.streaks_lifetime	dto.DailyCheckInQuery	streak summary object	Streak calculations across stored history through one date.

Streak behavior notes:

• metrics.streaks keeps range-based semantics for callers that need streaks constrained to a specific date window.
• metrics.streaks_lifetime computes the same streak summary shape across stored local history through the requested date, excluding future records.
• The lifetime start date is derived from the earliest stored ended focus session, check-in, or habit completion at or before the requested date. If no history exists, the requested date is used as the start date.
• The TUI Wellbeing dashboard uses metrics.streaks_lifetime for Momentum while retaining 7-day metrics.range, metrics.rollup, burnout, and dashboard summary calls for the rest of the daily metrics surface.
• For weekly and monthly custom habit streaks, an incomplete current week/month does not break the current streak while that bucket is still open.

Dashboards

Method	Request	Result	Notes
dashboard.window	dto.DashboardWindowQuery	dashboard window object	Shared dashboard data for a range and optional scope.
dashboard.focus_score	dto.DashboardSummaryQuery	focus score summary	Focus scoring summary; targetWorkedSeconds is the sum of estimates on issues due in the requested date range, or 0 when none are estimated. The response also includes a cause-oriented reason (no_activity, under_target, needs_breaks, balanced, or overextended).
dashboard.focus_score_range	dto.DateRangeQuery	array of types.FocusScoreRangeDay	One focus-score entry per calendar date in the inclusive requested range. Each entry includes the date, score, level, cause-oriented reason, and whether the day has score data.
dashboard.distribution	dto.DashboardSummaryQuery	distribution summary	Time distribution summary.
dashboard.goal_progress	dto.DashboardSummaryQuery	goal progress summary	Estimate and execution progress.

dashboard.focus_score_range accepts the inclusive ISO date range shape used by the other range methods:

{
  "start": "2026-08-01",
  "end": "2026-08-07"
}

The response contains an entry for every date, including dates without activity:

[
  {
    "date": "2026-08-01",
    "score": 82,
    "level": "strong",
    "reason": "balanced",
    "hasData": true
  },
  {
    "date": "2026-08-02",
    "score": 0,
    "level": "low",
    "reason": "no_activity",
    "hasData": false
  }
]

hasData distinguishes an empty day from a calculated zero score. Date-only values use the daemon’s local calendar semantics and must not be converted through UTC midnight.

Exports

Method	Request	Result	Notes
export.glance	dto.ExportReportRequest	export result	Summary export generation.
export.daily	dto.DailyReportRequest	export result	Daily report generation.
export.weekly	dto.ExportReportRequest	export result	Weekly report generation.
export.repo	dto.ExportReportRequest	export result	Repo report generation.
export.stream	dto.ExportReportRequest	export result	Stream report generation.
export.issue_rollup	dto.ExportReportRequest	export result	Issue rollup generation.
export.csv	dto.ExportReportRequest	export result	CSV export generation.
export.calendar	dto.ExportCalendarRequest	calendar export result	Writes deterministic .ics artifacts.
export.assets.get	dto.Empty	export assets metadata	Export templates, docs, preset metadata, directories.
export.reports_dir.set	dto.ExportReportsDirUpdateRequest	dto.OKResponse	Sets the reports directory.
export.ics_dir.set	dto.ExportICSDirUpdateRequest	dto.OKResponse	Sets the ICS directory.
export.reports.list	dto.Empty	generated report list	Lists generated report artifacts.
export.reports.delete	dto.ExportReportDeleteRequest	dto.OKResponse	Deletes a generated report artifact.
export.template.reset	dto.ExportTemplateResetRequest	asset reset result	Resets a template/spec to bundled defaults.
export.template.apply	dto.ExportTemplatePresetApplyRequest	asset preset result	Applies a built-in preset.

Export behavior notes:

• markdown export does not require extra renderer tooling
• summary, daily, and weekly PDF export require weasyprint
• repo, stream, and issue-rollup PDF export require pandoc plus a supported PDF engine
• repo, stream, and issue-rollup exports can be generated for explicitly selected entities; callers do not need to mutate the shared active context first
• export.assets.get is the runtime capability/status surface for renderer availability, active template paths, and reports directories

Sessions And Timer

Method	Request	Result	Notes
session.list_by_issue	dto.ListSessionsQuery	session list	Lists sessions by issue.
session.get	dto.SessionIDRequest	session object	Gets one session.
session.detail	dto.SessionIDRequest	session detail object	Rich session detail for overlays and history.
session.get_active	dto.Empty	active session or null	Current active session.
session.start	dto.StartSessionRequest	active session object	Starts a session for an issue.
session.pause	dto.Empty	timer/session state	Pauses the active session.
session.resume	dto.Empty	timer/session state	Resumes the active session.
session.end	dto.EndSessionRequest	ended session object	Ends the active session.
session.log_manual	dto.ManualSessionLogRequest	session object	Logs a manual session entry.
session.amend_note	dto.AmendSessionNoteRequest	session object	Rewrites the stored session note.
session.history	dto.SessionHistoryQuery	session history result	History queries with scope and paging controls.
timer.get_state	dto.Empty	timer state object	Current timer state.
timer.start	dto.TimerStartRequest	timer/session state	Starts a timer, optionally from context or an explicit repo/stream/issue path.
timer.activity.touch	dto.Empty	dto.OKResponse	Records recent client activity for active-session inactivity alert suppression.
timer.pause	dto.Empty	timer/session state	Pauses the timer.
timer.resume	dto.Empty	timer/session state	Resumes the timer.
timer.extend	dto.TimerExtendRequest	timer/session state	Extends an active hard-limit timer.
timer.defer_break	dto.TimerDeferBreakRequest	timer/session state	Daemon-authoritative automatic Pomodoro break deferral; normally invoked by acknowledging the daemon’s break-deferral alert action.
timer.end	dto.EndSessionRequest	ended session object	Ends the active timer/session.

Timer start behavior notes:

• TimerStartRequest can carry repoId, streamId, and issueId so clients can start focus from a selected issue without first mutating the shared active context.
• Hard-limit starts can set hardLimitKind to pomodoro or countdown. Missing values remain pomodoro for compatibility; countdowns use only hardLimitTotalSeconds and accept duration-only extensions through additionalSeconds.
• If issueId is omitted, the local daemon resolves the current active context issue.
• Inactivity alerts use core settings for enablement, first-alert threshold, and repeat interval. The default is enabled, 60 minutes to first alert, and 60 minutes between repeats.
• timer.defer_break accepts 30, 60, or 120 seconds exactly once per active Pomodoro work segment. Timer mutations and boundary callbacks are serialized; a successful deferral reschedules and invalidates the previous boundary callback.

Context

Method	Request	Result	Notes
context.get	dto.Empty	active context object	Gets the current shared context.
context.set	dto.UpdateContextRequest	active context object	Sets repo, stream, and issue together.
context.switch_repo	dto.SwitchRepoRequest	active context object	Switches repo only.
context.switch_stream	dto.SwitchStreamRequest	active context object	Switches stream only.
context.switch_issue	dto.SwitchIssueRequest	active context object	Switches issue only.
context.clear_issue	dto.Empty	active context object	Clears the current issue selection.
context.clear	dto.Empty	active context object	Clears the entire active context.

Settings

Method	Request	Result	Notes
settings.get_all	dto.Empty	settings object	Full core-settings payload.
settings.get	dto.GetCoreSettingRequest	single setting result	Gets one core setting.
settings.patch	dto.PatchCoreSettingRequest	settings object	Patches one setting.
settings.put	dto.PutCoreSettingsRequest	settings object	Replaces multiple settings at once.
settings.away_mode	dto.AwayModeRequest	dto.OKResponse	Daemon-owned live away toggle; enabling records the daemon’s current logical date in canonical awayDates. awayModeEnabled and awayDates cannot be changed through generic settings patch/put.

The awayDates settings field is a sorted, deduplicated historical list. Manual away mode records the current logical date immediately. Configured weekday and explicit-date rules are recorded only when their logical date occurs. Removing a rule does not remove dates already recorded, and current rules are not evaluated retroactively by historical calculations.

Successful settings mutations emit settings.changed with a keys array containing the affected core-setting keys. Connected clients should reload settings when this event arrives.

Day-boundary settings use explicit schedule objects:

{
  "enabled": true,
  "defaultTime": "00:00",
  "weekdayOverrides": {
    "1": "08:30",
    "5": "09:00"
  }
}

The weekday keys are ISO weekdays (1 Monday through 7 Sunday). startOfDay defaults to enabled at 00:00; endOfDay defaults to disabled. The daemon’s local timezone is authoritative. SOD advances Crona’s logical current date; EOD only emits an event and alert.

Day-boundary events

events.subscribe can emit day.start and day.end events with this payload:

{
  "kind": "start",
  "dateBefore": "2026-07-28",
  "dateAfter": "2026-07-29",
  "effectiveLocalTime": "2026-07-29T08:30:00+05:30",
  "effectiveUtcTime": "2026-07-29T03:00:00Z",
  "timezone": "Asia/Kolkata",
  "occurrenceId": "day-boundary:start:2026-07-29T03:00:00Z:Asia/Kolkata",
  "logicalDate": "2026-07-29"
}

Clients should refresh date-scoped state on day.start. Clients reconnecting after a boundary should use health.get.currentDate rather than expecting a stale event to be replayed. EOD alerts use the day.boundary alert kind and are routed through the normal daemon notification and companion-delivery paths.

Boundary occurrence persistence uses UTC RFC3339 timestamps (scheduled_at_utc and claimed_at_utc) plus the timezone name used for the local decision. The local timestamp and logical dates in the event are presentation and calendar values for clients. Existing date-only domain fields such as check-in, habit, and daily-plan dates remain calendar dates; they must not be converted through UTC midnight because that would shift a user’s selected day when the timezone changes.

Operations Log

Method	Request	Result	Notes
ops.list	dto.ListOpsQuery	ops list	Lists ops with optional filters.
ops.latest	dto.ListLatestOpsQuery	ops list	Latest ops shortcut.
ops.since	dto.ListOpsSinceQuery	ops list	Lists ops since a timestamp.

Events

Event types live in shared/types/events.go.

Entity Lifecycle Events

• repo.created
• repo.updated
• repo.deleted
• stream.created
• stream.updated
• stream.deleted
• issue.created
• issue.updated
• issue.deleted
• habit.created
• habit.updated
• habit.deleted
• habit.completed
• habit.uncompleted
• checkin.updated
• checkin.deleted

Typical payload:

• types.IDEventPayload

Session And Timer Events

• session.started
• session.stopped
• timer.state
• timer.boundary
• timer.tick
• timer.break_deferral_warning
• timer.break_deferred

Payload notes:

• timer.boundary uses types.TimerBoundaryPayload
• timer.tick uses types.TimerTickPayload
• timer.state carries the current timer/session state snapshot
• timer.break_deferral_warning uses types.TimerBreakDeferralWarningPayload and includes the five-second warning, session ID, and suggested deferral duration.
• timer.break_deferred uses types.SessionEventPayload and is emitted after the daemon applies a companion action acknowledgement.

Settings Events

• settings.changed uses types.SettingsChangedPayload and includes the changed core-setting keys.

Context Events

• context.repo.changed
• context.stream.changed
• context.issue.changed
• context.cleared

Payload notes:

• context change events use types.ContextChangedPayload
• context.cleared uses types.ContextClearedPayload

Update Events

• update.status

Payload notes:

• carries the current shared update status snapshot used by the TUI and CLI