{"id":51194389,"url":"https://github.com/aryrabelo/omp-free-text","last_synced_at":"2026-06-27T18:31:24.931Z","repository":{"id":366622961,"uuid":"1272433660","full_name":"aryrabelo/omp-free-text","owner":"aryrabelo","description":"OMP harness extension: a free-text session-notes panel below the status line with a prompt queue and cross-session note browsing, persisted per repo/branch/session.","archived":false,"fork":false,"pushed_at":"2026-06-22T16:31:08.000Z","size":191,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T17:11:31.936Z","etag":null,"topics":["bun","cli","coding-agent","developer-tools","free-text","notes","oh-my-pi","omp","scratchpad","tui"],"latest_commit_sha":null,"homepage":"https://github.com/aryrabelo/omp-free-text","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aryrabelo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-17T15:52:09.000Z","updated_at":"2026-06-22T16:31:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aryrabelo/omp-free-text","commit_stats":null,"previous_names":["aryrabelo/omp-free-text"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/aryrabelo/omp-free-text","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryrabelo%2Fomp-free-text","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryrabelo%2Fomp-free-text/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryrabelo%2Fomp-free-text/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryrabelo%2Fomp-free-text/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aryrabelo","download_url":"https://codeload.github.com/aryrabelo/omp-free-text/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aryrabelo%2Fomp-free-text/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34864431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","cli","coding-agent","developer-tools","free-text","notes","oh-my-pi","omp","scratchpad","tui"],"created_at":"2026-06-27T18:31:23.858Z","updated_at":"2026-06-27T18:31:24.926Z","avatar_url":"https://github.com/aryrabelo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @aryrabelo/omp-free-text\n\n[![CI](https://github.com/aryrabelo/omp-free-text/actions/workflows/ci.yml/badge.svg)](https://github.com/aryrabelo/omp-free-text/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Runtime: Bun](https://img.shields.io/badge/runtime-Bun-000000.svg?logo=bun)](https://bun.sh)\n\nAn OMP (Oh My Pi) extension that gives you a free-text session-notes panel below the status line, persisted per repo, branch, and session — and doubles the note as a FIFO prompt queue you can drip-feed to the agent.\n\nIf this is useful to you, please ⭐ the repo — it helps others find it.\n\n## Contents\n\n- [What it does](#what-it-does)\n- [Install in another OMP](#install-in-another-omp)\n- [Usage](#usage)\n  - [Browse other sessions](#browse-other-sessions)\n  - [Prompt queue](#prompt-queue)\n  - [Copy the note](#copy-the-note)\n  - [Let the agent add tasks](#let-the-agent-add-tasks)\n  - [Generate a queue from a goal](#generate-a-queue-from-a-goal)\n  - [Configurable shortcuts](#configurable-shortcuts)\n- [Storage](#storage)\n- [Development](#development)\n- [Non-goals / Roadmap](#non-goals--roadmap)\n- [Contributing](#contributing)\n- [Security](#security)\n- [License](#license)\n\n## What it does\n\n- Shows a notes panel directly below the status line. It is a read-only preview: the note body followed by a dimmed hint that reads `(Ctrl+N · Ctrl+↓ queue · Ctrl+Shift+↓ auto)` by default (a trailing `▶` marks the toggle key while auto-run is on). The hint reflects your configured keys.\n- Lets you edit notes with the `Ctrl+N` keyboard shortcut or the `/note` slash command, which opens a multi-line editor (Enter saves, Shift+Enter newline, Esc closes with a save/discard confirm). `/note \u003ctext\u003e` appends `\u003ctext\u003e` straight to the queue without opening the editor.\n- Lets you browse notes from your other sessions with `/notes`.\n- Doubles the note as a prompt queue of markdown checkbox tasks: `Ctrl+↓` dispatches the head task and the panel shows its state as a glyph — `☐` pending, `▸` in-flight, `✓` done — while `Ctrl+Shift+↓` toggles auto-run (default keys — rebindable, see [Configurable shortcuts](#configurable-shortcuts)).\n- Copies the whole note to your system clipboard with `Alt+Shift+C` (OSC 52, works locally and over SSH).\n- Lets the agent add tasks to your note itself via the `note_add` tool — say \"coloca na nota ...\" and it appends a `- [ ]` line.\n- Turns a goal into a whole prompt queue with `/make-note \u003cgoal\u003e` — the agent decomposes it into sequential prompts (with `---` review barriers) and writes them via the `make_note` tool.\n- Saves notes to `~/.free-text/{repo}/{branch}/{session-id}.md`, where `repo` is the git repository directory name, `branch` is the current git branch, and `session-id` is the OMP session id. Outside a git repo it falls back to the current directory name and `no-branch`. Notes written before the root migration (under the legacy `~/.omp-free-text/...` root) are still read back automatically.\n- Saves notes when you close the editor and flushes them when the session shuts down.\n\n## Install in another OMP\n\nThe repo is public, so installing needs no GitHub authentication.\n\n```sh\nomp plugin install github:aryrabelo/omp-free-text\n```\n\nPin a branch, tag, or commit with `#ref`, e.g. `github:aryrabelo/omp-free-text#main`.\n\n### Local development\n\n```sh\ngit clone https://github.com/aryrabelo/omp-free-text.git\nomp plugin link ./omp-free-text\n```\n\n`link` symlinks the local checkout into `~/.omp/plugins`, so edits to the source are picked up on the next OMP start.\n\n### Verify, update, remove\n\n```sh\nomp plugin list                                    # confirm it loaded and is enabled\nomp plugin install github:aryrabelo/omp-free-text  # re-run to update\nomp plugin uninstall @aryrabelo/omp-free-text      # remove\n```\n\nAfter installing, start OMP in any repo: the notes panel renders below the status line, and `Ctrl+N` / `/note` open the editor.\n\n## Usage\n\nPress `Ctrl+N` or type `/note` to open the editor. Type freely, then close or submit the editor to save. The panel below the status line shows the latest note.\n\n### Browse other sessions\n\nType `/notes` to open a keyboard picker listing notes from your **other** sessions in the same repo and branch. Choose one to open it in a read-only viewer — handy for pulling context from a parallel or earlier session without leaving the current one.\n\n### Prompt queue\n\nThe note doubles as a FIFO prompt queue of markdown checkbox tasks. You type plain lines (or `-` bullets); on save they auto-normalize to `- [ ]` tasks, so you never type `[ ]` by hand. `#` headings and `\u003e` quotes stay prose and are never dispatched.\n\n- `Ctrl+↓` sends the head pending task to the agent and marks it `- [\u003e]` (in-flight); when the turn settles it becomes `- [x]` (done). The panel renders these states as glyphs — `☐` pending, `▸` in-flight, `✓` done.\n- A lone `---` line (3 or more dashes) is a human-in-the-loop barrier. `Ctrl+↓` on a barrier deletes that line instead of sending it, passing the checkpoint so the next `Ctrl+↓` resumes with the line below.\n- `Ctrl+Shift+↓` toggles auto-run, which feeds one queued line per agent settle (it primes the first line immediately if the agent is already idle). While auto-run is on the panel hint marks the toggle key with a trailing `▶`, e.g. `(Ctrl+N · Ctrl+↓ queue · Ctrl+Shift+↓ auto ▶)`.\n- Auto-run pauses at a `---` barrier (and, inside Herdr with `HERDR_ENV=1`, fires a `herdr notification show` ping with `--sound request` so the workspace alerts you). It also halts if a turn ends in error or is aborted.\n\n**Known limit:** OMP caps continuation chains at 8 (`SESSION_STOP_CONTINUATION_CAP`), so a barrier-free run drains at most ~8 lines per chain before pausing. Use `---` barriers to checkpoint longer queues.\n\n### Copy the note\n\nPress `Alt+Shift+C` to copy the whole note buffer to your system clipboard. It uses an OSC 52 escape, so it works both locally and over SSH. There is no text-selection model and `Ctrl+C` is reserved by OMP, so copy is whole-buffer and keyboard-only.\n\n### Let the agent add tasks\n\nThe agent can append tasks to your note itself through the `note_add` tool: say something like \"coloca na nota ...\" (or \"add to the list\", \"remember to ...\") and it appends a `- [ ]` line to the bottom of the current note. The tool is auto-available in every session once the extension is installed — no separate skill install.\n\n### Generate a queue from a goal\n\nType `/make-note \u003cgoal\u003e` to turn a high-level goal into a ready-to-drain prompt queue in one shot. The agent decomposes the goal into sequential prompts and writes them to the note via the `make_note` tool: one `- [ ]` task per step, indented detail lines sent together with their prompt, and a `---` human-in-the-loop barrier wherever it decides you should review before the queue continues. Then drive it with `Ctrl+↓` / auto-run like any other queue. (`/note \u003ctext\u003e` is the manual one-liner version — it appends a single `- [ ]` task without the agent.)\n\n### Configurable shortcuts\n\nAll three shortcuts are read once at startup from a global `~/.free-text/config.json` (not per repo/branch):\n\n```json\n{\n  \"shortcuts\": {\n    \"editNotes\": \"ctrl+n\",\n    \"queueStep\": \"ctrl+down\",\n    \"queueToggleAuto\": \"ctrl+shift+down\"\n  }\n}\n```\n\nOmit the file (or any key) to keep the defaults shown above. A missing or malformed entry falls back to its default and logs a warning. This is the escape hatch when your terminal does not emit a distinct `Ctrl+Shift+↓`: rebind `queueToggleAuto` to a combo it does send (e.g. `\"ctrl+b\"`). Use OMP `KeyId` syntax — lowercase `modifier+key`, modifiers `ctrl`/`shift`/`alt`/`super` (e.g. `\"alt+enter\"`).\n\n## Storage\n\nEach session gets its own markdown file under `~/.free-text/`, organized by repo and branch. The files are plain markdown, so you can read or edit them directly. Every changed save (including discarded drafts) is also appended to a sibling `{session-id}.history.md` file, giving you an append-only history of the note. Notes saved before the root migration live under the legacy `~/.omp-free-text/` root; they are still read back (active session and the `/notes` browser) but new writes always go to `~/.free-text/`.\n\n## Development\n\nThis is a TypeScript/Bun extension. The entry point is `src/main.ts`. Its pure logic (paths, queue, store, widget, editor, config) comes from the shared [`@aryrabelo/free-text-core`](https://github.com/aryrabelo/free-text-core) package, and the extension reads legacy `~/.omp-free-text/` notes for back-compat after the root migration to `~/.free-text/`.\n\n- Run unit tests with `bun test`.\n- Typecheck with `bun run typecheck`.\n- Lint and format with `bun run lint` (check) / `bun run format` (apply). Style is enforced by [Biome](https://biomejs.dev).\n\n## Non-goals / Roadmap\n\nThese are deliberately out of scope today, listed as boundaries rather than promises:\n\n- **Inline editable panel** via `setEditorComponent` (replacing the popup overlay) — edit in place below the status line instead of in a separate editor.\n- **Per-session history-version browsing** of the `.history.md` timeline — step through the append-only versions of a note.\n- **Clickable widget** — needs OMP SDK `onClick` support before the panel can react to mouse interaction.\n- **Optional Herdr companion pane** sharing the note file — surface the same note inside a Herdr workspace pane.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, gates, and commit conventions.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for the security policy and how to report vulnerabilities.\n\n## License\n\nMIT, Ary Rabelo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faryrabelo%2Fomp-free-text","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faryrabelo%2Fomp-free-text","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faryrabelo%2Fomp-free-text/lists"}