manage-notes

name	manage-notes
description	Manage the Notes window — creating, searching, editing, and automating notes via the SDK and automation protocol.

Manage Notes

Create and automate notes in Script Kit's floating Notes window.

Where Notes Live

Notes are stored in SQLite at ~/.scriptkit/db/notes.sqlite. The Notes window manages them directly. Scripts and agents must use the runtime write ports (kit/notes_create, kit/notes_update, kit/notes_delete) or the Notes automation target; do not raw-write the database.

Every active note is also mirrored as a read-only markdown file at ~/.scriptkit/notes/<slug>-<id8>.md, so external tools (grep, editors, git) can read note content as plain files. The mirror is write-through from the app; treat the files as read-only — edits to them are not synced back and are overwritten on the next save.

Opening the Notes Window

• Hotkey: Cmd+Ctrl+N by default — override with notesHotkey or disable with notesHotkeyEnabled: false in config.ts
• From the launcher: Search for "Notes" in the main menu

Configuring the Hotkey

// ~/.scriptkit/config.ts
notesHotkey: {
  modifiers: ["meta", "shift"],
  key: "KeyN"
}

Notes Window Features

• Markdown editing with formatting toolbar
• Multiple notes with a Cmd+P note switcher
• Full-text search across all notes
• Tags from frontmatter or #tag markdown
• Wiki-style links and backlinks from [[Note Title]]
• Soft delete with trash and restore
• Export to plain text, Markdown, or HTML
• Character count in footer

Creating and Organizing Notes

Use the MCP notes tools when creating or organizing notes from an agent. They route through the app runtime, save any dirty open Notes editor before mutation, update the durable metadata index, and optionally open/select the changed note in the Notes window.

{
  "name": "kit/notes_create",
  "arguments": {
    "title": "Project Plan",
    "body": "# Project Plan\n\n#planning [[Research Notes]]",
    "tags": ["planning", "projects/script-kit"],
    "aliases": ["Plan"],
    "open": true,
    "select": true
  }
}

{
  "name": "kit/notes_update",
  "arguments": {
    "id": "NOTE_UUID",
    "content": "# Project Plan\n\nUpdated body with [[Decision Log]].",
    "tags": ["planning", "decisions"],
    "aliases": ["Plan", "Project Plan"],
    "open": true,
    "select": true
  }
}

Tags and aliases passed to the mutation tools are written into visible YAML frontmatter so users can edit them directly. Markdown #tags and [[Wiki Links]] are indexed from the note body. Backlinks are derived from the normalized link index; they are not copied into note content.

Read kit://notes to inspect organized notes. The resource returns each note's tags, aliases, outbound link count, and backlink count, and supports ?tag=..., ?alias=..., ?link=..., or ?q=... filters. Add &full=true to get complete note bodies instead of 240-char previews (bounded to 20 notes by default). Read kit://notes/{id} for full note content plus the same metadata.

Instruction Notes

Notes tagged #instructions (or tags: [instructions] in frontmatter) are standing agent guidance: new Agent Chat threads automatically stage kit://notes?tag=instructions&full=true as context, so the agent reads them at thread start. Use this for durable user preferences, style rules, or project conventions that should apply to every conversation.

Provenance

Notes created from Agent Chat ("Save as Note") carry source: scriptkit://agent-chat/{thread_id} frontmatter linking back to the originating conversation. kit/notes_create accepts an optional source string for the same purpose.

Automation Targets

The Notes window is a first-class automation target. Use target: { "type": "kind", "kind": "notes" } to address it.

Semantic IDs

Semantic ID	Element
panel:notes-window	The Notes window container
input:notes-editor	The active editor area

Query Elements

{
  "type": "getElements",
  "requestId": "elm-notes",
  "target": { "type": "kind", "kind": "notes" },
  "limit": 10
}

Wait for Notes Window

{
  "type": "waitFor",
  "requestId": "w-notes",
  "target": { "type": "kind", "kind": "notes" },
  "condition": {
    "type": "elementExists",
    "semanticId": "input:notes-editor"
  },
  "timeout": 3000,
  "pollInterval": 25
}

Batch Commands

{
  "type": "batch",
  "requestId": "b-notes",
  "target": { "type": "kind", "kind": "notes" },
  "commands": [
    { "type": "setInput", "text": "Hello from automation" }
  ]
}

Agent Chat Handoffs

Use the Notes UI actions for cross-surface handoffs:

• Send to Agent Chat — opens or focuses Agent Chat with the active note content
• Save as Note — creates or updates a note from Agent Chat-generated content

These are UI actions, not JavaScript globals. The current public Notes script surface is the automation target (kind: notes) plus the runtime MCP notes tools above unless real Notes functions are added to scripts/kit-sdk.ts.

Common Pitfalls

• No raw DB access: Do not read/write notes.sqlite directly from scripts. Use the MCP notes tools for creation/update/delete and the automation protocol for window/editor control.
• Default hotkey: The Notes window toggles with Cmd+Ctrl+N unless overridden via notesHotkey or disabled via notesHotkeyEnabled: false.
• Automation target must be open: getElements and batch commands targeting Notes require the Notes window to be open. Use waitFor with a timeout to handle the case where it is not yet visible.
• No invented JS globals: The current public Notes script surface is the automation target (kind: notes) and MCP notes tools. Do not document or rely on notesOpen(), notesCreate(), or similar JavaScript globals unless they are added to scripts/kit-sdk.ts.

Related Examples

• Canonical: ~/.scriptkit/plugins/examples/scriptlets/notes/main.md — copy-ready Notes automation payloads for getElements, waitFor, and batch
• Compatibility mirror: ~/.scriptkit/plugins/examples/scriptlets/notes.md — auto-generated flat copy of the canonical source

Related Skills

• start-chat — send note content into Agent Chat and continue there
• add-actions — expose note-related actions in the Actions Menu
• new-scriptlet — package Notes automation helpers as scriptlet bundles

Done When

• Notes window opens and is addressable via automation target
• kit/notes_create can create a tagged/linked note and open/select it in Notes
• getElements returns elements with panel:notes-window and input:notes-editor semantic IDs
• batch commands successfully set editor content