Metadata-Version: 2.4
Name: choom
Version: 0.0.3
Summary: A corporate-friendly Markdown notes engine that makes your AI happy.
License: MIT License
        
        Copyright (c) 2026 Ryan Stalets
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: pyyaml==6.0.3
Requires-Dist: textual==8.2.8
Provides-Extra: dev
Requires-Dist: mypy==2.3.0; extra == 'dev'
Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
Requires-Dist: pytest-xdist==3.8.0; extra == 'dev'
Requires-Dist: pytest==9.1.1; extra == 'dev'
Requires-Dist: ruff==0.16.0; extra == 'dev'
Requires-Dist: types-pyyaml==6.0.12.20260724; extra == 'dev'
Description-Content-Type: text/markdown

# choom

```
⠀⠀⠀⠀⠀⠀⠀⠀⣀⣀⣤⣤⣤⣤⣤⣄⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⢀⣠⣶⣾⡿⠿⢛⣛⣛⣛⡛⠻⠿⣿⣷⣦⡀⠀⠀⠀⠀⠀
⠀⠀⢀⣴⣿⡿⠛⠁⠀⣴⣿⣿⣿⣿⣿⣷⡄⠀⠉⠻⣿⣷⡀⠀⠀⠀
⠀⢀⣾⡿⠋⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⡧⠀⠀⠀⠈⠻⣿⣦⠀⠀
⢀⣿⡿⢁⣠⣤⣤⣤⣈⢿⣿⣿⣿⣿⣿⣿⠇⣠⣤⣤⣤⣀⠹⣿⣧⠀
⣼⣿⢳⣿⣿⣿⣿⣿⣿⣧⠙⢻⣿⣿⠛⢡⣾⣿⣿⣿⣿⣿⣷⣻⣿⡀
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⢸⣿⣿⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇
⣿⣿⠘⣿⣿⣿⣿⣿⣿⣿⡀⢸⣿⣿⠀⣸⣿⣿⣿⣿⣿⣿⡿⢹⣿⡇
⢿⣿⡄⠈⠙⠛⠟⠛⠙⢿⣿⣾⣿⣿⣾⣿⠟⠙⠛⠟⠛⠉⠀⣸⣿⠁
⠈⣿⣷⡀⠀⠀⠀⠀⠀⠀⠙⢿⣿⣿⡟⠃⠀⠀⠀⠀⠀⠀⣰⣿⡟⠀
⠀⠘⢿⣷⣄⠀⠀⠀⠀⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⢀⣴⣿⠟⠀⠀
⠀⠀⠈⠻⣿⣷⣄⡀⠀⠀⠀⢸⣿⣿⠀⠀⠀⠀⢀⣴⣿⡿⠃⠀⠀⠀
⠀⠀⠀⠀⠈⠙⠿⣿⣷⣶⣤⣼⣛⣻⣤⣤⣶⣾⡿⠟⠋⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠛⠛⠛⠛⠛⠛⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀
KEEP YOUR CORPO OVERLORDS HAPPY, FEED YOUR AI
```

**A corporate-friendly Markdown notes engine that makes your AI happy.**

A *choom* is Night City slang for a good friend — the one who's got your back. That's the job here: keeping you organized and your AI fed with context, corpo restrictions notwithstanding.

A local-only, terminal-based tool for capturing and organizing meeting notes, general notes, and tasks as plain markdown files — structured enough for a human to navigate through a TUI, and legible enough that an AI assistant can search and edit the vault through a CLI without any integration work.

## Why

Markdown is the native format of AI assistants — they read it, write it, diff it, and reason over it without an adapter layer. Almost nobody at a large company can actually work that way, because the sanctioned note-taking tools (OneNote, Confluence, SharePoint) lock notes behind proprietary formats and authenticated APIs, and markdown-first apps like Obsidian or Logseq are rarely on the approved-software list.

choom installs without admin rights, stores nothing outside a directory you already have, and needs no server or account — just a folder.

The tool disappears into the twenty seconds before a meeting starts. You type `/meeting.standup Q3 planning #platform`, a file exists with correct frontmatter and a date-stamped name, and you're typing notes before anyone has finished joining the call. You never decide where a file goes or what to call it.

