# Sir Scribbles A small ACP (Agent Client Protocol) chat sidebar for your notes. Obsidian on macOS is the currently supported host. The plugin is intended to work with multiple ACP agents; Kiro V3 CLI is the currently supported provider, with its launch arguments and permission handling implemented today. Other ACP providers are planned and are not yet selectable or validated. Obsidian hosts the plugin; the ACP agent supplies the conversation and tools. ## Disclosures - **Runs an external program.** The plugin starts the Kiro CLI executable you choose, only when you click **New chat** or **Past chats**, or send your first prompt. Each chat tab runs its own Kiro process (up to five at once). It never installs, updates or downloads anything. - **Requires a Kiro account.** Kiro needs its own login; the plugin stores no credentials and has no payment features. - **Network access through Kiro.** The plugin itself makes no network requests. Kiro sends your prompts, attached note text, and any images or text files you attach to its AI provider. - **Files outside the vault.** Kiro starts in the vault folder but can read, write or run anything its own permissions allow, including outside the vault. Actions Kiro asks about appear in the sidebar for approval; actions already allowed by Kiro's configuration may run without asking. - **Saved approval rules.** Choosing **Always allow** or **Always deny** asks Kiro to save a rule for this vault in its workspace `permissions.yaml`, under `~/.kiro/workspace-roots/` outside the vault. Kiro then applies it without asking, in every chat. The plugin never writes that file itself. - **No telemetry or ads.** The plugin keeps conversations in memory only. Kiro keeps its own chat history; **Past chats** asks Kiro for it. The only saved settings are the executable path, the floating chat preferences (on or off, opacity, window size) and the chat text font and size, stored on this device. ## Install Sir Scribbles requires Obsidian 1.5.0 or later on macOS and an already installed and signed-in Kiro CLI (see [below](#installauthenticate-kiro-separately)). - **Community plugins:** in Obsidian, open **Settings → Community plugins → Browse**, search for **Sir Scribbles**, install it and enable it. - **Manually:** download `main.js`, `manifest.json` and `styles.css` from the [latest release](https://github.com/cabra-arretado/sir-scribbles/releases/latest) into `YOUR_VAULT/.obsidian/plugins/sir-scribbles/`, then enable **Sir Scribbles** under **Settings → Community plugins**. Open the sidebar through the ribbon button or the **Sir Scribbles: Open chat** command. ## Use the sidebar 1. On first setup, enter the absolute path to your already installed Kiro executable. The path is saved and reused; later chats show **New chat** without asking for the path again. Change it under **Settings → Community plugins → Sir Scribbles** if the executable moves or startup fails. Settings also provides **Validate and save**, which checks the file without running it. 2. Review the displayed vault directory. With a saved executable, sending your first prompt starts ACP and sends after initialization succeeds, using the agent's default model. To choose another model, click **New chat** first and pick it from the composer; when the model offers more than one reasoning effort level, an effort picker appears beside it. **New chat** starts the chat straight away; it does not list past chats. Opening the sidebar or typing never starts a process. Starting Kiro may initialize its configured hooks and MCP servers. To continue an earlier conversation, click **Past chats**. This starts Kiro and lists the chats it has kept for this vault, newest first. Choose one to reopen it with its history, or **New chat**. Reopened messages show no time, because the agent does not send one. Typing a prompt in the list starts a new chat. Agents that cannot list or reopen chats say so here. 3. Type a prompt. Select text in a Markdown editor and click **+ Selection** to capture only that text, with its relative note path and line range. Inspect, replace or remove the snapshot before sending. Changes to the note do not change the attachment. A selection-only prompt is supported. Alternatively, click **+ File** above the message field to attach only the current note's vault-relative path. A checkmark shows it is attached. Kiro can read the saved file using its own tools; unsaved edits are not sent. The file path and a selected-text snapshot can be attached together. Remove each separately, or click the checked file button to clear the file path. To attach images or text files, paste them into the message field (a screenshot or a file copied in Finder), drop them on it, or click the paperclip. Images (PNG, JPEG, GIF, WebP) appear as thumbnails and go to the agent as images; larger ones are scaled to 2048 px on the longest side first. Text files (Markdown, code, CSV, JSON and similar UTF-8 files) appear with their name, and their contents are quoted into the prompt. Hover a thumbnail or file and click its **×** to remove it. A prompt carries up to 8 files, of which up to 4 images and 5 MB of images in total. Images need an agent that accepts them; if it does not, nothing is sent and the draft is kept. 4. Click **Send** or press Enter. Shift+Enter inserts a newline. Bot replies render Markdown; prompts, context previews, and tool activity stay plain text. Messages have timestamps and Copy controls that preserve the source. An activity row above the message box shows **Thinking…**, **Responding…**, or **Using tools…** while the agent works, with animated dots that respect reduced motion. Raw HTML and images stay inert; web links, including bare `https://` addresses, open only when clicked. Note links (`[[Note|Label]]`, Markdown note paths, absolute or `file://` paths inside the vault, and `obsidian://open` links to this vault) open through Obsidian when clicked. Headings and block references are supported. Cmd/Ctrl+click opens a new tab. Relative paths use the note attached or active when the prompt was sent, even if you switch notes later. 5. Review the approval card before choosing. It says in plain words what Kiro wants to do (for example "Kiro wants to write to a file in this vault"), lists the affected paths relative to the vault, marks any **Outside vault**, and previews the content to write, the text to replace, or the command to run. The full request stays under **Technical details**. **Allow once** and **Deny once** apply to this request only. When Kiro offers **Always allow** or **Always deny**, they appear on a second row, and the card says what the rule covers. Choosing one asks Kiro to save that rule for this vault only, in Kiro's own workspace settings outside the vault, and Kiro stops asking for matching actions in every chat. Kiro reads rules as patterns, so a folder rule also covers everything inside it. The plugin never widens the rule or saves it for all projects. Always choices are hidden when Kiro marks the request as not persistable, when its workspace is not this vault, when the request carries metadata the plugin does not recognize, or when the resource contains pattern characters (`* ? [ ] { } \`), which would make the saved rule wider than the request. To edit or remove a saved rule, change Kiro's workspace `permissions.yaml` (under `~/.kiro/workspace-roots/`). Partial requests use earlier details from the same tool call; missing arguments are identified in the approval card. Unsupported consent semantics still cancel the request. Existing Kiro policy may allow actions without asking the sidebar. 6. **Stop** requests cancellation and disables approvals. **Force stop agent** becomes available after five seconds if the turn is still unsettled. 7. Chats open in tabs at the top of the sidebar. **+** opens another chat, up to five; each has its own Kiro process, model, approvals and status dot, and keeps running while you look at another tab. Closing a tab confirms discarding its content, ends its process and keeps Kiro's own history, so it can be reopened later. Closing the panel or unloading the plugin discards client content and stops every owned process group. A tab whose cleanup is uncertain stays open with **Force stop agent** until recovery succeeds. ### Floating chat Turn on **Settings → Sir Scribbles → Floating chat** to chat without opening the sidebar. A chat icon appears in the status bar; click it, or run **Sir Scribbles: Show or hide floating chat**, to open a window over your notes. The window is translucent while you are not using it, so your notes show through. While **Floating chat** is on, two settings appear beneath it, each from 40% to 100%: **Opacity while in use** applies while the pointer is over the window or you are typing in it (default 100%), and **Opacity when not in use** applies the rest of the time (default 85%). To resize the window, drag the small grip in its top-left corner, or focus the grip and use the arrow keys; it grows up and to the left. These settings and the window size are stored on this device, like the executable path. The sidebar and the floating window show the same chats, one place at a time: opening the window moves your chats, drafts and attachments into it, and the sidebar offers **Show chats here** to move them back. The window's sidebar button does the same. Hiding the window (its **−** button, the status bar icon or Escape) keeps every chat running; the icon shows a dot while a chat is working, yellow when one is waiting for your approval. With floating chat on, closing the sidebar keeps chats running for the window. Turning floating chat off while the sidebar is closed opens the sidebar if any chat has messages, a draft or work in progress, so nothing is lost; otherwise it ends the idle chats. On a normal Obsidian quit, the plugin registers an awaited cleanup task: it ends ACP, sends SIGTERM to its owned process group, and escalates to SIGKILL after two seconds if needed. Each conversation is discarded from the sidebar; reopening the sidebar starts with one fresh tab. Crashes, force quits, and descendants that detach from the process group cannot be guaranteed to clean up. Only the executable path, the floating chat preferences (on or off, opacity, window size), the chat text settings and the experimental switches are saved, in this device's local storage. The plugin does not archive prompts, attachments, transcripts, session IDs or tool details. Past chats come from the agent each time you open the list. Kiro/provider history, inherited environment, hooks, MCP servers and native permissions remain outside the plugin's control. The vault directory is context, not a sandbox. ### Chat text Under **Settings → Sir Scribbles → Chat text**, choose the **Font** for messages and the prompt: Obsidian's interface font (default), your note text font, the monospace font, or **Custom**, which takes the name of any font installed on this device, such as `Fira Code` (no quotes needed; separate fallbacks with commas). **Text size** sets the size in pixels, from 10 to 28; its reset button returns to the theme's size. Headings, tables and code in replies scale with it. Timestamps, tool output and the start screen keep Obsidian's interface sizes. Both settings apply wherever the chats are shown: the sidebar, a sidebar moved to its own window, or the floating chat. They are stored on this device, for this vault. ### Slash commands (experimental) Turn on **Settings → Sir Scribbles → Experimental → Slash commands** to have a chat list the commands its agent offers. Typing `/` at the start of an empty prompt opens the list; keep typing to filter it. Use the arrow keys and Enter or Tab, or click, to put a command in the prompt, add any arguments, then send it. Escape closes the list. The list comes from the agent (ACP `available_commands_update`), so it can differ between chats and agent versions, and stays empty until the agent sends one. A chosen command is sent as an ordinary prompt; the plugin does not run commands itself. Kiro CLI V3 runs some of its terminal commands, such as `/model`, only through its own client, so not every Kiro command is available here. The switch is off by default and is stored on this device, for this vault. ## Help your agent write clickable links The plugin does not add instructions to your prompts. To have the agent write links the sidebar can open, paste this into the instruction file your agent reads from the vault root (for example `AGENTS.md`, `CLAUDE.md` or a Kiro steering file). Replace the ticket URLs with your own tracker's. ```markdown ## Replying in Sir Scribbles (Obsidian sidebar) Replies are shown as Markdown in an Obsidian sidebar. Write links so they can be clicked: - **Notes:** use wikilinks with paths relative to the vault root: `[[Projects/Launch notes|Launch notes]]`. - Link to a heading with `[[Note#Heading]]` and to a block with `[[Note#^block-id]]`. - Inside a table, escape the pipe: `[[Note\|Label]]`. - Markdown links also work, but encode spaces: `[Launch notes](Projects/Launch%20notes.md)`. - **Web pages:** always write the full `https://` address, e.g. `[Docs](https://example.com/docs)`. `example.com` without `https://` stays plain text. - **Tickets and PRs:** link to them, never just the ID: `[PROJ-123](https://yourcompany.atlassian.net/browse/PROJ-123)`, `[owner/repo#42](https://github.com/owner/repo/pull/42)`. - **Not supported:** images, `![[embeds]]` and raw HTML appear as plain text. Paths outside this vault can't be opened. - Name notes by their vault path so the user can open them, e.g. `[[Daily/2026-10-07]]`, not "today's note". ``` ## Install/authenticate Kiro separately The [official download page](https://kiro.dev/downloads/) provides this command: ```sh curl -fsSL https://cli.kiro.dev/install | bash kiro-cli login command -v kiro-cli ``` The [authentication guide](https://kiro.dev/docs/getting-started/authentication/) documents the terminal login flow. The plugin neither installs nor authenticates Kiro. ## Development Requires Node.js 22+. Runtime uses Node/Electron built-ins, Obsidian's supplied API, and the pinned markdown-it parser bundled into `main.js`. Build and test dependencies are pinned. ```sh npm ci --ignore-scripts npm test npm run check npm run build ``` The build writes `main.js` to the repository root, beside `manifest.json` and `styles.css`, and copies all three files into `dist/sir-scribbles/`. `main.js` is not committed; releases attach it. To release, bump the version in `manifest.json`, `package.json` and `versions.json`, then push a tag equal to that version (for example `0.0.2`, no `v`). The workflow builds a draft release to review and publish.