Advanced Features

Periodic Notes

Periodic Notes are a type of Registered Note that automatically resolve to a date-based file path. Use {date-format} placeholders in the path field — any path containing {...} is treated as a periodic note.

Template Syntax

Placeholders use DateFormatter patterns:

Pattern	Output	Example
yyyy	4-digit year	2026
MM	2-digit month	02
dd	2-digit day	23
EEEE	Full weekday name	Monday

Path examples:

# Single-level daily notes
path: ~/Notes/daily/{yyyy-MM-dd}.md
# → ~/Notes/daily/2026-02-23.md

# Nested year/month/day
path: ~/Notes/{yyyy}/{MM}/{dd}.md
# → ~/Notes/2026/02/23.md

Rollover Delay

For late-night work sessions, rollover_delay shifts the logical date boundary past midnight.

notes:
  - path: ~/Notes/daily/{yyyy-MM-dd}.md
    rollover_delay: 2h

With rollover_delay: 2h, at 1:30 AM the note still resolves to yesterday's date. The rollover happens at 2:00 AM instead of midnight.

Format: Nh (hours) or Nm (minutes) — e.g. 2h, 30m.

Template File

When a periodic note's file doesn't exist yet, Chirami creates it automatically. If template is specified, the template file is copied as the initial content:

notes:
  - path: ~/Notes/daily/{yyyy-MM-dd}.md
    template: ~/Notes/templates/daily.md

Without template, an empty file is created.

Navigation

Periodic notes show navigation controls in the title bar:

• ◀ / ▶ — Navigate to the previous or next existing file matching the template pattern.
• Today — Jump to the current logical date (respecting rollover_delay).

A background timer checks every 60 seconds whether the logical date has changed. If you're viewing "today" and the date rolls over, the note automatically switches to the new day's file. The same switch also happens when a hidden window is shown — if the date changed while the window was hidden, it opens to today's note.

Smart Paste

Cmd+V triggers Smart Paste, which converts clipboard content to Markdown before inserting. Use Cmd+Shift+V for plain text paste.

Conversion Rules

Clipboard Content	Result
URL	[page title](url) (title fetched asynchronously)
HTML	Converted to Markdown (headings, lists, links, tables, etc.)
JSON	Wrapped in a ```json code block
Multi-line code	Wrapped in a ``` code block
Plain text	Inserted as-is

Content types are detected in this priority order: HTML → URL → JSON → Code → Plain text.

Settings

smart_paste:
  enabled: true         # Set to false to disable (Cmd+V falls through to normal paste)
  fetch_url_title: true  # Set to false to skip title fetching for URLs

When fetch_url_title is enabled, Chirami inserts [](url) immediately, then replaces the empty title with the fetched page title (from og:title or <title> tag) within a 5-second timeout.

Karabiner-Elements Integration

Chirami can set a Karabiner-Elements variable when a note window gains or loses focus. This lets you define Karabiner key remappings that only apply while editing a Chirami note.

Chirami Config

karabiner:
  variable: chirami_active
  on_focus: 1
  on_unfocus: 0

Karabiner-Side Condition

In your Karabiner rule, add a condition to match the variable:

{
  "type": "variable_if",
  "name": "chirami_active",
  "value": 1
}

This lets you, for example, remap keys for Markdown editing only while a Chirami window is focused.

The cli_path field is optional — Chirami auto-detects the karabiner_cli binary location. Set it explicitly if the binary is in a non-standard location.

Transient Note

Use position: cursor to create a note that appears at the mouse cursor. Cursor notes start unpinned by default — they hide automatically when focus is lost. Useful for scratch-pad or quick-capture workflows.

notes:
  - path: ~/Notes/scratch.md
    title: Scratch
    hotkey: cmd+shift+s
    position: cursor

Press the hotkey → the note pops up at your cursor → type your note → click elsewhere and it vanishes. Click the pin button (📌) to keep it visible.

Images

Image Paste

Paste an image from the clipboard (Cmd+V) to save it as a PNG file and insert a Markdown image link.

![](attachments/image-a1b2c3d4.png)

Details:

• If the clipboard contains both text and an image, text takes priority (normal paste)
• File names are generated from the SHA256 hash of the image content (image-<hash>.png)
• Pasting the same image multiple times reuses the existing file (no duplicates)
• The link is inserted as a relative path from the note file

Display

Images are scaled to fit the window width.

• By default, images stretch to the full window width (minus left/right margins)
• Aspect ratio is preserved
• Maximum height is capped at 400px

Delete

Hover over an image to reveal a delete button (×) at the top-right corner. Click the button to remove the image's Markdown link from the note.

• The deletion is undoable (Cmd+Z)
• The image file itself is not deleted immediately — orphaned files are cleaned up on app startup (see Orphaned Image Cleanup)

Resize

Drag the right edge of an image to resize it. The cursor changes to a resize cursor (↔) when hovering near the right edge.

• Drag right to enlarge, left to shrink (minimum width: 50px)
• On release, the final width is written into the Markdown as ![alt|width](url)
• The resize is undoable (Cmd+Z)

You can also set the width manually in Markdown using ![alt|width](url) syntax:

![screenshot|300](image.png)

• A number after | sets the display width in pixels
• If the specified width exceeds the window width, the image is scaled down to fit
• Without a width specification, the image fits to the window width

Attachment Directory

Configure the image storage directory with attachment.dir.

notes:
  - path: ~/Notes/todo.md
    attachment:
      dir: attachments/

Resolution order:

1. Per-note attachment.dir if set
2. Static notes: <note-stem>.attachments/ (same directory as the note)
3. Periodic notes: template path's parent directory + attachments/

Path formats:

Path	Resolves to
~/Pictures/chirami/	Expanded from home directory
/absolute/path/	Used as-is
attachments/	Relative to the note's parent directory

Orphaned Image Cleanup

On app startup, Chirami automatically deletes image files that are no longer referenced by any note.

• Runs in the background without affecting startup speed
• Only targets files matching the image-*.png pattern
• Scans the Markdown content of all notes to identify referenced images
• For periodic notes, checks image references across all files matching the template pattern

CLI

See CLI for usage details.

Tips

Dotfiles Management

config.yaml lives at ~/.config/chirami/config.yaml — a standard XDG path. Symlink or include it in your dotfiles repository. state.yaml is stored separately at ~/.local/state/chirami/state.yaml and should not be version-controlled.

Obsidian Daily Notes Compatibility

Point a periodic note's path to the same directory Obsidian uses for Daily Notes. Both tools work on the same plain .md files with no conflicts:

notes:
  - path: ~/Obsidian/Vault/Daily/{yyyy-MM-dd}.md
    title: Daily
    rollover_delay: 2h
    template: ~/Obsidian/Vault/Templates/Daily.md

Tiling Window Manager Coexistence

Chirami note windows are ignored by tiling window managers like aerospace by default. Notes float independently without disrupting your tiled layout — no extra configuration needed.