## Usage

### Install

Requires Python 3.11+. Works on Windows, macOS, and Linux, with no network access needed after install.

```bash
uv tool install choom
```

**Coming from v0.0.1, when this project was called `endpaper`?** Rename the workspace marker directory — `mv .endpaper .choom` from the workspace root — and nothing else about the workspace changes. Ids written under the old `m_`/`n_`/`t_` prefixes keep resolving alongside the new `meeting_`/`note_`/`task_` ones; no existing file is rewritten.

### Create a workspace

**Cloud-synced folder? Pin it to this device first.** choom has no index — every command
reads whichever files are actually present, so a file that is only a cloud placeholder is
invisible to it, and to any assistant reading the folder. Turn off on-demand/online-only
storage for the workspace folder: **OneDrive** → "Always keep on this device"; **Dropbox** →
"Make available offline"; **Google Drive** → "Available offline"; **iCloud Drive** → keep it
downloaded and exclude it from "Optimize Mac Storage" (or it may be evicted later).

```bash
mkdir notes && cd notes
choom init
```

This creates `.choom/config.toml`, `AGENTS.md`, and `meetings/` in the current directory. This directory is now your workspace root — every command below runs from inside it.

### Capture a meeting

```bash
choom meeting new "Q3 planning" --type standup --tag platform
```

Prints the path to the new file: `meetings/2026-07-28-standup-q3-planning.md`, already stamped with frontmatter (`id`, `type`, `title`, `tags`, `created`, `updated`).

### Browse and list

```bash
choom meeting list --json
choom meeting list --type standup --since 2026-07-01
```

Or launch the TUI with no arguments:

```bash
choom
```

