# Notes > Standalone CLI and MCP server for repo-scoped Markdown notes. # Overview Source: https://notes.timmo.dev/ `notes` manages repository notes in a Git-backed vault and exposes the same behaviour through a CLI and an MCP server. **Project notes** Store Markdown notes under `projects/{owner}/{repo}` using a Git remote or a local project identity. **Safe writes** Reads, writes, and deletes are constrained to the notes vault, then committed and best-effort pushed. **Handoffs** Handoffs are ordinary notes tagged `handoff`, using the same priority metadata as other notes. **MCP server** The same note operations are exposed as raw-text MCP tools for agent harnesses. ## Start Here **[Install](/install)** Install from the AUR or build the binary locally with mise. **[Quick Start](/quick-start)** List, read, write, and serve notes over MCP. **[Notes](/notes)** Understand the vault layout, frontmatter, and safety model. **[MCP Server](/mcp-server)** Expose notes to MCP-compatible agents over stdio. ## Documentation Scope This repo owns the standalone CLI and MCP server. OpenCode plugins and slash commands that consume `notes` live in dotfiles/OpenCode config. ## Machine-readable docs | URL | Use | | ------------------------------------- | ---------------------------------------- | | https://notes.timmo.dev/llms.txt | Compact page index | | https://notes.timmo.dev/llms-full.txt | Full docs bundle | | https://notes.timmo.dev/mcp | Hosted MCP (search, page and navigation) | | `/{route}.md` | One page as Markdown | --- # CLI Source: https://notes.timmo.dev/cli The `notes` CLI is the direct interface to the same note service exposed through MCP. ```bash notes list notes read --path notes write --path --stdin notes handoffs notes mcp ``` Use `notes --help` or `notes --help` for terminal help. The [command reference](/cli/commands/) is generated from the same Effect command tree. Shell completions are generated by [`notes --completions`](/cli/completions/). --- # Command Reference Source: https://notes.timmo.dev/cli/commands This page is generated from the same `Command` values that parse and run the CLI. ## `notes root` ```text DESCRIPTION Print the notes vault root USAGE notes root [flags] FLAGS --projects Print the projects directory GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) EXAMPLES notes root notes root --projects ``` ## `notes context` ```text DESCRIPTION Resolve project-note context for integration plugins. USAGE notes context [flags] FLAGS --command string Integration command name requesting context --json Emit structured context JSON GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) EXAMPLES notes context --command notes-list notes context --command note-reference --json ``` ## `notes list` ```text DESCRIPTION List repository notes USAGE notes list [flags] FLAGS --all Show notes from every projects directory --tag string Only include notes with this tag --format choice Output format (choices: labels, json) GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) EXAMPLES notes list notes list --all notes list --tag handoff ``` ## `notes search` ```text DESCRIPTION Search repository note metadata USAGE notes search [flags] FLAGS --query string Fuzzy search text --all Show notes from every projects directory --tag string Only include notes with this tag --format choice Output format (choices: labels, json) GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) EXAMPLES notes search --query architecture --format labels ``` ## `notes read` ```text DESCRIPTION Print a note file USAGE notes read [flags] FLAGS --path path Absolute path to a note file inside the notes vault --json Emit content and revision hash as JSON GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes write` ```text DESCRIPTION Write stdin to a note file, then commit and push it USAGE notes write [flags] FLAGS --path path Absolute path to a note file inside the notes vault --stdin Read note content from stdin --expected-hash string Fail if the existing note no longer has this SHA-256 hash --json Emit the complete mutation result as JSON GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes delete` ```text DESCRIPTION Delete a note file, then commit and push it USAGE notes delete [flags] FLAGS --path path Absolute path to a note file inside the notes vault --json Emit the complete mutation result as JSON GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes move` ```text DESCRIPTION Move a note to another known repository scope USAGE notes move [flags] FLAGS --path path Absolute path to a note file inside the notes vault --to string Existing or remembered repository scope --json Emit the complete mutation result as JSON GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes create` ```text DESCRIPTION Create a note from stdin, then commit and push it USAGE notes create [flags] FLAGS --repository string Repository scope for the new note --kind choice Note template kind (choices: note, handoff) --name string Note name --description string Note description --stdin Read the note body from stdin --json Emit the complete create result as JSON GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes targets` ```text DESCRIPTION List known repository targets USAGE notes targets [flags] FLAGS --format choice Output format (choices: labels, json) GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes agents` ```text DESCRIPTION List installed agent targets USAGE notes agents [flags] FLAGS --format choice Output format (choices: labels, json) GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes active-count` ```text DESCRIPTION Emit the focused Herdr pane's project note count and paths as JSON, including handoffs USAGE notes active-count [flags] GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes priority` ```text DESCRIPTION Set a note priority, then commit and push it USAGE notes priority [flags] FLAGS --path path Absolute path to a note file inside the notes vault --value choice New priority (choices: low, medium, high, critical) --json Emit the mutation result as JSON GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes open-agent` ```text DESCRIPTION Open a note in an installed agent through Herdr USAGE notes open-agent [flags] FLAGS --path path Absolute path to a note file inside the notes vault --agent string Command from notes agents --mode choice Agent opening mode (choices: default, plan) --json Emit the opened workspace and tab IDs GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes handoffs` ```text DESCRIPTION Browse handoff-tagged notes USAGE notes handoffs [flags] FLAGS --all Show notes from every projects directory --list List handoffs to stdout instead of opening the TUI --format choice Output format (choices: labels, json) GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes mcp` ```text DESCRIPTION Run the notes MCP server over stdio USAGE notes mcp [flags] GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes capture` ```text DESCRIPTION Process a captured note through local OpenCode USAGE notes capture [flags] FLAGS --config path Daemon YAML configuration path --status Check local processor availability --stdin Read captured note text from stdin --repository string Target repository (omit for Automatic) --json Emit a machine-readable result GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes daemon` ```text DESCRIPTION Process captured notes through local OpenCode USAGE notes daemon [flags] FLAGS --config path Daemon YAML configuration path --once Process one queue snapshot and exit GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) ``` ## `notes agent` ```text DESCRIPTION The Code Mode tools the OpenCode plugin registers USAGE notes agent [flags] GLOBAL FLAGS --help, -h Show help information --version, -v Show version information --wizard Start wizard mode for a command --completions Print shell completion script (choices: bash, zsh, fish, powershell, sh, pwsh) --log-level Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) SUBCOMMANDS tools Print the Code Mode tools as JSON call Run a Code Mode tool in the current repository, with its input as JSON on stdin, and print its result as JSON ``` --- # Shell Completions Source: https://notes.timmo.dev/cli/completions `notes` can print completion scripts for Bash, Fish, and Zsh: ```bash notes --completions bash notes --completions fish notes --completions zsh ``` The Arch packages install Bash, Fish, and Zsh completions automatically. For a local binary, write the generated script into the shell-specific completion directory for your environment. --- # Install Source: https://notes.timmo.dev/install ## Arch Linux Install the stable binary package with an AUR helper: ```bash yay -S repo-notes-bin ``` Install `repo-notes-git` instead to track relevant changes on `main`: ```bash yay -S repo-notes-git ``` Both packages install Git, the `notes` binary, and Bash, Fish, and Zsh completions. ## Runtime requirements The compiled `notes` binary includes its JavaScript dependencies and does not need Bun or Node.js at runtime. It uses these external applications for specific features: | Application | Used by | | ------------- | -------------------------------------------- | | Git | Repository detection and vault versioning | | Bash | Launching an editor from the interactive TUI | | Neovim | Default editor when `EDITOR` is unset | | OpenCode | The TUI's `o` and `O` actions | | `notify-send` | Optional MCP write and delete notifications | | GitHub CLI | Queued capture daemon mode | Git is installed by the Linux packages. Set `EDITOR` and `VISUAL` to use other editors instead of Neovim. Missing `notify-send` only disables desktop notifications. The [capture processor](/integrations/capture-daemon/) needs a configured OpenCode CLI in both queued and direct modes. Stable releases use a semver version shared by the CLI and `@timmo001/effect-notes`. Create a blank GitHub draft tagged with it, optionally generate its release notes, then publish it to build Linux archives, deb and RPM packages, publish the library to npm and JSR, and update `repo-notes-bin`. ## Build Locally Use the mise tasks to install dependencies and build the binary. The repo pins Node and Bun through mise. ```bash mise run install mise run build ``` The compiled binary is written to `dist/notes`: ```bash ./dist/notes --help ``` ## Build an Arch Package Create a local Arch package from the compiled binary: ```bash mise run package:arch ``` This task is Arch-specific and needs `makepkg` from `base-devel`. The package is written to `dist/` and includes shell completions. --- # Capture processor Source: https://notes.timmo.dev/integrations/capture-daemon The notes daemon polls a private GitHub issue queue, claims each issue with a temporary processing label, runs its captured text through the OpenCode V2 CLI, and posts the result before closing the issue. The same processor also accepts a capture directly, without the web app or GitHub queue: ```sh printf 'Investigate this note' | notes capture \ --config ~/.config/notes/daemon.yml \ --stdin \ --repository owner/repository \ --json ``` Omit `--repository` to use Automatic repository resolution. Check whether the configured executable is available with `notes capture --config ~/.config/notes/daemon.yml --status --json`. This check does not start OpenCode or a model. The capture form validates the same version 1 text, timestamp, request ID, source, and optional repository fields as the web capture. The [Notes Capture Omarchy plugin](/integrations/omarchy-capture/) uses this direct mode through a host-owned wrapper. Direct captures do not need GitHub CLI authentication or pass through the GitHub issue queue. Run one pass while testing configuration: ```sh notes daemon --config ~/.config/notes/daemon.yml --once ``` Omit `--once` for the supervised polling loop. Both modes use the same command configuration and model fallback chain. ```yaml repository: owner/private-notes queueLabel: agent:ready workerId: desktop workerActor: github-user opencodeCommand: opencode2 opencodeArgs: [] opencodeDirectory: ~/.config/dotfiles opencodeAgent: notes-daemon opencodeModels: - providerID: github-copilot modelID: gpt-5.6-sol variant: low - providerID: github-copilot modelID: claude-opus-4.8 variant: low allowedReadPaths: - ~/repos/** - ~/.config/dotfiles/** - ~/.config/bootstrap/** - ~/.config/waybar/** - ~/.config/uwsm/** sessionTimeoutSeconds: 300 passTimeoutSeconds: 900 commandTimeoutSeconds: 30 consecutiveFailureLimit: 3 pollIntervalSeconds: 30 ``` The GitHub CLI must be authenticated with issue and repository write access. Each daemon process claims an issue with a visible `agent:processing::` label and deletes that temporary label when processing finishes. A process proceeds only while its label is the sole processing label on the issue. `opencodeCommand` is an optional executable name or path, defaulting to `opencode2`. `opencodeArgs` is an optional argv prefix, defaulting to `[]`. Notes uses that launcher and prefix for setup and `run --server
--session --format json --agent notes-daemon --model provider/model#variant --title ... -- prompt`, with `opencodeDirectory` as the working directory. Arguments are passed literally without a shell; only a leading `~` in the executable path is expanded. Readiness checks only that executable, not its prefix arguments or model access. Before each model attempt, Notes checks `service status` and requires the default OpenCode V2 server to be running. All subsequent CLI commands pin that address with `--server`. Notes obtains the existing password with `service get password` and passes it through `OPENCODE_PASSWORD`, keeping it redacted in the Effect workflow and out of command arguments. No standalone server, SDK or direct HTTP client is used. Setup uses the CLI's `api` subcommand: wait for plugin activation at the configured location, resolve the capture agent, create a session with explicit permissions, then read it back through a separate CLI process. Both responses must retain the requested agent, location and exact ordered permissions, and the read-back ID must match. Missing or changed policy fails the attempt before any prompt. Every fallback repeats setup with a fresh session. Notes supplies the dedicated `notes-daemon` agent and base configuration under `.opencode-daemon/`. The host creates `opencodeDirectory` before launching Notes and installs these files there as project configuration, with its `allowedReadPaths`. A launcher may refresh that configuration before setup commands, but must preserve the configured location. The existing server loads the capture agent and tools for that location, while retaining its own credentials and global configuration. Setting isolated XDG paths on a client does not isolate an already-running server. `opencodeModels` is an ordered fallback chain. Notes reads final assistant text from stdout JSON events and keeps stderr separate. A model result must explicitly report success after writing the note; a reported failure, malformed result, command failure, or timeout advances to the next model. `sessionTimeoutSeconds` covers setup and execution together for each attempt, so `passTimeoutSeconds` must leave enough time for every configured attempt and cleanup. The session policy starts with deny-all and replays the resolved agent rules in order, retaining denials and intentional exceptions and converting approval requests to denials. Allowances are limited to read/glob/grep, web research, GitHub and Exa tools, external directories, and Notes MCP list/read/write. Broad or unrelated tool allowances are discarded. Shell, direct filesystem edits, questions, delegation, browser tools and note deletion remain denied. Session rules override agent rules in OpenCode, so preserving the ordered restrictions matters. This flow is verified against OpenCode 2.0.3. The supplied configuration uses a read-only GitHub MCP endpoint. Keep that endpoint and credential isolation: the `github_*` permission itself does not distinguish reads from writes. MCP permissions use resource `*`, so Notes write permission cannot enforce exactly one call or restrict repository arguments. Those remain agent instructions and MCP service responsibilities. Native grep remains enabled for repository research. In OpenCode 2.0.3 it checks the search root and query, but does not apply file-read denials to matched contents. Sensitive-file read denials therefore do not prevent those files appearing in grep results within authorised search roots. Hosts requiring that stronger boundary should deny grep in the agent policy. The agent must investigate before writing. Notes record the repository paths or primary sources inspected, evidence-based findings, and the requested output, such as an implementation plan. A capture cannot complete by merely paraphrasing its issue text; if the available read tools cannot support the investigation, the daemon leaves the issue open as failed. A failed issue receives one bounded, sanitised error summary when the daemon has an actionable typed error. Unknown failures use a generic public message. Complete error objects remain in daemon logs rather than exposing stack traces, credentials, request bodies, or filesystem paths in GitHub comments. OpenCode infers the target repository from the capture and writes under `projects/{owner}/{repo}`. Captures without a resolvable repository use `projects/local/captures`. Completion comments report the note commit SHA rather than exposing a local filesystem path. Claim labels are ownership checked before GitHub mutations. The daemon does not automatically take over stale claims; remove an `agent:processing:*` label manually only after confirming its worker is no longer processing the issue. Session, queue-pass, and external command timeouts are configured in daemon YAML. On timeout or cancellation, Notes terminates the child process group and allows ten seconds before forcing termination, leaving time for a configured wrapper to finish its own cleanup. Cancellation does not start a fallback. Persistent pass failures exit after the configured threshold so systemd can restart the daemon. --- # Omarchy plugin Source: https://notes.timmo.dev/integrations/omarchy-capture The Notes plugin adds a persistent service, bar widget, and keyboard-first panel to Omarchy Quattro. It uses the Notes CLI for note management and keeps local capture as one panel subview. ## Requirements - Omarchy Quattro - [Notes installed](/install/) and available on `PATH` - A configured Notes vault - `notes-capture-local` on `PATH` for capture Install and enable the standalone plugin after reviewing its source: ```bash omarchy plugin add https://github.com/timmo001/omarchy-notes.git ``` For an unattended installation from a repository you trust: ```bash omarchy plugin add https://github.com/timmo001/omarchy-notes.git --enable --yes ``` ## Browse and search Select the Notes widget to open an overview with Notes, Handoffs, New note, New handoff, and Capture note actions. Notes and Handoffs show entries from every repository. Each view provides repository, tag, and priority filters; modified and name sorting in either direction; and repository, priority, or ungrouped display. Typing runs a debounced ranked search across all repositories. Search ranking comes from: ```text notes search --query --all --format json ``` Normal lists use `notes list --all --format json`. Up and Down move the cursor, Enter opens an item, and the selected row is kept visible. Escape clears the active filter before going back. Tab switches bar panels where the shell supports it. ## Note actions The detail view shows repository, tags, priority, modified time, and rendered Markdown. Its action menu can: - edit the full Markdown content in the panel - open the note in an external editor - open the note using any target returned by `notes agents --format json` - set low, medium, high, or critical priority - move to a target returned by `notes targets --format json` - delete after an explicit confirmation Native edits read the current content and revision hash with `notes read --json`, then submit content on standard input to `notes write --stdin --expected-hash ... --json`. Ctrl+Enter saves. Mutating commands are serialised, and successful mutations refresh the list. New note and New handoff provide native forms for repository, name, description, and Markdown content. They submit content on standard input to `notes create`. ## Capture Capture note retains the local capture workflow. The host-owned wrapper must support: ```text notes-capture-local --status --json notes-capture-local --stdin --json [--repository owner/repository] ``` The status command exits with zero when available. The submission command reads the capture from standard input and returns JSON with `"status": "success"`. It normally forwards to a configured [capture processor](/integrations/capture-daemon/). Ctrl+Enter sends a capture. Submissions run one at a time, further submissions wait in memory, and closing the panel does not cancel them. A shell restart loses the pending queue. Failures save the submitted text and send a local notification. Optional repository choices are read from: ```text ${XDG_CACHE_HOME:-$HOME/.cache}/dot/notes-capture-repositories.json ``` ```json [ { "label": "Display name", "repository": "owner/repository" } ] ``` The current draft and latest failed submission are stored unencrypted at: ```text ${XDG_CACHE_HOME:-$HOME/.cache}/dot/notes-capture-draft.txt ${XDG_CACHE_HOME:-$HOME/.cache}/dot/notes-capture-failed-draft.txt ``` ## IPC The `timmo.notes` target provides `open`, `close`, `show`, `hide`, `toggle`, and `capture`. The capture method opens the panel directly in the capture subview. ```bash omarchy-shell timmo.notes toggle omarchy-shell timmo.notes capture ``` ## Update and remove ```bash omarchy plugin update timmo.notes omarchy plugin remove timmo.notes ``` Removing the plugin does not remove Notes, capture services, configuration, credentials, targets, or drafts. Plugin publication from the Notes repository is independent of stable CLI releases. ## Security The plugin runs unsandboxed inside `omarchy-shell`. It starts local Notes, capture, editor, agent, and notification commands. The QML does not make direct network requests, but Notes mutations may commit and push, and capture may use the configured OpenCode command. Review the plugin and host configuration before installation. --- # OpenCode Source: https://notes.timmo.dev/integrations/opencode `notes` owns the standalone CLI, MCP server, OpenCode plugin, and portable [`notes-cli`](https://github.com/timmo001/notes/tree/main/.agents/skills/notes-cli) and [`notes-mcp`](https://github.com/timmo001/notes/tree/main/.agents/skills/notes-mcp) Agent Skills. Slash commands, guards, and integration-specific skills are maintained outside this repo because they are part of the agent configuration layer. ## Plugin The OpenCode plugin in `opencode-plugin/` adds a `notes` Code Mode namespace, so an agent can list, search, read, create and change the session repository's notes and handoffs in one script. Load it from the repository: ```json { "plugins": ["github:timmo001/notes#main::path:opencode-plugin"] } ``` It reads its tools from `notes agent tools --json` and runs each with `notes agent call` in the session's directory, so they always match the `notes` on your `PATH`. Tools that change notes, such as `write`, `create` and `move`, ask first, and commit and push like the CLI. ## Context Integrations can read structured context from: ```bash notes context --command notes-list --json ``` ## MCP The MCP server is configured with the `notes` key: ```json { "mcp": { "notes": { "type": "local", "command": ["notes", "mcp"], "enabled": true } } } ``` With that key, raw MCP tools such as `note_read` and `note_write` are exposed to OpenCode as `notes_note_read` and `notes_note_write`. Import the skill for the transport agents should use: `notes-cli` for shell commands or `notes-mcp` for MCP tools. --- # Web Capture Source: https://notes.timmo.dev/integrations/web-capture The capture PWA creates private queue issues in a configured notes repository. Cloudflare Access restricts the application to configured identities, and the Worker validates the Access token before serving the application or accepting captures. ## Capture Type into the capture field and submit the note for local processing. You can use the phone's voice keyboard or desktop speech-to-text when needed. When `CAPTURE_REPOSITORIES` is configured, the form also provides a searchable target repository picker and remembers the last valid explicit selection in browser storage. Its default **Automatic** option leaves the target unspecified so the daemon can infer it from the capture context, falling back to `projects/local/captures`. The value is a JSON array of `{ "label": "Display name", "repository": "owner/repo" }` records. The API validates every explicit selection against this server-owned list and records it as issue metadata. It never uses the target as the issue destination. Submitting always creates an issue in the private queue repository configured by `GITHUB_OWNER/GITHUB_REPO`, with the fixed `agent:ready` label. The issue records the target repository, request identifier, typed capture source, and timestamp for later local processing. ## Install and updates The page is an installable PWA: it offers an install banner until you turn it down once, and an Install button stays in the header. It can also receive shares: share text or a link to Capture from another app and it is added to the note, never replacing what is already written. Each build has a version. The page sends it with every API call, and the Worker answers `426` to a page from another build. The page then reloads once onto the new build, keeping the note, or shows a banner asking for a reload if that didn't help. ## Development The PWA is a separate application under `capture/` so the Starlight documentation deployment remains static and independent. A Lit form is built by Vite and served as static assets by a Cloudflare Worker, whose Effect `HttpRouter` handles the Access check and the `/api/repositories` and `/api/captures` routes. The Worker runs first for every request, so the page itself stays behind Cloudflare Access. ```bash mise run capture:dev mise run serve:capture mise run serve:capture:status mise run serve:capture:logs mise run serve:capture:restart mise run serve:capture:stop mise run capture:check mise run capture:build ``` `serve:capture` runs the Vite dev server through Pitchfork on port 7490, or the next free port, at `https://capture.notes.localhost` through the Pitchfork proxy. Capture type-checking runs the Effect-patched TypeScript 7 compiler with plain `tsc`. Local development bypasses Cloudflare Access and requires `GITHUB_TOKEN` in `capture/.dev.vars` to exercise issue creation. Never commit that file. Copy `capture/.dev.vars.example` to `capture/.dev.vars` for local configuration. Production configuration stays outside this public repository. ## Deployment [`capture/alchemy.run.ts`](https://github.com/timmo001/notes/blob/main/capture/alchemy.run.ts) is the Worker's [Alchemy](https://alchemy.run) stack: the `notes-capture` Worker, its custom domain, the Vite build's assets and the plain `ACCESS_AUD`, `ACCESS_TEAM_DOMAIN`, `GITHUB_OWNER`, `GITHUB_REPO`, `CAPTURE_REPOSITORIES` and `QUEUE_LABEL` vars. The Deploy capture workflow runs `mise run capture:deploy` on pushes to `main` that touch `capture/`. `GITHUB_TOKEN` is a Worker secret set in Cloudflare, outside the stack, and deploys leave it alone. The stack reads the vars as `CAPTURE_*` names (`CAPTURE_GITHUB_REPO` for `GITHUB_REPO`, and so on). CI gets them from the repository's secrets and variables; locally they come from the ignored `capture/.env.prod`, not `.env`, which Wrangler would load as dev vars. `mise run docs:deploy:github` writes that file's values into the repository, so change a var there, deploy the github stack, then deploy capture. `mise run capture:plan` shows what a deploy would change. `capture/wrangler.example.jsonc` only gives the Vite plugin and `wrangler types` the Worker's shape for development and the build. --- # MCP Server Source: https://notes.timmo.dev/mcp-server `notes mcp` starts a Model Context Protocol server over stdio. It speaks JSON-RPC on stdout and sends logging to stderr so the protocol stream stays clean. ```json { "mcp": { "notes": { "type": "local", "command": ["notes", "mcp"], "enabled": true } } } ``` The server exposes note tools for reading, listing, writing, and deleting vault files. Reads include a SHA-256 revision that writes can use to reject stale content. See the generated [MCP tool reference](/mcp-server/tools) for tool parameters. Successful writes and deletes send a desktop notification when `notify-send` is available. Notifications are best-effort, so the operation still succeeds when `notify-send` is missing or cannot reach a notification service. ## Tools Agent harnesses prefix tool names with the server key. With the server configured as `notes`, `note_read` appears as `notes_note_read`. ## Results and Code Mode Each tool declares an `outputSchema` and returns its result as `structuredContent`, alongside the same text content as before. Clients that type results from the schema, such as OpenCode's Code Mode, can chain calls without parsing text: ```js const { notes = [] } = await tools["notes"].note_list({ tag: "handoff" }); const note = await tools["notes"].note_read({ path: notes[0].filePath }); await tools["notes"].note_write({ path: note.path, content: `${note.content}\n- Picked up\n`, expectedHash: note.hash, }); ``` `note_list` returns `{ notes }` for the current project, or `{ sections }` grouped by project when `all` is set. `note_write` and `note_delete` return the path, the Git commit and push outcome, and the rendered `output`; `note_write` also returns the new `hash`. ## Resources - `notes://context` - repo-note context for the current repository. - `notes://command/{name}` - help text for a notes command. Resources are a progressive enhancement; tools are the primary interface. --- # MCP Tool Reference Source: https://notes.timmo.dev/mcp-server/tools ## `note_read` Read the full content and SHA-256 revision of a note file from the notes vault. CLI equivalent: `notes read --path ` | Parameter | Type | Default | CLI | Description | | --------- | ------ | ------- | --------------- | ------------------------------------------------------ | | `path` | string | | `--path ` | Absolute path to the note file inside the notes vault. | ## `note_list` List note files in the notes vault for the current project, optionally filtered by tag or grouped across all projects. CLI equivalent: `notes list [--all] [--tag ] --format json` | Parameter | Type | Default | CLI | Description | | --------- | ------- | ------- | ------------- | ------------------------------------------------------------- | | `tag` | string | | `--tag ` | Optional tag to filter notes by, for example handoff. | | `all` | boolean | false | `--all` | List notes from all projects instead of just the current one. | ## `note_write` Write a note file to the notes vault, then commit and best-effort push it. CLI equivalent: `notes write --path --stdin` | Parameter | Type | Default | CLI | Description | | -------------- | ------ | ------- | -------------------------- | ------------------------------------------------------------------------- | | `path` | string | | `--path ` | Absolute path to the note file to create or overwrite. | | `content` | string | | `stdin` | Full file content to write, including frontmatter and body. | | `expectedHash` | string | | `--expected-hash ` | Optional SHA-256 revision from note_read used to reject stale overwrites. | ## `note_delete` Delete a note file from the notes vault, then commit and best-effort push it. CLI equivalent: `notes delete --path ` | Parameter | Type | Default | CLI | Description | | --------- | ------ | ------- | --------------- | ----------------------------------------- | | `path` | string | | `--path ` | Absolute path to the note file to delete. | --- # Notes Source: https://notes.timmo.dev/notes `notes` stores Markdown files in a Git-backed vault and opens an interactive browser when run without a command. The default vault is `~/Documents/notes`; set `NOTES` to use a different path. `DOT_NOTES_DIR` is still read as a compatibility fallback when `NOTES` is unset. ## Browse ```bash notes notes --all ``` The TUI is a document-first browser. Wide terminals use a 35/65 split between the note list and Markdown preview. When both pane minimums no longer fit, it switches to a one-pane master/detail layout while preserving each pane's selection and scroll position. Terminals below the compact floor show a stable resize screen instead of a broken workspace. The preview keeps the title and priority summary visible above the document. Metadata is expanded by default in split mode and collapsed in master/detail mode. Toggle it with `i`; your choice persists for the rest of the TUI session. The bottom command bar only shows commands relevant to the active pane, while `?` opens the complete grouped shortcut reference. Useful controls: | Key | Action | | ------------------- | ----------------------------------- | | `up` / `down` | Move through notes | | `Tab` | Switch between list and preview | | `Enter` | Open the selected note preview | | `/` | Search note names, tags and summary | | `s` | Cycle sorting | | `v` | Toggle current repo/all repos | | `a` / `A` | Create a note in editor/visual | | `e` / `E` | Edit in editor/visual | | `o` | Open the full note in OpenCode | | `O` | Plan from the full selected note | | `d` | Delete after confirmation | | `r` | Refresh | | `i` | Toggle preview metadata | | `?` | Open grouped keyboard help | | `Esc` / `Backspace` | Exit or go back | Editor actions are launched through Bash and must stay attached until editing finishes. Set `EDITOR` for terminal editing and use a waiting visual command such as `VISUAL="code --wait"` for `A` and `E`. Both modes fall back to Neovim when no editor is configured. The `o` and `O` actions require OpenCode. `O` adds portable built-in planning instructions to the full selected note context. OpenCode runs from the selected note's source checkout, including when Notes was opened from another directory or with `--all`. Notes remembers exact checkout paths as machine-local state under `$XDG_STATE_HOME/notes`; paths are not written into portable note files. A local note whose remembered directory no longer exists keeps the Notes process's current directory. ## Layout Repository notes live under: ```text {vault}/projects/{owner}/{repo}/{slug}.md ``` The `{owner}/{repo}` segment is resolved from the current Git repository's remote URL. `notes` prefers `origin`, then `upstream`, then the first remote, so a fork keeps its notes under its own owner. To use another remote for one checkout, set it in that checkout's Git config, for example `git config notes.remote upstream`. When no usable remote exists, notes use `projects/local/{project}`. The project name comes from the Git worktree root, or from the current directory outside Git. ## Frontmatter Notes are ordinary Markdown files with YAML frontmatter: ```yaml --- repo: owner/repo date: 2026-07-06T12:00:00+01:00 name: Useful Note description: One-line summary. tags: [research, handoff] priority: medium --- ``` `name`, `description`, `tags`, and `priority` are used for listings. Writes validate the frontmatter and refresh `date:` automatically. The body is free-form Markdown. A few paragraphs with no headings is a perfectly good note. ## Safety Read, write, and delete operations are restricted to physical Markdown files under `projects/{owner}/{repo}`. Symlinks, special files, malformed project identities, and paths elsewhere in the vault are rejected. Writes use atomic replacement, and draft creation never overwrites an existing filename. Before a mutation, `notes` refuses an existing staged index and rebases safely onto the configured upstream. Mutations are serialized across processes, committed to the vault Git repo, and then pushed when a remote exists. Editor sessions hold the same transaction lock until the resulting note is validated and committed. A commit or push failure is reported as partial success because the local file change has already completed. `notes read --json` and MCP `note_read` return a SHA-256 revision. Pass it to `notes write --expected-hash` or MCP `note_write.expectedHash` to reject a stale overwrite. ## Listing ```bash notes list notes list --format json notes list --all notes list --tag research ``` The JSON form returns structured note metadata for scripts and plugins. --- # Handoffs Source: https://notes.timmo.dev/notes/handoffs Handoffs are normal notes with a `handoff` tag. They are used by agent workflows to pass context between sessions. ```yaml --- repo: owner/repo date: 2026-07-06T12:00:00+01:00 type: handoff name: Checkout Flow Handoff description: Current state and next steps for checkout work. priority: medium tags: [handoff] --- ``` ## Priority Note priority can be `low`, `medium`, `high`, or `critical`. Missing priority is treated as `medium`. ```bash notes handoffs notes handoffs --all notes handoffs --list notes handoffs --format json ``` `notes handoffs` opens the same two-pane TUI as `notes`, filtered to notes tagged `handoff`. Use `--list` when you want stdout output for scripts or non-interactive shells. `notes handoff` is an alias for `notes handoffs`. The handoff view uses the same priority-aware controls as the main notes TUI: | Key | Action | | --- | ----------------------------------------- | | `g` | Toggle grouping by priority | | `p` | Change the selected note's priority | | `s` | Cycle sorting within the current grouping | ## Instructions The standalone `notes` tool only owns storage and listing semantics. Handoff authoring instructions live in the consuming agent configuration, such as the dotfiles handoff skill. --- # Quick Start Source: https://notes.timmo.dev/quick-start Install `notes` first, or build locally and substitute `./dist/notes` for `notes` in the examples below. ## Inspect the Vault ```bash notes root notes root --projects ``` The vault defaults to `~/Documents/notes`. Set `NOTES` to use another Git-backed vault. ## List Notes Run list commands from a project directory. `notes` prefers `owner/repo` from a Git remote, then falls back to `local/` using the Git root or current directory name. ```bash notes list notes list --format json notes list --all notes list --tag handoff ``` ## Read and Write ```bash notes read --path ~/Documents/notes/projects/owner/repo/topic.md notes write --path ~/Documents/notes/projects/owner/repo/topic.md --stdin < topic.md ``` Writes validate and refresh frontmatter, create parent directories, commit the changed note, and best-effort push the vault when it has a remote. Use `notes read --json` and pass its `hash` back with `--expected-hash` when an overwrite must fail if another process changed the note. ## Handoffs Handoffs are normal notes tagged `handoff`, written as an instruction for the next session. `notes handoff` starts a draft with a title and a `Next` heading; use as much or as little structure as the work needs. ```bash notes handoffs notes handoffs --all notes handoff ``` ## MCP Server Start the stdio server from an MCP client: ```bash notes mcp ``` OpenCode exposes the tools with the server key prefix, for example `notes_note_read` and `notes_note_write` when the server is configured as `notes`.