@bojackduy/opencode-telescope 0.1.13 → 0.1.14

package/README.md

@@ -42,9 +42,47 @@ Add the plugin to your `tui.json`:
 | ---------------- | ----------------------------------------------- |
 | Open search      | `<leader>f` or `/telescope`                     |
 | Type to filter   | Fuzzy match against conversation text           |
-| Navigate results | `↑` / `↓` or `Ctrl+j` / `Ctrl+k`                |
+| Navigate results | `↑` / `↓` or `j` / `k`                          |
 | Preview          | Select a result to see the conversation preview |
 | Open             | Press `Enter` to jump to the selected session   |
+| Owner filter     | Press `o` to cycle `all` / `you` / `assistant`  |
+
+## Configuration
+
+Telescope reads optional plugin-specific config from:
+
+```txt
+~/.config/opencode/opencode-telescope/config.json
+```
+
+If `$XDG_CONFIG_HOME` is set, the path is:
+
+```txt
+$XDG_CONFIG_HOME/opencode/opencode-telescope/config.json
+```
+
+Missing config, invalid JSON, and invalid individual fields are ignored. Defaults are kept for anything not configured.
+
+Example:
+
+```jsonc
+{
+  "openKey": "<leader>f",
+  "keys": {
+    "moveDown": ["down", "j"],
+    "moveUp": ["up", "k"],
+    "scrollPreviewDown": ["d"],
+    "scrollPreviewUp": ["u"],
+    "open": ["enter", "return"],
+    "close": ["q", "escape"],
+    "insertMode": ["/"],
+    "normalMode": ["ctrl+q"],
+    "toggleOwner": ["o"]
+  }
+}
+```
+
+Key strings support simple names like `j`, `k`, `down`, `up`, `enter`, `return`, and `escape`, plus modifier strings like `ctrl+q`.
 
 ## How it works
 

package/components/result-list.tsx

