54 lines
4.2 KiB
Org Mode
54 lines
4.2 KiB
Org Mode
#+TITLE: Flight Plan: Emacs Client UX Overhaul
|
|
#+DATE: 2026-04-07
|
|
#+FILETAGS: :plan:ux:emacs:interface:psf:
|
|
|
|
* Phase A: Demand (Verify State)
|
|
- Current state: The `opencortex` Emacs client uses a single buffer for both input and output, or a clunky side-window for reasoning. The interface is rudimentary and lacks modern chat application affordances.
|
|
- User feedback indicates that responses and reasoning streams are sometimes missing or hard to read.
|
|
- Objective: Design a comprehensive, intuitive, and modern UX for the Emacs client.
|
|
|
|
* Key Requirements
|
|
1. **Dedicated Input Area**: A text box (minibuffer or dedicated window at the bottom) for user input, distinct from the chat history.
|
|
2. **Main History Buffer**: A primary buffer displaying the conversation history, agent outputs, and system logs.
|
|
3. **Syntax Highlighting**: Enhanced colorization depending on the syntax (e.g., Lisp code, shell commands, Org-mode elements).
|
|
4. **Diff Visualization**: Clear, visual representation of proposed code changes or diffs, akin to modern CLI tools (e.g., `gemini-cli` or `magit`).
|
|
5. **Overall Appeal**: A comprehensive design that feels modern and intuitive for users accustomed to tools like Claude Code or ChatGPT interfaces.
|
|
|
|
* Phase B: Blueprint (Architectural Design)
|
|
|
|
** 1. Window Layout Management
|
|
We will abandon the single-buffer approach and adopt a dual-window layout for the chat interface:
|
|
- **`*opencortex-chat*` (Top, 80% height)**: A read-only `special-mode` or customized `org-mode` buffer dedicated to displaying the conversation history, agent responses, and tool execution logs.
|
|
- **`*opencortex-input*` (Bottom, 20% height)**: A dedicated `markdown-mode` or `org-mode` buffer for composing messages. Pressing `C-c C-c` here will send the contents to the daemon, clear the input buffer, and append the user's message to the main chat buffer.
|
|
|
|
** 2. The Output Formatting Engine (Syntax & Color)
|
|
To make the main chat buffer appealing, we need a robust formatting engine within `opencortex.el`:
|
|
- **Structured Insertion**: When the daemon sends an `:insert-at-end` command, the Emacs client will parse the payload.
|
|
- **Font-Lock Extensions**: We will define custom `font-lock` rules for the `*opencortex-chat*` buffer to highlight specific elements:
|
|
- *User Messages*: Distinct background or font face.
|
|
- *Agent Responses*: Standard Org-mode styling.
|
|
- *Tool Executions (Reasoning)*: Dimmed or italicized text for "Thinking..." or "Executing shell command: `ls`".
|
|
- *Code Blocks*: Native syntax highlighting for `#+begin_src` blocks using `org-src-fontify-natively`.
|
|
|
|
** 3. Diff Visualization Interface
|
|
To handle code modifications safely and beautifully:
|
|
- When the agent proposes a file change, it will send a structured `:diff` or `:patch` payload rather than raw text.
|
|
- The Emacs client will intercept this payload and present it using `diff-mode` or a custom overlay within the chat buffer, providing visual red/green highlights for removals and additions.
|
|
- *Interactive Acceptance*: The user can press a key (e.g., `C-c C-y`) on the diff to accept and apply the patch, realizing the "Active Approval Mode" pattern in Emacs.
|
|
|
|
** 4. The Reasoning Stream Integration
|
|
- Instead of a separate right-side window that clutters the workspace, the reasoning stream (Probabilistic Engine thoughts, tool calls) will be integrated directly into the main `*opencortex-chat*` buffer.
|
|
- It will be presented as a collapsible Org-mode drawer (e.g., `:REASONING:`) or formatted as dimmed, transient text that provides transparency without overwhelming the primary conversation.
|
|
|
|
* Phase C: Tester (Verification Strategy)
|
|
- Launch `M-x opencortex`.
|
|
- Verify the dual-window layout appears correctly.
|
|
- Type a message in the input buffer, send it, and verify it clears and appears in the main buffer.
|
|
- Trigger a tool call and verify the reasoning stream is formatted clearly (and distinct from the final answer).
|
|
- Trigger a file modification and verify the diff visualization is presented elegantly.
|
|
|
|
* Migration Strategy
|
|
This overhaul requires significant changes to:
|
|
1. `projects/opencortex/src/opencortex.el` (The Emacs client).
|
|
2. `notes/org-skill-chat.org` (To update the expected payload formats if we move beyond simple `:insert-at-end`).
|