Context is attention. The lighter it is to keep, the steadier the path. Context Navigator helps you practice “context engineering”: move tasks, open files, buffer selections, and notes out of your head into clear, reusable groups per project (or globally). Switch context instantly, lower cognitive load, and stay with the work.
- Project‑aware, event‑driven, lightweight
- Sidebar on the left; compact title in header-line; controls in the modeline
- One‑way GPTel integration (push on demand or automatically)
- Per‑group history (Undo/Redo)
- Asynchronous, per‑group persistence (format v3) with progress spinner
- “Live” filters: by name and by content
- Add context universally, by glob mask, or from text (path extraction)
- Optional Groups and Stats splits under the sidebar
- Multifile view to browse and safely edit selections across files
- Optional icons (all-the-icons), i18n, logging
Repository: https://github.com/11111000000/context-navigator
- Emacs 29.1+ (recommended 30.1+)
- transient 0.3.0+
- Optional: gptel — to push context to your LLM session project.el or projectile — project detection / auto‑switch all-the-icons — icons in the sidebar (run M-x all-the-icons-install-fonts) which-key, consult — nicer hints and picking
(use-package context-navigator
:load-path "~/Code/context-navigator/lisp"
:custom
(context-navigator-global-key "C-c n")
(context-navigator-autoload t)
(context-navigator-autosave t)
:config
(context-navigator-mode 1))(use-package context-navigator
:straight (context-navigator
:type git
:host github
:repo "11111000000/context-navigator")
:custom
(context-navigator-global-key "C-c n")
(context-navigator-autoload t)
(context-navigator-autosave t)
:config
(context-navigator-mode 1))Notes:
- Prefer M-x context-navigator-transient when you don’t want a global key.
- If you enable icons, install fonts once: M-x all-the-icons-install-fonts.
- Enable the mode: M-x context-navigator-mode
- Open Navigator: M-x context-navigator-start Title in the header-line shows “[project: group]” The control toolbar lives in the Navigator modeline
- Press your global key (e.g., C-c n), then for example: n — toggle Navigator; p — switch to current buffer’s project g — open Groups list; s — toggle Stats split a — Add (universal) f — Add by mask (glob) t — Add files from text (extracts paths) R — Occam filter (org): minimize enabled items for the task P — Push now → GPTel; C — Clear GPTel
- Inside the sidebar: j/k or n/p to move; RET/l to visit; v to preview SPC/t to enable/disable at point g to refresh; d to delete; q to quit s to filter by name; f to filter by content; F to clear active filter
Press ? in the sidebar for localized, context-aware help.
- Task groups (per project): “research”, “bug‑123”, “release”, etc.
- Auto‑project switching: follows meaningful buffers (files, GPTel, Dired) across projects.
- LLM sessions: push enabled items to GPTel on demand or automatically; return to saved groups anytime.
- Adding context:
- Universal Add (from Dired / region / buffer)
- Add by mask (glob)
- Add from text (extract path‑like tokens and resolve)
- Header-line: compact “[project: group]” title with a small filter segment when active. Click the title to collapse/expand quickly.
- Modeline toolbar (in Navigator buffers): compact clickable controls with icons or short labels, for example: [→] push→GPTel on/off [A] auto‑project on/off [↶]/[↷] Undo/Redo (per group) [G] open Groups split [Σ] open 5‑line Stats split [MF] open Multifile view [O]/[K] open/close all context buffers [P] Push now; [T]/[x] enable all / clear group
Note: which-key (when installed) shows friendly labels sourced from the centralized keyspec.
- Items view
- Indicators show GPTel membership (green/gray)
- Left column: indicator + icon + name; right side may show relpath
- Filters:
- s — name filter (substring AND across tokens)
- f — content filter (buffers/selections)
- F — clear filter, or click [×] in the header segment
- Groups (bottom split)
- Compact list with active group highlight
- Create/rename/duplicate/delete; toggle selection in multi‑group mode
- Designed for quick, low‑friction switching
- Optional 5‑line split below the sidebar:
- Counts (enabled vs total), size, rough token estimates
- A small types summary (e.g., by extension)
- Toggle from the modeline or via transient/menu
- One buffer with sections per item (indicator, icon, name, relpath)
- Navigate (j/k or n/p), RET to visit/edit, t to toggle, d to delete, p to push
- Selection items open in indirect buffers narrowed to region for safe editing
- “Edit all” opens indirect buffers for every selection (with a safety threshold)
- After saving, auto‑push can update GPTel when ON
- n — toggle Navigator (sidebar/buffer mode)
- p — switch to current buffer’s project
- g — open Groups
- s — toggle Stats split
- a/f/t — Add (universal) / Add by mask / Add from text
- P/C — Push now / Clear GPTel
- R — Occam filter (org)
- RET / l — activate (visit item / open group)
- v — preview (other window)
- j/k or n/p — next/previous
- SPC / t — enable/disable item at point
- d — delete (item or group)
- g — refresh
- h / u — go up (items ↔ groups)
- G — show Groups split
- a / r / e / c — add / rename / edit description / duplicate group (groups view)
- x / A — toggle push→GPTel / auto‑project
- U — unload context (switch to global)
- P / C — push now / clear GPTel
- O / o — open all context buffers (background)
- K — close all context buffers
- E — clear current group
- s — toggle Stats split
- TAB / S-TAB — jump across toggles/actions/items/groups
- q — quit, ? — help/menu
- j/k or n/p — move between sections
- RET / v — visit / preview
- t — toggle enabled; d — delete; p — push one
- f — filter enabled‑only; z — collapse/expand all; E — Edit all
- q — close
Tip: which-key automatically annotates Navigator keymaps with human‑readable labels.
- In Dired: adds marked files; directories expand recursively with a preview+confirm step
- In a file buffer with a region: adds a “selection” item (precise, safe)
- In a file buffer without a region: adds the current file
- In a non‑file buffer: adds the buffer
- Large files and TRAMP paths: careful prompts; size/remote filters apply
- Single mask per invocation; supports globstar (*) and character classes
- Works relative to project root, current directory, or as an absolute path
- Safety: TRAMP masks are disabled by default; enable only if you really need it
- Respect size limits and type checks; preview on big sets
- Extracts path‑like tokens from region/buffer; de‑quotes and strips position suffixes like :N or :A-B
- Resolves against project index (with a TTL cache) or existing abs/rel paths
- Reports ambiguities and unresolved samples; previews when large
- Applies size/remote/type filters; confirms when remote paths are present
With auto‑push ON, newly added or re‑enabled items are batched to GPTel in the background.
Navigator never imports from GPTel; it only resets + adds enabled items. Apply is batched and responsive; you can optionally defer until a GPTel window is visible. Files, buffers, and selections are supported. Indicators in the sidebar show membership in GPTel.
Highlights:
- Small background batches keep the UI responsive
- Optional deferral until GPTel is visible in the current frame
- Selections are handled safely; buffer items skip dead buffers
- Indicators show present/absent state (when enabled)
- Toggle multi‑group mode from the modeline or transient/menu
- Select multiple groups in the bottom Groups split; push applies the aggregate
- Group-local enable flags aren’t changed; MG only aggregates for GPTel
- Auto‑push gate: if selected groups exceed a safe threshold of enabled items, auto‑push is turned OFF with a one‑time notice (manual push still works)
- Where: org-mode only (R in the transient/menu)
- Source: active region if any; otherwise the whole org buffer
- Payload: the content of currently enabled items (files/buffers/selections)
- Modes:
- flex (default): try strict JSON first; otherwise accept simple identifiers (names/paths/keys)
- json-only: require strict JSON; offers an automatic retry
- Safety:
- Clear remote warnings; large payload warnings with rough budget estimate
- Apply flow:
- Preview counts (enabled vs total); confirm or cancel
- Applies by enabling only the returned items; Undo/Redo per group are available
- Format v3, one file per group: Project: <project>/.context/<group>.el Global: ~/.context/<group>.el
- state.el tracks the current group, display names, descriptions, and MG selection
- Async load with progress and spinner; safe fallback to the groups list on errors
- Can auto‑create a default group file on first use
- Roots from project.el or projectile (if available)
- “Interesting” buffers: File‑backed buffers gptel/gptel‑aibo buffers Dired (and wdired)
- Auto‑switch is throttled and sticky; child frames and internal buffers are ignored
- Manual project switch anytime: M-x context-navigator-switch-to-current-buffer-project (or “p” via transient)
- Counters and stats are cached (TTL) for responsiveness
- TRAMP mask expansion is disabled by default; enable only when needed
- GPTel apply runs in small batches; heavy operations are deferred and non‑blocking
Defaults reflect code defaults.
| Variable | Default | Description | ||
|---|---|---|---|---|
| context-navigator-global-key | “C-c n” | Global key to open the transient/menu (nil to disable) | ||
| context-navigator-view-width | 45 | Sidebar width (columns) | ||
| context-navigator-autoload | t | Auto‑load context when switching projects | ||
| context-navigator-autosave | t | Auto‑save context file on model refresh | ||
| context-navigator-context-switch-interval | 0.7 | Throttle interval (s) for auto project switch | ||
| context-navigator-context-load-batch-size | 64 | Async context load batch size | ||
| context-navigator-default-push-to-gptel | t | Start with push→GPTel ON | ||
| context-navigator-default-auto-project-switch | t | Start with auto‑project switch ON | ||
| context-navigator-dir-name | “.context” | Project subdir for context files | ||
| context-navigator-context-file-name | “context.el” | Legacy per‑project single file name (used for compatibility paths) | ||
| context-navigator-global-dir | ~/.context | Global context directory | ||
| context-navigator-create-default-group-file | t | Ensure default group file exists on first use | ||
| context-navigator-display-mode | sidebar | Display ‘sidebar’ or ‘buffer’ | ||
| context-navigator-remember-display-mode | t | Remember last display mode between sessions | ||
| context-navigator-buffer-placement | reuse-other-window | Buffer-mode placement policy | ||
| context-navigator-buffer-split-size | 0.5 | Buffer-mode split size (fraction or absolute) | ||
| context-navigator-undo-depth | 10 | History depth per group for Undo/Redo | ||
| context-navigator-gptel-apply-batch-size | 20 | Items per background tick when pushing to GPTel | ||
| context-navigator-gptel-apply-batch-interval | 0.05 | Delay (s) between GPTel apply ticks | ||
| context-navigator-gptel-require-visible-window | nil | Defer apply until a GPTel window is visible | ||
| context-navigator-gptel-visible-poll-interval | 0.5 | Poll interval (s) for GPTel visibility when deferred | ||
| context-navigator-auto-open-groups-on-error | t | Auto‑open groups list when a group fails to load | ||
| context-navigator-highlight-active-group | t | Highlight active group in groups list | ||
| context-navigator-view-controls-style | icons | Controls style: auto | icons | text |
| context-navigator-gptel-indicator-poll-interval | 0 | Polling interval (s) for GPTel indicators (0 disables; events still update) | ||
| context-navigator-view-spinner-frames | ⠋…⠏ | Frames for the loading spinner (list of strings) | ||
| context-navigator-view-spinner-interval | 0.1 | Spinner animation interval (s) | ||
| context-navigator-view-spinner-degrade-threshold | 0.25 | Degrade to static indicator if timer slips more than this (s) | ||
| context-navigator-view-modeline-enable | t | Use Navigator-specific modeline controls | ||
| context-navigator-view-modeline-face | shadow | Face used to render modeline status text | ||
| context-navigator-title-left-padding | 2 | Left padding (spaces) for the title string | ||
| context-navigator-max-file-size | 1048576 | Max file size (bytes) to include when adding recursively | ||
| context-navigator-path-add-limit | 70 | Max files to add in a single operation (names/text/mask) | ||
| context-navigator-path-add-index-cache-ttl | 30.0 | TTL (s) for project file index cache | ||
| context-navigator-path-add-case-sensitive | on | Basename match policy: auto | on | off |
| context-navigator-path-add-ignore-gitignored | t | Prefer sources that respect .gitignore | ||
| context-navigator-path-add-exclude-dotdirs | t | Exclude dot-directories in fallback recursion | ||
| context-navigator-path-add-fallback-exclude | node_modules… | Directory names excluded in fallback recursion | ||
| context-navigator-mask-include-dotfiles | nil | Include dotfiles without explicit dot in pattern component | ||
| context-navigator-mask-enable-remote | nil | Allow TRAMP mask expansion | ||
| context-navigator-mask-globstar | t | Enable * (globstar) | ||
| context-navigator-log-enabled | nil | Enable logging | ||
| context-navigator-log-level | :info | Minimal level: :error :warn :info :debug :trace | ||
| context-navigator-log-auto-open-on-error | t | Open log buffer automatically on errors | ||
| context-navigator-log-buffer-name | /Context Navigator Log/ | Log buffer name | ||
| context-navigator-log-max-lines | 5000 | Trim log to at most N lines | ||
| context-navigator-log-truncate-length | 800 | Truncate long messages (0/nil = no truncation) | ||
| context-navigator-log-file-enable | nil | Also append each line to a persistent file | ||
| context-navigator-log-file | nil | Path to persistent log file | ||
| context-navigator-language | auto | UI language; ‘auto’ detects from locale | ||
| context-navigator-multigroup-autopush-threshold | 100 | Max enabled items across selected groups before auto‑push is gated OFF |
(use-package context-navigator
:custom
(context-navigator-global-key "C-c n")
(context-navigator-autoload t)
(context-navigator-autosave t)
:config
(context-navigator-mode 1))(use-package context-navigator
;; :straight (context-navigator :type git :host github :repo "11111000000/context-navigator")
:custom
(context-navigator-global-key "C-c n")
(context-navigator-autoload t)
(context-navigator-autosave t)
(context-navigator-view-width 36)
(context-navigator-view-controls-style 'icons)
(context-navigator-gptel-indicator-poll-interval 0)
;; (context-navigator-gptel-require-visible-window t)
:config
(context-navigator-mode 1))- Enable via the transient menu or by setting context-navigator-log-enabled
- Levels: :error :warn :info :debug :trace
- Log buffer: “*Context Navigator Log/”
- Optional per‑line file logging
- Keys/menu don’t work? Ensure context-navigator-mode is enabled and a global key is set, or use M-x context-navigator-transient
- Navigator doesn’t open? Try M-x context-navigator-start or M-x context-navigator-open
- Icons missing? Install all-the-icons and run M-x all-the-icons-install-fonts, then restart Emacs
- GPTel not installed? Navigator still works; push operations no‑op with a friendly message
- Group load failed? The groups list will open automatically; delete or fix the group file
- Where are the controls? Title lives in the header-line; the control toolbar lives in the Navigator modeline
Issues and pull requests are welcome. Please:
- Provide clear repro steps and Emacs/version info
- Keep patches focused and side‑effect‑local
- Update docstrings and this README when behavior or user‑facing options change
MIT — see LICENSE.
Let attention rest where it works best: in a clear, gentle context.