feat(cli): add Rich human-readable output to bm tool commands#967
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 457cd0ed3b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
This is good to go, but needs to ship in v0.next |
There was a problem hiding this comment.
Pull request overview
This PR adds human-friendly terminal output to key bm tool subcommands while preserving script-friendly JSON behavior, introducing a centralized output-mode resolver and a new config knob to control interactive defaults.
Changes:
- Adds Rich (Panels/Tables/Trees/Markdown) and
--plainoutput modes tobm toolcommands with a precedence matrix and mutual-exclusion validation for--json/--plain. - Introduces
cli_output_style: "rich" | "plain"config option (and env override) to control the default interactive output style when stdout is a TTY. - Adds a comprehensive new test suite covering mode precedence, escaping, frontmatter handling, and known API quirks.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
src/basic_memory/cli/commands/tool.py |
Implements output mode resolution plus Rich/plain renderers for search-notes, read-note, build-context, and recent-activity. |
src/basic_memory/config.py |
Adds the cli_output_style configuration field and description for interactive CLI defaults. |
tests/cli/test_cli_tool_rich_output.py |
Adds extensive tests for Rich/plain/JSON behavior, flag precedence, escaping, and frontmatter rendering rules. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
83f6005 to
af94435
Compare
|
@codex review |
|
recheck |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: af944354ea
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
|
recheck |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cea9aa922b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
|
recheck |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3d2dfee1f0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
search-notes, read-note, build-context, and recent-activity now display formatted Rich output (tables, panels, Markdown rendering) when stdout is an interactive TTY. When piped or redirected the commands continue to emit raw JSON exactly as before. A new --json flag is available on each command to force JSON output even in a TTY. Follows the bm status / bm project list precedent: Rich by default for humans, JSON for machines. Closes #678 Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Drew Cain <groksrc@gmail.com>
…Result shape
_display_build_context was reading top-level item.get("title")/item.get("type")
on each results[i], but the real GraphContext.model_dump() shape wraps every item
as a ContextResult with primary_result + related_results nested inside. This
made every related note render as an empty tree node.
Fix:
- Rewrite _display_build_context to iterate context_items, build a primary-result
node from item["primary_result"], then add each item["related_results"] entry as
a child with relation_type/type/title rendered.
- Update _display_search_results to use the real SearchResponse key "current_page"
(not "page"), pass query from the CLI argument, add Score and Snippet columns
(score + matched_chunk/content truncated to 200 chars) as the issue requested.
- Update test fixtures in test_cli_tool_rich_output.py to match the real payload
shapes (nested ContextResult, current_page, score/matched_chunk fields, no
updated_at in recent-activity).
- Fix test_build_context_json_flag_overrides_tty assertion to navigate the nested
primary_result/related_results shape.
Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Drew Cain <groksrc@gmail.com>
MCP tools return str | dict depending on output_format; the Rich display helpers require the dict (or list) shape. String payloads keep main's behavior of printing through the JSON path. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Drew Cain <groksrc@gmail.com>
- `_display_read_note`: render frontmatter key/value panel when present so `--include-frontmatter` is not silently dropped in the Rich path - `_display_build_context`: render ContextResult.observations under each primary node (category + truncated content) so interactive users see the same core facts as `--json` output; update subtitle to include count - Update BUILD_CONTEXT_RESULT fixture with real ObservationSummary shape (type/category/content/permalink/file_path/created_at) - Add test_read_note_rich_include_frontmatter asserting frontmatter keys appear - Add test_build_context_rich_renders_observations asserting category/content visible Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Drew Cain <groksrc@gmail.com>
…er flag gate
Bug 1 — Rich markup injection: user-sourced titles, permalinks, snippets,
observation categories/content, and frontmatter keys/values were interpolated
directly into Rich markup strings, causing bracketed text (e.g. "[draft]",
"[fact]") to be silently swallowed or restyled. Apply markup_escape() at
every injection point in _display_search_results, _display_read_note,
_display_build_context, and _display_recent_activity. Observation labels use
markup_escape on the full "[category] content" fragment so the literal brackets
around the category are also escaped.
Bug 2 — frontmatter panel ignores flag: _display_read_note rendered the
frontmatter panel whenever result["frontmatter"] was non-empty, but the JSON
payload always carries that key regardless of --include-frontmatter. Thread
the boolean flag as a keyword argument and gate the panel on both the flag and
non-empty content.
Bug 3 — "0 result(s)" subtitle: the search API returns total=0 even when
results is non-empty. result.get("total", len(results)) never triggered its
default because the key exists; fall back to len(results) when total is falsy
but results is non-empty, keeping page-count math consistent.
Tests: add cases for bracketed title surviving search output, "[fact]" category
surviving build-context tree, read-note without --include-frontmatter asserting
no frontmatter panel, and search with total=0 asserting correct subtitle count.
Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Drew Cain <groksrc@gmail.com>
The four interactive bm tool commands (search-notes, read-note,
build-context, recent-activity) now support three output modes instead of
two:
- JSON — raw machine-readable output (--json, or automatically when piped).
- Rich — colored Panel/Table/Tree/Markdown (the default TTY experience).
- Plain — undecorated, greppable text with no ANSI colors, box-drawing, or
markup (--plain, forced even when piped).
Precedence, highest first: --json > --plain > non-TTY (JSON) > TTY (config
style). Passing both --json and --plain is a typer error with a non-zero
exit. Each TTY default is governed by the new BasicMemoryConfig field
cli_output_style ("rich"/"plain", default "rich", env
BASIC_MEMORY_CLI_OUTPUT_STYLE), mirroring the existing CLI-behavior config
conventions; its Field description documents the setting since the repo has
no general CLI-settings reference doc.
Plain renderers deliberately do NOT apply rich.markup.escape — escaping is
only correct on the Rich path and would corrupt literal brackets — so
[draft]/[fact] survive verbatim. The plain search path keeps the total=0
fallback so the corrected result count matches the Rich path. String tool
results still route to JSON to preserve ty narrowing.
Module docstring and each command's help text now document the three modes
and the config default.
Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Drew Cain <groksrc@gmail.com>
The API content field keeps the blank line left by frontmatter stripping; plain print() rendered it as a double gap under the header. JSON mode stays byte-faithful. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Drew Cain <groksrc@gmail.com>
With the flag the API returns the literal file as content, so both display paths printed the frontmatter twice (synthesized block/panel + the block inside content). Plain now prints the file verbatim; Rich keeps the panel and strips the block from the Markdown body. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Drew Cain <groksrc@gmail.com>
…de-frontmatter The file's own frontmatter carries title/permalink, so the header line duplicated it. Plain without the flag keeps the header. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Drew Cain <groksrc@gmail.com>
Drop the synthesized title/permalink header and the (no content) placeholder: plain mode is the content verbatim (note body, or the literal file with --include-frontmatter). Decoration belongs to the Rich path. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Drew Cain <groksrc@gmail.com>
Keep --include-frontmatter as a deprecated alias for back-compat (the old name shipped in 0.22.0). The MCP tool parameter include_frontmatter is unchanged. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Drew Cain <groksrc@gmail.com>
Signed-off-by: phernandez <paul@basicmachines.co>
Signed-off-by: phernandez <paul@basicmachines.co>
Signed-off-by: phernandez <paul@basicmachines.co>
|
@codex review recheck |
3d2dfee to
e72a5b2
Compare
|
Codex Review: Something went wrong. Try again later by commenting “@codex review”. ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e72a5b2b91
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Signed-off-by: phernandez <paul@basicmachines.co>
|
@codex review |
|
Codex Review: Didn't find any major issues. Nice work! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Closes #678
Summary
Adds human-readable output to
bm tool search-notes,read-note,build-context, andrecent-activitywhile preserving machine-readable behavior.--json, or stdout is piped/redirected--plain--json --plainis rejected. Interactive users can setcli_output_style: "rich" | "plain"; the default remains Rich.Renderers
search-notesrenders a result table with scores and snippets.read-noterenders Markdown and optional frontmatter in Rich mode; plain frontmatter mode writes the literal file byte-for-byte for redirection.build-contextrenders primary entities, observations, and related results as a tree.recent-activityrenders a compact activity table.The existing
--include-frontmatterCLI spelling remains as a deprecated alias for the shorter--frontmatter; the MCP parameter is unchanged.Maintainer follow-through
mainand updated tests to patch the deferred MCP import targets.--plain --frontmatterpreserve all boundary newlines with exact-output coverage.--plain --frontmatteroutput byte-faithful.Testing
uv run pytest -q tests/cli/test_cli_tool_rich_output.py— 46 passed.ty— passed.just fast-check— passed (with the repository's existing Python 3.14 asyncio deprecation diagnostics).Manual follow-up
manual/man3/read-note-3already documents--frontmatterand its deprecated alias.cli_output_style.Generated with Claude Code; maintainer hardening by Basic Machines.