@@ -54,9 +54,9 @@ export const ResultRow = (props: {
   </box>
 )
 
-export const EmptyState = (props: { query: string; theme: TuiThemeCurrent }) => (
+export const EmptyState = (props: { query: string; owner: string; theme: TuiThemeCurrent }) => (
   <box paddingLeft={1} paddingTop={1}>
-    <text fg={props.theme.textMuted}>{props.query.trim() ? "No matching user/assistant conversation text." : "No recent conversation text found."}</text>
+    <text fg={props.theme.textMuted}>{props.query.trim() ? `No matching ${props.owner} conversation text.` : `No recent ${props.owner} conversation text found.`}</text>
   </box>
 )
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@bojackduy/opencode-telescope",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Fuzzy search across all OpenCode conversations — grep session and chat history, find code snippets, and jump to any chat instantly",
   "type": "module",
   "license": "MIT",

package/search.ts

@@ -27,6 +27,8 @@ export type SearchResult = {
   text: string
 }
 
+export type SearchRole = "user" | "assistant"
+
 export type ConversationPreviewPart = {
   id: string
   messageID: string
@@ -64,7 +66,7 @@ type Row = {
   session_id: string
   session_title: string | null
   directory: string
-  role: "user" | "assistant"
+  role: SearchRole
   time_created: number
   text: string
 }
@@ -73,7 +75,7 @@ type ConversationRow = {
   id: string
   message_id: string
   session_id: string
-  role: "user" | "assistant"
+  role: SearchRole
   type: "text" | "reasoning" | "tool"
   time_created: number
   data: string
@@ -127,18 +129,18 @@ export function resolveDatabasePath() {
   }
 }
 
-export function searchSessionMessages(query: string, options?: { limit?: number; offset?: number; dbPath?: string; directory?: string }) {
+export function searchSessionMessages(query: string, options?: { limit?: number; offset?: number; dbPath?: string; directory?: string; role?: SearchRole }) {
   const term = query.trim()
   if (!term) return []
   if (options?.dbPath === ":memory:") return []
   const dbPath = options?.dbPath ?? resolveDatabasePath()
   const db = getDb(dbPath)
-  return searchRows(db, dbPath, term, options?.limit ?? 80, options?.directory, options?.offset)
+  return searchRows(db, dbPath, term, options?.limit ?? 80, options?.directory, options?.offset, options?.role)
 }
 
-export function recentSessionMessages(options?: { limit?: number; offset?: number; dbPath?: string; directory?: string }) {
+export function recentSessionMessages(options?: { limit?: number; offset?: number; dbPath?: string; directory?: string; role?: SearchRole }) {
   const db = getDb(options?.dbPath)
-  return visibleTextRows(db, options?.limit ?? 40, undefined, options?.directory, options?.offset).flatMap(
+  return visibleTextRows(db, options?.limit ?? 40, undefined, options?.directory, options?.offset, options?.role).flatMap(
     (row) => rowToSearchResult(row, "") ?? [],
   )
 }
@@ -535,10 +537,10 @@ function parseToolState(value: unknown): ToolState | undefined {
   }
 }
 
-function searchRows(db: Database, dbPath: string, query: string, limit: number, directory?: string, offset?: number) {
+function searchRows(db: Database, dbPath: string, query: string, limit: number, directory?: string, offset?: number, role?: SearchRole) {
   if (!tableExists(db, "part") || !tableExists(db, "message")) return []
   debug.time("query:sql")
-  const rows = indexedTextRows(db, dbPath, limit, query, directory, offset) ?? visibleTextRows(db, limit, query, directory, offset)
+  const rows = indexedTextRows(db, dbPath, limit, query, directory, offset, role) ?? visibleTextRows(db, limit, query, directory, offset, role)
   debug.timeEnd("query:sql")
   debug.time("query:map")
   const results = rows.flatMap((row) => rowToSearchResult(row, query) ?? [])
@@ -546,13 +548,17 @@ function searchRows(db: Database, dbPath: string, query: string, limit: number,
   return results
 }
 
-function indexedTextRows(db: Database, dbPath: string, limit: number, query: string, directory?: string, offset?: number) {
+function indexedTextRows(db: Database, dbPath: string, limit: number, query: string, directory?: string, offset?: number, role?: SearchRole) {
   const match = ftsQuery(query)
   if (!match) return []
   try {
     const index = ensureSearchIndex(db, dbPath)
     const conditions = ["document_fts MATCH ?"]
     const params: (string | number)[] = [match]
+    if (role) {
+      conditions.push("role = ?")
+      params.push(role)
+    }
     if (directory) {
       conditions.push("directory = ?")
       params.push(directory)
@@ -577,14 +583,16 @@ function indexedTextRows(db: Database, dbPath: string, limit: number, query: str
   }
 }
 
-function visibleTextRows(db: Database, limit: number, query?: string, directory?: string, offset?: number) {
+function visibleTextRows(db: Database, limit: number, query?: string, directory?: string, offset?: number, role?: SearchRole) {
   const offsetClause = offset ? "OFFSET ?" : ""
   const conditions: string[] = [
     "json_extract(p.data, '$.type') = 'text'",
-    "json_extract(m.data, '$.role') IN ('user', 'assistant')",
+    role ? "json_extract(m.data, '$.role') = ?" : "json_extract(m.data, '$.role') IN ('user', 'assistant')",
   ]
   const params: (string | number)[] = []
 
+  if (role) params.push(role)
+
   if (directory) {
     conditions.push("s.directory = ?")
     params.push(directory)

package/telescope.tsx

@@ -2,7 +2,7 @@
 import type { TuiPluginApi } from "@opencode-ai/plugin/tui"
 import type { InputRenderable, ParsedKey, ScrollBoxRenderable } from "@opentui/core"
 import { useKeyboard, useTerminalDimensions } from "@opentui/solid"
-import { For, Show, createEffect, createMemo, createSignal, onCleanup } from "solid-js"
+import { For, Show, batch as solidBatch, createEffect, createMemo, createSignal, onCleanup } from "solid-js"
 import { ConversationPreview, PreviewHeader } from "./components/preview.tsx"
 import { EmptyState, ResultRow, SkeletonRow } from "./components/result-list.tsx"
 import {
@@ -14,43 +14,71 @@ import {
   searchSessionMessages,
   type ConversationPreviewPart,
   type SearchResult,
+  type SearchRole,
 } from "./search.ts"
 import { debug } from "./ui/debug.ts"
 import { syntaxStyle } from "./ui/format.ts"
-import { isKey, prevent } from "./ui/keyboard.ts"
+import type { TelescopeConfig } from "./ui/config.ts"
+import { inputSafeKeys, keyListLabel, matchesKey, prevent } from "./ui/keyboard.ts"
 import { jumpToRenderedTarget, messageTargetID, previewScrollAmount, scrollPreviewToTarget } from "./ui/render-target.ts"
 
-export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) => {
+export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; onClose: () => void }) => {
+  type OwnerFilter = "all" | SearchRole
   const dimensions = useTerminalDimensions()
   const [query, setQuery] = createSignal("")
+  const [ownerFilter, setOwnerFilter] = createSignal<OwnerFilter>("all")
   const [results, setResults] = createSignal<SearchResult[]>([])
   const [previewParts, setPreviewParts] = createSignal<ConversationPreviewPart[]>([])
   const [selected, setSelected] = createSignal(0)
+  const [resultBaseOffset, setResultBaseOffset] = createSignal(0)
+  const [nextResultOffset, setNextResultOffset] = createSignal(0)
   const [busy, setBusy] = createSignal(false)
   const [error, setError] = createSignal("")
   const [mode, setMode] = createSignal<"normal" | "insert">("normal")
   const [loading, setLoading] = createSignal(true)
   const [hasMore, setHasMore] = createSignal(true)
   const [loadingMore, setLoadingMore] = createSignal(false)
+  const [loadingPreviousResults, setLoadingPreviousResults] = createSignal(false)
   const [prefetchingResults, setPrefetchingResults] = createSignal(false)
   const [resultPageInfo, setResultPageInfo] = createSignal({ loadedUntil: 0, hasMore: true, pageSize: 0, lastOffset: 0, lastAdded: 0 })
   const [hasMorePreviewBefore, setHasMorePreviewBefore] = createSignal(false)
   const [hasMorePreviewAfter, setHasMorePreviewAfter] = createSignal(false)
   const [loadingPreviewMore, setLoadingPreviewMore] = createSignal(false)
+  const [prefetchingPreviewBefore, setPrefetchingPreviewBefore] = createSignal(false)
+  const [prefetchingPreviewAfter, setPrefetchingPreviewAfter] = createSignal(false)
   const MIN_SEARCH_BATCH_SIZE = 25
   const MIN_RECENT_BATCH_SIZE = 15
   const RESULT_OVERSCAN_MULTIPLIER = 2
-  const RESULT_PREFETCH_VIEWPORTS = 3
+  const RESULT_BATCH_VIEWPORTS = 4
+  const RESULT_PREFETCH_VIEWPORTS = 10
+  const RESULT_CACHE_BEHIND_VIEWPORTS = 6
   const INITIAL_PREVIEW_BEFORE = 20
   const INITIAL_PREVIEW_AFTER = 30
   const PREVIEW_PAGE_SIZE = 20
+  const PREVIEW_PREFETCH_VIEWPORTS = 0.5
   let input: InputRenderable | undefined
   let resultScroll: ScrollBoxRenderable | undefined
   let previewScroll: ScrollBoxRenderable | undefined
 
   const theme = createMemo(() => props.api.theme.current)
   const syntax = createMemo(() => syntaxStyle(theme()))
-  const selectedResult = createMemo(() => results()[selected()])
+  const ownerRole = createMemo(() => ownerFilter() === "all" ? undefined : ownerFilter() as SearchRole)
+  const ownerLabel = createMemo(() => ownerFilter() === "user" ? "you" : ownerFilter())
+  const inputKeys = createMemo(() => ({
+    moveDown: inputSafeKeys(props.config.keys.moveDown),
+    moveUp: inputSafeKeys(props.config.keys.moveUp),
+    open: inputSafeKeys(props.config.keys.open),
+    normalMode: inputSafeKeys(props.config.keys.normalMode),
+  }))
+  const normalHelpItems = createMemo(() => [
+    `${keyListLabel(props.config.keys.moveUp)}/${keyListLabel(props.config.keys.moveDown)} move`,
+    `${keyListLabel(props.config.keys.scrollPreviewDown)}/${keyListLabel(props.config.keys.scrollPreviewUp)} scroll`,
+    `${keyListLabel(props.config.keys.toggleOwner)} owner`,
+    `${keyListLabel(props.config.keys.insertMode)} search`,
+    `${keyListLabel(props.config.keys.open)} open`,
+    `${keyListLabel(props.config.keys.close)} close`,
+  ])
+  const selectedResult = createMemo(() => results()[selected() - resultBaseOffset()])
   const popupWidth = createMemo(() => Math.max(72, Math.min(dimensions().width - 2, Math.floor(dimensions().width * 0.92))))
   const leftWidth = createMemo(() => Math.max(36, Math.min(64, Math.floor(popupWidth() * 0.36))))
   const height = createMemo(() => Math.max(18, dimensions().height - 8))
@@ -58,9 +86,28 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
   const dbPath = createMemo(() => resolveDatabasePath())
   const directory = props.api.state.path.directory
   let advanceSelectionAfterLoad = false
+  let advanceSelectionBeforeLoad = false
   let resultPrefetchTimer: ReturnType<typeof setTimeout> | undefined
+  let resultPreviousTimer: ReturnType<typeof setTimeout> | undefined
+  let previewBeforeTimer: ReturnType<typeof setTimeout> | undefined
+  let previewAfterTimer: ReturnType<typeof setTimeout> | undefined
+  let pendingPreviewBefore: { previousContentHeight: number; preserveScroll: boolean; visibleLoad: boolean } | undefined
+  let pendingPreviewAfterVisible = false
+  const cancelPreviewPrefetch = () => {
+    if (previewBeforeTimer) clearTimeout(previewBeforeTimer)
+    if (previewAfterTimer) clearTimeout(previewAfterTimer)
+    previewBeforeTimer = undefined
+    previewAfterTimer = undefined
+    pendingPreviewBefore = undefined
+    pendingPreviewAfterVisible = false
+    setPrefetchingPreviewBefore(false)
+    setPrefetchingPreviewAfter(false)
+    setLoadingPreviewMore(false)
+  }
   onCleanup(() => {
     if (resultPrefetchTimer) clearTimeout(resultPrefetchTimer)
+    if (resultPreviousTimer) clearTimeout(resultPreviousTimer)
+    cancelPreviewPrefetch()
   })
 
   const resultRowHeight = createMemo(() => leftWidth() >= 48 ? 3 : 4)
@@ -68,27 +115,47 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
     const viewportHeight = resultScroll?.height || Math.max(8, height() - 7)
     return Math.max(5, Math.floor(viewportHeight / resultRowHeight()))
   }
-  const searchBatchSize = () => Math.max(MIN_SEARCH_BATCH_SIZE, visibleResultRows() * 2)
-  const recentBatchSize = () => Math.max(MIN_RECENT_BATCH_SIZE, visibleResultRows() * 2)
-  const resultPrefetchThreshold = () => Math.max(visibleResultRows() * RESULT_PREFETCH_VIEWPORTS, searchBatchSize())
+  const searchBatchSize = () => Math.max(MIN_SEARCH_BATCH_SIZE, visibleResultRows() * RESULT_BATCH_VIEWPORTS)
+  const recentBatchSize = () => Math.max(MIN_RECENT_BATCH_SIZE, visibleResultRows() * RESULT_BATCH_VIEWPORTS)
+  const resultPrefetchThreshold = () => visibleResultRows() * RESULT_PREFETCH_VIEWPORTS
+  const resultPrefetchState = () => {
+    const cachedEnd = resultBaseOffset() + results().length
+    const rowsAhead = Math.max(0, cachedEnd - selected() - 1)
+    const threshold = resultPrefetchThreshold()
+    return { cachedEnd, rowsAhead, threshold, shouldPrefetch: rowsAhead <= threshold }
+  }
+  const trimResultCache = (items: SearchResult[], anchorIndex: number) => {
+    const base = resultBaseOffset()
+    const keepBehind = visibleResultRows() * RESULT_CACHE_BEHIND_VIEWPORTS
+    const minOffset = Math.max(0, anchorIndex - keepBehind)
+    const drop = Math.min(Math.max(0, minOffset - base), Math.max(0, items.length - 1))
+    if (drop === 0) return { base, items }
+
+    const nextBase = base + drop
+    debug.log("results:evict", { fromBase: base, toBase: nextBase, dropped: drop, kept: items.length - drop, anchorIndex })
+    return { base: nextBase, items: items.slice(drop) }
+  }
   const resultRenderWindow = createMemo(() => {
-    const total = results().length
+    const base = resultBaseOffset()
+    const cached = results()
     const visible = visibleResultRows()
     const overscan = visible * RESULT_OVERSCAN_MULTIPLIER
     const index = selected()
-    const start = Math.max(0, index - overscan)
-    const end = Math.min(total, index + visible + overscan)
-    return { start, end, items: results().slice(start, end) }
+    const cachedStart = Math.max(0, index - overscan - base)
+    const cachedEnd = Math.min(cached.length, index + visible + overscan - base)
+    return { start: base + cachedStart, end: base + cachedEnd, items: cached.slice(cachedStart, cachedEnd) }
   })
 
   let lastResultRenderWindow = ""
   createEffect(() => {
     const window = resultRenderWindow()
-    const key = `${window.start}:${window.end}:${results().length}`
+    const key = `${window.start}:${window.end}:${resultBaseOffset()}:${nextResultOffset()}:${results().length}`
     if (key === lastResultRenderWindow) return
     lastResultRenderWindow = key
     debug.log("results:render-window", {
       selected: selected(),
+      baseOffset: resultBaseOffset(),
+      nextOffset: nextResultOffset(),
       totalLoaded: results().length,
       start: window.start,
       end: window.end,
@@ -101,8 +168,18 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
 
   createEffect(() => {
     const q = query().trim()
+    const role = ownerRole()
     setError("")
     setHasMore(true)
+    if (resultPrefetchTimer) clearTimeout(resultPrefetchTimer)
+    if (resultPreviousTimer) clearTimeout(resultPreviousTimer)
+    resultPrefetchTimer = undefined
+    resultPreviousTimer = undefined
+    advanceSelectionAfterLoad = false
+    advanceSelectionBeforeLoad = false
+    setLoadingMore(false)
+    setLoadingPreviousResults(false)
+    setPrefetchingResults(false)
     const db = dbPath()
     const dir = directory
 
@@ -112,14 +189,22 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
       const timer = setTimeout(() => {
         debug.time("query:recent")
         try {
-          const batch = recentSessionMessages({ limit, offset: 0, dbPath: db, directory: dir })
-          setResults(batch)
-          setHasMore(batch.length >= limit)
-          setResultPageInfo({ loadedUntil: batch.length, hasMore: batch.length >= limit, pageSize: limit, lastOffset: 0, lastAdded: batch.length })
-          setSelected(0)
+          const batch = recentSessionMessages({ limit, offset: 0, dbPath: db, directory: dir, role })
+          solidBatch(() => {
+            setResults(batch)
+            setResultBaseOffset(0)
+            setNextResultOffset(batch.length)
+            setHasMore(batch.length >= limit)
+            setResultPageInfo({ loadedUntil: batch.length, hasMore: batch.length >= limit, pageSize: limit, lastOffset: 0, lastAdded: batch.length })
+            setSelected(0)
+          })
         } catch (err) {
-          setResults([])
-          setResultPageInfo({ loadedUntil: 0, hasMore: false, pageSize: limit, lastOffset: 0, lastAdded: 0 })
+          solidBatch(() => {
+            setResults([])
+            setResultBaseOffset(0)
+            setNextResultOffset(0)
+            setResultPageInfo({ loadedUntil: 0, hasMore: false, pageSize: limit, lastOffset: 0, lastAdded: 0 })
+          })
           setError(err instanceof Error ? err.message : String(err))
         }
         debug.timeEnd("query:recent")
@@ -135,14 +220,22 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
     const timer = setTimeout(() => {
       debug.time("query:search")
       try {
-        const batch = searchSessionMessages(q, { limit, offset: 0, dbPath: db, directory: dir })
-        setResults(batch)
-        setHasMore(batch.length >= limit)
-        setResultPageInfo({ loadedUntil: batch.length, hasMore: batch.length >= limit, pageSize: limit, lastOffset: 0, lastAdded: batch.length })
-        setSelected(0)
+        const batch = searchSessionMessages(q, { limit, offset: 0, dbPath: db, directory: dir, role })
+        solidBatch(() => {
+          setResults(batch)
+          setResultBaseOffset(0)
+          setNextResultOffset(batch.length)
+          setHasMore(batch.length >= limit)
+          setResultPageInfo({ loadedUntil: batch.length, hasMore: batch.length >= limit, pageSize: limit, lastOffset: 0, lastAdded: batch.length })
+          setSelected(0)
+        })
       } catch (err) {
-        setResults([])
-        setResultPageInfo({ loadedUntil: 0, hasMore: false, pageSize: limit, lastOffset: 0, lastAdded: 0 })
+        solidBatch(() => {
+          setResults([])
+          setResultBaseOffset(0)
+          setNextResultOffset(0)
+          setResultPageInfo({ loadedUntil: 0, hasMore: false, pageSize: limit, lastOffset: 0, lastAdded: 0 })
+        })
         setError(err instanceof Error ? err.message : String(err))
       } finally {
         debug.timeEnd("query:search")
@@ -159,10 +252,11 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
       advanceSelectionAfterLoad = false
       return
     }
-    if (loadingMore() || prefetchingResults() || busy() || loading()) return
+    if (loadingMore() || loadingPreviousResults() || prefetchingResults() || busy() || loading()) return
 
-    const total = results().length
+    const offset = nextResultOffset()
     const q = query().trim()
+    const role = ownerRole()
     const db = dbPath()
     const dir = directory
     const limit = q ? searchBatchSize() : recentBatchSize()
@@ -171,18 +265,35 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
     debug.time("query:load-more")
     try {
       const batch = q
-        ? searchSessionMessages(q, { limit, offset: total, dbPath: db, directory: dir })
-        : recentSessionMessages({ limit, offset: total, dbPath: db, directory: dir })
+        ? searchSessionMessages(q, { limit, offset, dbPath: db, directory: dir, role })
+        : recentSessionMessages({ limit, offset, dbPath: db, directory: dir, role })
       const nextHasMore = batch.length >= limit
-      const nextLoadedUntil = total + batch.length
-      debug.log("results:prefetch", { offset: total, limit, added: batch.length, totalLoaded: nextLoadedUntil, hasMore: nextHasMore, advance })
-      setResults((prev) => [...prev, ...batch])
-      setResultPageInfo({ loadedUntil: nextLoadedUntil, hasMore: nextHasMore, pageSize: limit, lastOffset: total, lastAdded: batch.length })
-      if (!nextHasMore) setHasMore(false)
-      if (advanceSelectionAfterLoad) {
-        debug.log("results:advance-after-load", { from: selected(), total, added: batch.length })
+      const nextLoadedUntil = offset + batch.length
+      const previousSelected = selected()
+      const nextSelected = advanceSelectionAfterLoad && batch.length > 0 ? offset : selected()
+      const nextCache = trimResultCache([...results(), ...batch], nextSelected)
+      debug.log("results:prefetch", {
+        offset,
+        limit,
+        added: batch.length,
+        baseOffset: nextCache.base,
+        cached: nextCache.items.length,
+        totalLoaded: nextLoadedUntil,
+        hasMore: nextHasMore,
+        advance,
+      })
+      const shouldAdvance = advanceSelectionAfterLoad
+      solidBatch(() => {
+        setResultBaseOffset(nextCache.base)
+        setNextResultOffset(nextLoadedUntil)
+        setResults(nextCache.items)
+        setResultPageInfo({ loadedUntil: nextLoadedUntil, hasMore: nextHasMore, pageSize: limit, lastOffset: offset, lastAdded: batch.length })
+        if (!nextHasMore) setHasMore(false)
+        if (shouldAdvance && batch.length > 0) setSelected(offset)
+      })
+      if (shouldAdvance) {
+        debug.log("results:advance-after-load", { from: previousSelected, offset, added: batch.length })
         advanceSelectionAfterLoad = false
-        if (batch.length > 0) setSelected(total)
       }
     } catch (err) {
       debug.log("results:load-more:error", err instanceof Error ? err.message : String(err))
@@ -193,9 +304,51 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
     }
   }
 
+  const loadPreviousResults = (advance = false) => {
+    if (advance) advanceSelectionBeforeLoad = true
+    const base = resultBaseOffset()
+    if (base <= 0) {
+      advanceSelectionBeforeLoad = false
+      return
+    }
+    if (loadingMore() || loadingPreviousResults() || prefetchingResults() || busy() || loading()) return
+
+    const q = query().trim()
+    const role = ownerRole()
+    const db = dbPath()
+    const dir = directory
+    const pageSize = q ? searchBatchSize() : recentBatchSize()
+    const offset = Math.max(0, base - pageSize)
+    const limit = base - offset
+
+    setLoadingPreviousResults(true)
+    debug.time("query:load-before")
+    try {
+      const batch = q
+        ? searchSessionMessages(q, { limit, offset, dbPath: db, directory: dir, role })
+        : recentSessionMessages({ limit, offset, dbPath: db, directory: dir, role })
+      const nextSelected = advanceSelectionBeforeLoad && batch.length > 0 ? base - 1 : selected()
+      debug.log("results:load-before", { offset, limit, added: batch.length, fromBase: base, toBase: offset, cached: results().length + batch.length, advance })
+      const shouldAdvance = advanceSelectionBeforeLoad
+      solidBatch(() => {
+        setResultBaseOffset(offset)
+        setResults([...batch, ...results()])
+        setResultPageInfo({ loadedUntil: nextResultOffset(), hasMore: hasMore(), pageSize, lastOffset: offset, lastAdded: batch.length })
+        if (shouldAdvance && batch.length > 0) setSelected(nextSelected)
+      })
+      if (shouldAdvance) advanceSelectionBeforeLoad = false
+    } catch (err) {
+      debug.log("results:load-before:error", err instanceof Error ? err.message : String(err))
+      advanceSelectionBeforeLoad = false
+    } finally {
+      debug.timeEnd("query:load-before")
+      setLoadingPreviousResults(false)
+    }
+  }
+
   const scheduleResultPrefetch = (advance = false) => {
     if (advance) advanceSelectionAfterLoad = true
-    if (resultPrefetchTimer || loadingMore() || prefetchingResults()) return
+    if (resultPrefetchTimer || loadingMore() || loadingPreviousResults() || prefetchingResults()) return
     debug.log("results:prefetch-scheduled", { advance, pendingAdvance: advanceSelectionAfterLoad, pageInfo: resultPageInfo() })
     resultPrefetchTimer = setTimeout(() => {
       resultPrefetchTimer = undefined
@@ -203,15 +356,33 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
     }, 1)
   }
 
+  const schedulePreviousResultsLoad = (advance = false) => {
+    if (advance) advanceSelectionBeforeLoad = true
+    if (resultPreviousTimer || loadingMore() || loadingPreviousResults() || prefetchingResults()) return
+    debug.log("results:load-before-scheduled", { advance, pendingAdvance: advanceSelectionBeforeLoad, baseOffset: resultBaseOffset(), pageInfo: resultPageInfo() })
+    resultPreviousTimer = setTimeout(() => {
+      resultPreviousTimer = undefined
+      loadPreviousResults(advanceSelectionBeforeLoad)
+    }, 1)
+  }
+
+  let lastResultPrefetchDecision = ""
+
   const move = (delta: number) => {
     if (results().length === 0) return
     setSelected((index) => {
+      const base = resultBaseOffset()
+      const cachedEnd = base + results().length
       const next = index + delta
       let finalIndex = next
-      if (next < 0) finalIndex = results().length - 1
-      else if (next >= results().length) {
+      if (next < 0) finalIndex = cachedEnd - 1
+      else if (next < base) {
+        schedulePreviousResultsLoad(true)
+        finalIndex = base
+      }
+      else if (next >= cachedEnd) {
         if (hasMore()) scheduleResultPrefetch(true)
-        finalIndex = results().length - 1
+        finalIndex = cachedEnd - 1
       }
        
       if (finalIndex !== index) debug.time("nav:total")
@@ -235,11 +406,26 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
   })
 
   createEffect(() => {
-    const index = selected()
-    const total = results().length
-    const threshold = resultPrefetchThreshold()
-    if (index < total - threshold) return
-    if (!hasMore() || loadingMore() || prefetchingResults() || busy() || loading()) return
+    const state = resultPrefetchState()
+    const blockedBy = !hasMore()
+      ? "no-more"
+      : loadingMore()
+        ? "loading-more"
+        : loadingPreviousResults()
+          ? "loading-before"
+          : prefetchingResults()
+            ? "prefetching"
+            : busy()
+              ? "busy"
+              : loading()
+                ? "loading"
+                : ""
+    const decisionKey = `${selected()}:${state.cachedEnd}:${state.rowsAhead}:${state.threshold}:${blockedBy}:${state.shouldPrefetch}`
+    if (decisionKey !== lastResultPrefetchDecision) {
+      lastResultPrefetchDecision = decisionKey
+      debug.log("results:prefetch-decision", { selected: selected(), ...state, blockedBy: blockedBy || undefined })
+    }
+    if (!state.shouldPrefetch || blockedBy) return
 
     const timer = setTimeout(() => scheduleResultPrefetch(false), 100)
     onCleanup(() => clearTimeout(timer))
@@ -251,11 +437,11 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
     return lastChild ? lastChild.y + lastChild.height : 0
   }
 
-  const loadPreviewBefore = (previousContentHeight = previewContentHeight(), preserveScroll = true) => {
+  const loadPreviewBefore = (previousContentHeight = previewContentHeight(), preserveScroll = true, visibleLoad = false) => {
     const item = selectedResult()
     const first = previewParts()[0]
-    if (!item || !first || loadingPreviewMore()) return
-    setLoadingPreviewMore(true)
+    if (!item || !first || loadingPreviewMore() || prefetchingPreviewBefore()) return
+    visibleLoad ? setLoadingPreviewMore(true) : setPrefetchingPreviewBefore(true)
     debug.time("preview:load-before")
     try {
       const page = loadConversationBefore(item, { id: first.id, timeCreated: first.timeCreated }, { limit: PREVIEW_PAGE_SIZE, dbPath: dbPath() })
@@ -264,6 +450,7 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
         added: page.parts.length,
         hasMoreBefore: page.hasMoreBefore,
         preserveScroll,
+        visibleLoad,
         first: page.parts[0]?.id,
         last: page.parts.at(-1)?.id,
       })
@@ -281,15 +468,15 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
       debug.log("preview:load-before:error", err instanceof Error ? err.message : String(err))
     } finally {
       debug.timeEnd("preview:load-before")
-      setLoadingPreviewMore(false)
+      visibleLoad ? setLoadingPreviewMore(false) : setPrefetchingPreviewBefore(false)
     }
   }
 
-  const loadPreviewAfter = () => {
+  const loadPreviewAfter = (visibleLoad = false) => {
     const item = selectedResult()
     const last = previewParts().at(-1)
-    if (!item || !last || loadingPreviewMore()) return
-    setLoadingPreviewMore(true)
+    if (!item || !last || loadingPreviewMore() || prefetchingPreviewAfter()) return
+    visibleLoad ? setLoadingPreviewMore(true) : setPrefetchingPreviewAfter(true)
     debug.time("preview:load-after")
     try {
       const page = loadConversationAfter(item, { id: last.id, timeCreated: last.timeCreated }, { limit: PREVIEW_PAGE_SIZE, dbPath: dbPath() })
@@ -297,6 +484,7 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
         item: item.id,
         added: page.parts.length,
         hasMoreAfter: page.hasMoreAfter,
+        visibleLoad,
         first: page.parts[0]?.id,
         last: page.parts.at(-1)?.id,
       })
@@ -306,14 +494,47 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
       debug.log("preview:load-after:error", err instanceof Error ? err.message : String(err))
     } finally {
       debug.timeEnd("preview:load-after")
-      setLoadingPreviewMore(false)
+      visibleLoad ? setLoadingPreviewMore(false) : setPrefetchingPreviewAfter(false)
     }
   }
 
+  const schedulePreviewBefore = (previousContentHeight = previewContentHeight(), preserveScroll = true, visibleLoad = false) => {
+    if (!hasMorePreviewBefore() || loadingPreviewMore() || prefetchingPreviewBefore()) return
+    if (previewBeforeTimer) {
+      if (pendingPreviewBefore) {
+        pendingPreviewBefore.preserveScroll = pendingPreviewBefore.preserveScroll && preserveScroll
+        pendingPreviewBefore.visibleLoad = pendingPreviewBefore.visibleLoad || visibleLoad
+      }
+      return
+    }
+    pendingPreviewBefore = { previousContentHeight, preserveScroll, visibleLoad }
+    debug.log("preview:prefetch-before-scheduled", { preserveScroll, visibleLoad })
+    previewBeforeTimer = setTimeout(() => {
+      const pending = pendingPreviewBefore
+      previewBeforeTimer = undefined
+      pendingPreviewBefore = undefined
+      if (pending) loadPreviewBefore(pending.previousContentHeight, pending.preserveScroll, pending.visibleLoad)
+    }, 1)
+  }
+
+  const schedulePreviewAfter = (visibleLoad = false) => {
+    if (!hasMorePreviewAfter() || loadingPreviewMore() || prefetchingPreviewAfter()) return
+    pendingPreviewAfterVisible = pendingPreviewAfterVisible || visibleLoad
+    if (previewAfterTimer) return
+    debug.log("preview:prefetch-after-scheduled", { visibleLoad })
+    previewAfterTimer = setTimeout(() => {
+      const pendingVisibleLoad = pendingPreviewAfterVisible
+      previewAfterTimer = undefined
+      pendingPreviewAfterVisible = false
+      loadPreviewAfter(pendingVisibleLoad)
+    }, 1)
+  }
+
   let lastPreviewItemId = ""
   createEffect(() => {
     const item = selectedResult()
     if (!item) {
+      cancelPreviewPrefetch()
       setPreviewParts([])
       setHasMorePreviewBefore(false)
       setHasMorePreviewAfter(false)
@@ -321,6 +542,7 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
     }
     if (item.id === lastPreviewItemId) return
     lastPreviewItemId = item.id
+    cancelPreviewPrefetch()
     debug.log("preview:new-item", item.sessionTitle?.slice(0, 40) ?? item.id.slice(-8))
     const db = dbPath()
     debug.time("preview:load")
@@ -347,30 +569,36 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
     const item = selectedResult()
     if (!item) return
     const interval = setInterval(() => {
-      if (loadingPreviewMore()) return
+      if (loadingPreviewMore() || prefetchingPreviewBefore() || prefetchingPreviewAfter()) return
       const scroll = previewScroll
       const children = scroll?.getChildren()
       if (!scroll || !children || children.length === 0) return
       const lastChild = children[children.length - 1] as { y: number; height: number }
       const totalContentHeight = lastChild.y + lastChild.height
       const atTop = scroll.y <= 0
-      const nearTop = scroll.y <= 2
+      const prefetchDistance = Math.max(2, Math.floor(scroll.height * PREVIEW_PREFETCH_VIEWPORTS))
+      const nearTop = scroll.y <= prefetchDistance
       const atBottom = scroll.y + scroll.height >= totalContentHeight - 1
-      if (nearTop || atBottom) {
+      const nearBottom = scroll.y + scroll.height >= totalContentHeight - prefetchDistance
+      if (nearTop || nearBottom) {
         debug.log("preview:scroll-edge", {
           y: scroll.y,
           height: scroll.height,
           contentHeight: totalContentHeight,
+          prefetchDistance,
           atTop,
           nearTop,
           atBottom,
+          nearBottom,
           hasMoreBefore: hasMorePreviewBefore(),
           hasMoreAfter: hasMorePreviewAfter(),
+          prefetchingBefore: prefetchingPreviewBefore(),
+          prefetchingAfter: prefetchingPreviewAfter(),
           children: children.length,
         })
       }
-      if (nearTop && hasMorePreviewBefore()) loadPreviewBefore(totalContentHeight, !atTop)
-      if (atBottom && hasMorePreviewAfter()) loadPreviewAfter()
+      if (atTop && hasMorePreviewBefore()) schedulePreviewBefore(totalContentHeight, false, true)
+      if (nearBottom && hasMorePreviewAfter()) schedulePreviewAfter(atBottom)
     }, 400)
     onCleanup(() => clearInterval(interval))
   })
@@ -409,50 +637,54 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
     el?.blur?.()
   }
 
+  const toggleOwnerFilter = () => {
+    setOwnerFilter((filter) => filter === "all" ? "user" : filter === "user" ? "assistant" : "all")
+  }
+
   useKeyboard((evt) => {
     if (!props.api.ui.dialog.open) return
 
-    if (isKey(evt, "down") || isKey(evt, "up")) {
+    if (mode() !== "normal") return
+
+    if (matchesKey(evt, props.config.keys.moveDown) || matchesKey(evt, props.config.keys.moveUp)) {
       prevent(evt)
-      isKey(evt, "down") ? move(1) : move(-1)
+      matchesKey(evt, props.config.keys.moveDown) ? move(1) : move(-1)
       return
     }
 
-    if (mode() === "normal") {
-      if (isKey(evt, "j")) {
-        prevent(evt)
-        move(1)
-        return
-      }
-      if (isKey(evt, "k")) {
-        prevent(evt)
-        move(-1)
-        return
-      }
-      if (isKey(evt, "q")) {
-        prevent(evt)
-        props.onClose()
-        return
-      }
-      if (isKey(evt, "d")) {
-        scrollPreview(1, evt)
-        return
-      }
-      if (isKey(evt, "u")) {
-        scrollPreview(-1, evt)
-        return
-      }
-      if (isKey(evt, "/")) {
-        prevent(evt)
-        setMode("insert")
-        focusInput()
-        return
-      }
-      if (isKey(evt, "enter", "return")) {
-        prevent(evt)
-        open()
-        return
-      }
+    if (matchesKey(evt, props.config.keys.open)) {
+      prevent(evt)
+      open()
+      return
+    }
+
+    if (matchesKey(evt, props.config.keys.close)) {
+      prevent(evt)
+      props.onClose()
+      return
+    }
+
+    if (matchesKey(evt, props.config.keys.scrollPreviewDown)) {
+      scrollPreview(1, evt)
+      return
+    }
+
+    if (matchesKey(evt, props.config.keys.scrollPreviewUp)) {
+      scrollPreview(-1, evt)
+      return
+    }
+
+    if (matchesKey(evt, props.config.keys.toggleOwner)) {
+      prevent(evt)
+      toggleOwnerFilter()
+      return
+    }
+
+    if (matchesKey(evt, props.config.keys.insertMode)) {
+      prevent(evt)
+      setMode("insert")
+      focusInput()
+      return
     }
   })
 
@@ -483,12 +715,17 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
                   focusedBackgroundColor={theme().backgroundPanel}
                   onInput={(value) => setQuery(value)}
                   onKeyDown={(evt: ParsedKey) => {
-                    if (isKey(evt, "down") || isKey(evt, "up")) {
+                    if (matchesKey(evt, inputKeys().moveDown) || matchesKey(evt, inputKeys().moveUp)) {
+                      prevent(evt)
+                      matchesKey(evt, inputKeys().moveDown) ? move(1) : move(-1)
+                      return
+                    }
+                    if (matchesKey(evt, inputKeys().open)) {
                       prevent(evt)
-                      isKey(evt, "down") ? move(1) : move(-1)
+                      open()
                       return
                     }
-                    if (evt.ctrl && isKey(evt, "q")) {
+                    if (matchesKey(evt, inputKeys().normalMode)) {
                       prevent(evt)
                       setMode("normal")
                       blurInput()
@@ -496,13 +733,13 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
                   }}
                   flexGrow={1}
                 />
-                <text fg={theme().textMuted}>{busy() ? "searching" : loading() ? "loading..." : query().trim() ? (results().length > 0 ? `${selected() + 1}/${results().length} hits` : "0 hits") : (results().length > 0 ? `${selected() + 1}/${results().length} recent` : "0 recent")}</text>
+                <text fg={theme().textMuted}>{busy() ? `searching ${ownerLabel()}` : loading() ? `loading ${ownerLabel()}` : query().trim() ? (results().length > 0 ? `${ownerLabel()} ${selected() + 1}/${nextResultOffset()} hits` : `${ownerLabel()} 0 hits`) : (results().length > 0 ? `${ownerLabel()} ${selected() + 1}/${nextResultOffset()} recent` : `${ownerLabel()} 0 recent`)}</text>
               </box>
             </box>
 
             <box flexDirection="row" flexGrow={1} minHeight={0}>
               <box width={leftWidth()} flexDirection="column" minHeight={0} backgroundColor={theme().backgroundPanel}>
-                <scrollbox ref={(element: ScrollBoxRenderable) => (resultScroll = element)} flexGrow={1} minHeight={0} verticalScrollbarOptions={{ visible: false }}>
+                <scrollbox ref={(element: ScrollBoxRenderable) => (resultScroll = element)} flexGrow={1} minHeight={0} verticalScrollbarOptions={{ visible: true }}>
                   <Show
                     when={!error()}
                     fallback={
@@ -513,7 +750,7 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
                     }
                   >
                     <Show when={!loading()}>
-                      <Show when={results().length > 0} fallback={<EmptyState query={query()} theme={theme()} />}>
+                      <Show when={results().length > 0} fallback={<EmptyState query={query()} owner={ownerLabel()} theme={theme()} />}>
                         <For each={resultRenderWindow().items}>
                           {(item, index) => {
                             const absoluteIndex = () => resultRenderWindow().start + index()
@@ -565,23 +802,21 @@ export const Telescope = (props: { api: TuiPluginApi; onClose: () => void }) =>
             <Show when={mode() === "normal"}>
               <box paddingLeft={4} paddingRight={4} flexDirection="row" backgroundColor={theme().backgroundElement} gap={2}>
                 <text fg={theme().accent}><span style={{ bold: true }}>NORMAL</span></text>
-                <text fg={theme().textMuted}>·</text>
-                <text fg={theme().text}>j/k move</text>
-                <text fg={theme().textMuted}>·</text>
-                <text fg={theme().textMuted}>d/u scroll</text>
-                <text fg={theme().textMuted}>·</text>
-                <text fg={theme().text}>/ search</text>
-                <text fg={theme().textMuted}>·</text>
-                <text fg={theme().textMuted}>enter open</text>
-                <text fg={theme().textMuted}>·</text>
-                <text fg={theme().text}>q close</text>
+                <For each={normalHelpItems()}>
+                  {(item, index) => (
+                    <>
+                      <text fg={theme().textMuted}>·</text>
+                      <text fg={index() % 2 === 0 ? theme().text : theme().textMuted}>{item}</text>
+                    </>
+                  )}
+                </For>
               </box>
             </Show>
             <Show when={mode() === "insert"}>
               <box paddingLeft={4} paddingRight={4} flexDirection="row" backgroundColor={theme().backgroundElement} gap={2}>
                 <text fg={theme().warning}><span style={{ bold: true }}>INSERT</span></text>
                 <text fg={theme().textMuted}>·</text>
-                <text fg={theme().textMuted}>↑/↓ move · ^Q normal</text>
+                <text fg={theme().textMuted}>{keyListLabel(inputKeys().moveUp)}/{keyListLabel(inputKeys().moveDown)} move · {keyListLabel(inputKeys().normalMode)} normal</text>
               </box>
             </Show>
 

package/tui.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @opentui/solid */
 import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
 import { Telescope } from "./telescope.tsx"
+import { loadTelescopeConfig } from "./ui/config.ts"
 
 const id = "opencode-telescope"
 
@@ -13,9 +14,10 @@ const enabled = (options: unknown) => {
 const tui: TuiPlugin = async (api: TuiPluginApi, options: unknown) => {
   if (!enabled(options)) return
 
+  const config = loadTelescopeConfig()
   const command = "opencode.telescope.sessions"
   const open = () => {
-    api.ui.dialog.replace(() => <Telescope api={api} onClose={() => api.ui.dialog.clear()} />)
+    api.ui.dialog.replace(() => <Telescope api={api} config={config} onClose={() => api.ui.dialog.clear()} />)
     api.ui.dialog.setSize("xlarge")
   }
 
@@ -30,7 +32,7 @@ const tui: TuiPlugin = async (api: TuiPluginApi, options: unknown) => {
         run: open,
       },
     ],
-    bindings: [{ key: "<leader>f", desc: "Search conversations", group: "Search", cmd: open }],
+    bindings: [{ key: config.openKey, desc: "Search conversations", group: "Search", cmd: open }],
   })
 
   api.lifecycle.onDispose(() => {

package/ui/config.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { defaultTelescopeConfig, loadTelescopeConfig, parseTelescopeConfig, telescopeConfigPath } from "./config.ts"
+
+describe("telescope config", () => {
+  test("uses defaults for missing config", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "opencode-telescope-config-"))
+    try {
+      expect(loadTelescopeConfig(path.join(dir, "missing.json"))).toEqual(defaultTelescopeConfig)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  test("uses defaults for invalid json", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "opencode-telescope-config-"))
+    const file = path.join(dir, "config.json")
+    try {
+      writeFileSync(file, "{")
+      expect(loadTelescopeConfig(file)).toEqual(defaultTelescopeConfig)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  test("merges valid partial config and ignores invalid fields", () => {
+    const config = parseTelescopeConfig({
+      openKey: " <leader>s ",
+      keys: {
+        moveDown: ["n", 1, ""],
+        moveUp: [],
+        open: "ctrl+o",
+      },
+    })
+
+    expect(config.openKey).toBe("<leader>s")
+    expect(config.keys.moveDown).toEqual(["n"])
+    expect(config.keys.moveUp).toEqual(defaultTelescopeConfig.keys.moveUp)
+    expect(config.keys.open).toEqual(["ctrl+o"])
+    expect(config.keys.close).toEqual(defaultTelescopeConfig.keys.close)
+  })
+
+  test("resolves config under XDG_CONFIG_HOME", () => {
+    expect(telescopeConfigPath({ XDG_CONFIG_HOME: "/tmp/config" })).toBe("/tmp/config/opencode/opencode-telescope/config.json")
+  })
+})

package/ui/config.ts

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import path from "node:path"
+
+export type TelescopeKeyAction =
+  | "moveDown"
+  | "moveUp"
+  | "scrollPreviewDown"
+  | "scrollPreviewUp"
+  | "open"
+  | "close"
+  | "insertMode"
+  | "normalMode"
+  | "toggleOwner"
+
+export type TelescopeConfig = {
+  openKey: string
+  keys: Record<TelescopeKeyAction, string[]>
+}
+
+export const defaultTelescopeConfig: TelescopeConfig = {
+  openKey: "<leader>f",
+  keys: {
+    moveDown: ["down", "j"],
+    moveUp: ["up", "k"],
+    scrollPreviewDown: ["d"],
+    scrollPreviewUp: ["u"],
+    open: ["enter", "return"],
+    close: ["q", "escape"],
+    insertMode: ["/"],
+    normalMode: ["ctrl+q"],
+    toggleOwner: ["o"],
+  },
+}
+
+export function telescopeConfigPath(env: NodeJS.ProcessEnv = process.env) {
+  const configHome = env.XDG_CONFIG_HOME || path.join(homedir(), ".config")
+  return path.join(configHome, "opencode", "opencode-telescope", "config.json")
+}
+
+export function loadTelescopeConfig(configPath = telescopeConfigPath()): TelescopeConfig {
+  if (!existsSync(configPath)) return cloneConfig(defaultTelescopeConfig)
+
+  try {
+    return parseTelescopeConfig(JSON.parse(readFileSync(configPath, "utf8")))
+  } catch {
+    return cloneConfig(defaultTelescopeConfig)
+  }
+}
+
+export function parseTelescopeConfig(value: unknown): TelescopeConfig {
+  const config = cloneConfig(defaultTelescopeConfig)
+  if (!isRecord(value)) return config
+
+  if (typeof value.openKey === "string" && value.openKey.trim()) {
+    config.openKey = value.openKey.trim()
+  }
+
+  if (!isRecord(value.keys)) return config
+  for (const action of Object.keys(defaultTelescopeConfig.keys) as TelescopeKeyAction[]) {
+    const parsed = parseKeyList(value.keys[action])
+    if (parsed) config.keys[action] = parsed
+  }
+
+  return config
+}
+
+function parseKeyList(value: unknown) {
+  if (typeof value === "string") {
+    const key = value.trim()
+    return key ? [key] : undefined
+  }
+  if (!Array.isArray(value)) return
+
+  const keys = value
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim())
+    .filter(Boolean)
+  return keys.length > 0 ? keys : undefined
+}
+
+function cloneConfig(config: TelescopeConfig): TelescopeConfig {
+  return {
+    openKey: config.openKey,
+    keys: Object.fromEntries(
+      Object.entries(config.keys).map(([action, keys]) => [action, [...keys]]),
+    ) as Record<TelescopeKeyAction, string[]>,
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value))
+}

package/ui/keyboard.test.ts

@@ -0,0 +1,40 @@
+import type { ParsedKey } from "@opentui/core"
+import { describe, expect, test } from "bun:test"
+import { inputSafeKeys, keyListLabel, matchesKey } from "./keyboard.ts"
+
+describe("keyboard helpers", () => {
+  test("matches simple key names", () => {
+    expect(matchesKey(key("j"), ["j"])).toBe(true)
+    expect(matchesKey(key("j"), ["k"])).toBe(false)
+  })
+
+  test("matches ctrl modifier strings", () => {
+    expect(matchesKey(key("q", { ctrl: true }), ["ctrl+q"])).toBe(true)
+    expect(matchesKey(key("q"), ["ctrl+q"])).toBe(false)
+  })
+
+  test("labels configured key lists", () => {
+    expect(keyListLabel(["ctrl+q"])).toBe("^q")
+    expect(keyListLabel(["enter", "return"])).toBe("enter/return")
+  })
+
+  test("filters text input unsafe plain character keys", () => {
+    expect(inputSafeKeys(["j", "down", "ctrl+j"])).toEqual(["down", "ctrl+j"])
+  })
+})
+
+function key(name: string, options: Partial<ParsedKey> = {}): ParsedKey {
+  return {
+    name,
+    ctrl: false,
+    meta: false,
+    shift: false,
+    option: false,
+    sequence: name,
+    number: false,
+    raw: name,
+    eventType: "press",
+    source: "raw",
+    ...options,
+  }
+}

package/ui/keyboard.ts

@@ -4,6 +4,40 @@ export function isKey(evt: ParsedKey, ...names: string[]) {
   return names.includes(evt.name)
 }
 
+export function matchesKey(evt: ParsedKey, keys: string[]) {
+  return keys.some((key) => matchesKeyString(evt, key))
+}
+
+export function keyListLabel(keys: string[]) {
+  return keys.map(keyLabel).join("/")
+}
+
+export function inputSafeKeys(keys: string[]) {
+  return keys.filter((key) => key.includes("+") || key.length > 1)
+}
+
+function matchesKeyString(evt: ParsedKey, key: string) {
+  const parts = key.toLowerCase().split("+").map((part) => part.trim()).filter(Boolean)
+  const name = parts.at(-1)
+  if (!name || evt.name.toLowerCase() !== name) return false
+
+  const modifiers = new Set(parts.slice(0, -1))
+  return Boolean(evt.ctrl) === modifiers.has("ctrl") &&
+    Boolean(evt.meta) === modifiers.has("meta") &&
+    Boolean(evt.shift) === modifiers.has("shift") &&
+    Boolean(evt.option) === (modifiers.has("alt") || modifiers.has("option"))
+}
+
+function keyLabel(key: string) {
+  return key.split("+")
+    .map((part) => {
+      const value = part.trim()
+      if (value.toLowerCase() === "ctrl") return "^"
+      return value
+    })
+    .join("")
+}
+
 export function prevent(evt: ParsedKey) {
   const controlled = evt as ParsedKey & {
     preventDefault?: () => void