![Tasks collection: To-Do and Done categories on the left, open tasks in the middle, and the highlighted task's body on the right with two underlined links out to other records](docs/screenshots/tasks.png)

choom opens on **Tasks**; `tab`/`shift+tab` cycle the top bar between Tasks, Notes, and Meetings, whose path sits flush right in that same bar so you always know which workspace you're in. Each collection lists its records as four labelled columns — date, type, title, tags — that hold their position whether or not a record has a type or tags; on a narrow terminal the lower-priority columns drop before the date or title ever get squeezed. For Notes and Meetings the left pane lists months, most-recent-first, and only the month on screen is read from disk — a workspace with years of history costs the same to open as an empty one.

![Notes collection: month list on the left, August's notes in the middle, and a research note rendered on the right with a vendor comparison table and links back to the meetings it came from](docs/screenshots/notes.png)

`/` opens a permanent command bar — type `filter <term>` (or `f <term>`) to narrow the list live, or `meeting.standup <description>` and hit `enter` to create one, landing straight in the editor. Arrow keys move, `enter` opens the selected record in a rendered markdown preview, `e` drops into a raw editor from either the list or the preview, `b` toggles a pane showing what the record points at and what points back at it, `ctrl+d` deletes the highlighted record after a one-line confirmation naming it, `ctrl+o`/`ctrl+x` save, `esc` backs out. Every confirmation in the tool — discarding unsaved edits, deleting a record — is that same slim, centred bar: one question, `(Esc)` to stop and `(Enter)` to proceed, nothing to click. `/help` lists every command and key binding without leaving the screen, and the running version sits in the bottom-right corner.

![Raw markdown editor with line numbers, frontmatter, and prose containing inline markdown links whose targets carry an id fragment](docs/screenshots/edit-meeting.png)

### Ask an assistant from inside the document

Type `/ai <prompt>` on its own line in the editor and press `enter`:

![Editor with a 1:1 meeting note open and `/ai generate a list of action items` typed on its own line below the notes](docs/screenshots/ai-command.png)

The document saves, whichever assistant CLI you already have installed runs the prompt, and the reply lands where the command was:

![The same note with the /ai line replaced by two generated checklist items, the first carrying a markdown link through to the renewal meeting](docs/screenshots/ai-response.png)

While it works, the line shows `⋯` and the status bar offers `ctrl+c to cancel`. Cancelling — or any failure — restores the line exactly as you typed it, so a prompt is never lost.

### For AI assistants

An assistant working in a choom workspace reads `AGENTS.md` at the root and takes it from there — non-interactive, `--json`-capable, and scriptable by design. Nothing opens an editor or blocks on a prompt.

Below, an assistant is asked to pull up a vendor sync meeting, research the competitor options it calls for, and write up its findings — reading and writing the vault the same way it reads and writes a codebase:

![AI assistant reading meeting notes, researching, and writing a new note via the CLI](docs/screenshots/execute-task.png)

The note it produced shows up like any other — because it is:

![The assistant's research note, rendered back in the TUI](docs/screenshots/research-note.png)

Run `choom --help` for the full command reference. The `AGENTS.md` that `init` writes into your workspace documents the folder layout, the frontmatter schema, the task line format, link syntax, and the exit codes.

## Features (v0.0.3)

- **Meeting notes** — `/meeting.standup Q3 planning #platform` creates a dated, frontmatter-tagged file and drops you straight into the editor. Browse with `/meetings` or `tab`; the left pane lists months, most-recent-first; `/filter <term>` (or `/f <term>`) narrows across every month; open with `enter`.
- **General notes** — `/note` opens (or creates) today's daily note; `/note.research vendor landscape #procurement` creates a typed note. Browse with `/notes` or `tab`.
- **Tasks** — `/task.followup send the vendor comparison #procurement` appends a checkbox line to `tasks.md`. `/tasks` or `tab` opens on **To-Do**; `space` toggles a task done, moving it to the **Done** category in the left pane. A task can carry an optional markdown body — details, a running log — stored as indented lines beneath its checkbox line; it renders in the preview pane when the task is highlighted, and `e` opens the editor scoped to just that body. Empty until you type something, and a save that changes nothing writes nothing. `choom task show <id>` prints a task and its body from the CLI; `task list --json` carries `body` on every entry. The file stays hand-editable plain markdown — no database.
- **Inline task capture** — inside any meeting or note, typing `/task <description>` (or `/task.<type> <description>`) on its own line and pressing `enter` captures a task without leaving the editor: the line becomes a checklist item linking to it, `- [ ] [call Terry about the renewal](../../../tasks.md#task_a1b2)`, cursor at its end, nothing else on screen moving. Prefix an existing line with `/task.followup ` to promote its own words into the task instead. That checklist item is a **two-way control surface**, not a copy — tick it and save, or tick the task from the tasks list, and the other side follows; opening a document brings every mirror in it into agreement with `tasks.md` first, so nothing shown is ever stale, with no repair command and no background process. `choom task add "<description>" --link <id>` does the same capture from the command line, and `task done`/`undone --json` report which documents were updated. The same syntax is available to `/ai`: a `/task` line an assistant writes in its reply is captured exactly as if you had typed it, and the reply comes back with a real, linked task in place of that line.
- **Document links** — any record can point at any other, as an ordinary markdown link: `See [Q3 planning](../../../meetings/2026/07/2026-07-28-q3-planning.md#meeting_20260728_a1b2c3d4)`. The `#id` fragment is what choom resolves and never changes; the path is derived so the link is clickable in any plain markdown viewer, and it's recomputed whenever the target moves. Write just the fragment — `[Q3 planning](#meeting_20260728_a1b2c3d4)` — and the path fills itself in on the next save; nobody has to count `../`. `b` opens a pane of outbound and inbound links in any preview, `/link <search terms>` inserts a correct link without leaving the editor — when the terms match more than one record, a short list rises in the same status-bar region instead of failing closed, showing each candidate's title, collection, and date, with `↑`/`↓` to move, `enter` to insert, and `esc` to leave the typed line untouched — and `choom links <id> --direction in` answers what points at a record from the command line. `choom links check` separates **stale** links (fixable) from **dead** ones (need a decision) and `choom links heal` repairs every stale one. Nothing is indexed or cached — inbound links are computed by scanning, measured at 155 ms across 6,000 documents.
- **Workspace init** — `choom init` sets up a workspace (config, `AGENTS.md`, `meetings/`, `notes/daily/`, `tasks.md`) in the current directory. Multi-user shared workspaces are planned but not in v0.0.3 — tracked in [issue #18](https://github.com/rstalets/choom/issues/18).
- **View and edit** — highlighting a record and pressing `e` opens the editor in place of the preview pane — the list, the links pane, and the top bar all stay on screen, and the highlighted row never moves. Opening a record full-screen first (`enter`, then `e`) still edits full-screen. Line numbers, soft wrap, and `ctrl+o` (stay) / `ctrl+x` (save and return) work the same either way. The cursor starts on an empty line one blank line below whatever is already there, so appending a thought costs no cursor-movement keystrokes. `esc` discards, but only prompts when there's something to lose; `ctrl+q` prompts the same way rather than quitting outright when it would discard an unsaved edit. `ctrl+s` is also bound as a save alias, but `ctrl+o` is the canonical key: some terminals treat `ctrl+s` as the legacy XOFF flow-control signal and swallow it before it ever reaches choom. If saves with `ctrl+s` seem to do nothing, run `stty -ixon` in that shell (or use `ctrl+o` instead).
- **Delete a record** — `ctrl+d` on a highlighted meeting, note, or task in the TUI raises a one-line confirmation naming it; confirm and it's gone, decline and nothing changes. `choom meeting delete <id> --force` (`note`/`task` the same way) does it from the command line — the flag is required, so the command never prompts and never blocks. Deleting a task leaves its checklist mirrors elsewhere untouched, in whatever words you wrote them, rather than rewriting or stripping your line. There's no trash and no undo: once confirmed, the record is gone.
- **AI-friendly CLI** — every TUI action has a non-interactive CLI equivalent backed by the same core library: `--json` on every read command, meaningful exit codes, data on stdout and errors on stderr, nothing that opens an editor or blocks on input. Assistants create records through the commands, so frontmatter and file placement stay correct, then edit the markdown bodies directly like any other file.
- **`/ai` in the editor** — type `/ai <prompt>` on its own line and press `enter`: the document saves, your already-installed Claude Code CLI or GitHub Copilot CLI runs the prompt, and the reply lands where the command was. The line shows `⋯` and the status bar names a random breadcrumb plus `ctrl+c to cancel` while it works; every failure — cancelled, no reply, the assistant errored — restores the line exactly as typed. Which assistant to call is detected automatically when only one is installed, or set explicitly with `choom config assistant <claude|copilot|none>` (CLI) or `/config assistant <value>` (TUI command bar) — a workspace with neither tool installed keeps every other feature unchanged.
- **Assistant discovery file** — naming an assistant (`choom config assistant <claude|copilot>`, `/config assistant <value>`, or `choom init --assistant <value>`) also drops a short, choom-owned pointer into that assistant's own user-scope location outside the workspace — `~/.claude/skills/choom/SKILL.md` for Claude Code, `~/.copilot/skills/choom/SKILL.md` for Copilot CLI — so the assistant knows choom exists and where this workspace is even when started from an unrelated directory. It restates nothing `AGENTS.md` already says, is rewritten in full every time the assistant is (re)configured, and setting the assistant to `none` removes it. On a machine with exactly one assistant installed and none configured, choom offers to install it once, at first launch, through the same confirmation bar used everywhere else in the TUI — answered or not, it's never asked again.
- **No index, no database** — the markdown files are the only state; nothing to corrupt, nothing to reindex. Every list load and every document open reads straight from disk at that moment, not from a snapshot taken at launch, so a change made by an assistant (or by hand) in another process shows up the next time you look. An open list also re-reads on its own every 2 seconds, re-rendering only when something actually changed and holding your selection steady; typing into the command bar's filter never stalls waiting on this, since the pool it searches is hydrated in the background as soon as the bar opens.
- **`AGENTS.md`** — generated at `init`, under ~100 lines, so an assistant landing in the workspace is productive immediately.

Everything above has landed on `main` as of v0.0.3 — see [Releases](https://github.com/rstalets/choom/releases) for what has been published to PyPI.

## License

See [LICENSE](LICENSE).
