---
title: Notes
description: Vault layout, repository identity, and note safety rules.
---

`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.
