opencode-ghost 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-09-25
+
+### Changed
+
+- Slash-command argument hints are dimmed at the same opacity as every other
+  ghost; they keep the theme accent hue but no longer appear brighter than the
+  next-message and history ghosts.
+## [0.2.4] - 2026-09-25
+
+### Fixed
+
+- Long next-message suggestions now wrap onto extra rows and grow the prompt
+  box instead of being clipped at its right edge, so the whole suggestion stays
+  readable.
+- Slash commands and skills only suggest their accepted argument flags (from
+  `argHints`); command and skill descriptions are no longer echoed as if they
+  were arguments. Commands without hints show no ghost.
+
+### Changed
+
+- Ghost styling: slash-command ghosts use the theme accent color, and every
+  other ghost is dimmed and clipped to the prompt box so it cannot be mistaken
+  for typed text.
 ## [0.2.3] - 2026-09-25
 
 ### Removed
@@ -82,7 +105,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Options for `model`, `acceptKeys`, `maxChars`, `idleDelayMs`,
   `recentMessages` and `system`.
 
-[Unreleased]: https://github.com/ozandogrultan/opencode-ghost/compare/v0.2.3...HEAD
+[Unreleased]: https://github.com/ozandogrultan/opencode-ghost/compare/v0.2.5...HEAD
+[0.2.5]: https://github.com/ozandogrultan/opencode-ghost/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/ozandogrultan/opencode-ghost/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/ozandogrultan/opencode-ghost/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/ozandogrultan/opencode-ghost/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/ozandogrultan/opencode-ghost/compare/v0.2.0...v0.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 opencode-ghost contributors
+Copyright (c) 2026 Ozan Dogrultan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -17,14 +17,21 @@ dimmed ghost text you accept with <kbd>Tab</kbd> (or <kbd>→</kbd>).
   default) for one line that sounds like you.
 - **Ghost text, `Tab` to accept.** The suggestion renders under the prompt;
   `Tab` or `→` drops it into the input so you can edit and send.
-- **Slash-command argument ghosts while typing.** After `/name `, argument
-  option hints (from `argHints` or learned from builtins) render inside the
-  prompt input box, right after the caret, like Claude Code's inline ghosts.
-  Tab completes the next argument. While the command name is still being typed,
-  opencode's own slash menu stays in charge. Purely local — no model calls.
+- **Slash-command argument ghosts while typing.** After `/name `, accepted
+  argument options (from `argHints`) render inside the prompt input box, right
+  after the caret, as `[a | b | c]` like Claude Code. Running out of options or
+  naming a command with no configured hints shows no ghost — command and skill
+  descriptions are never suggested as if they were arguments. Tab completes the
+  next argument. While the command name is still being typed, opencode's own
+  slash menu stays in charge. Purely local — no model calls.
 - **History ghost while typing.** If the line you are typing is a prefix of a
   message you already sent in the same session, the rest of it is ghosted in
   the box as well; Tab pulls the full line back. Also purely local.
+- **Distinct ghost styling.** Slash-command ghosts use the theme accent color;
+  every ghost is dimmed so it cannot be mistaken for typed text. A
+  next-message suggestion that is wider than the prompt wraps onto extra rows
+  and grows the prompt box (up to five rows) so it stays fully readable; other
+  ghosts are clipped to the box and never spill past it.
 - **`/suggest` toggles it.** State is stored in the plugin KV.
 
 ## Requirements
@@ -97,7 +104,7 @@ Pass an options object as the second element of the plugin tuple:
 | `system`         | `string`   | built-in              | Override the system prompt sent to the suggestion model.              |
 | `backOnEmptyLeft` | `boolean`  | `false`               | Return to the home screen with Left when the prompt is empty.         |
 | `internalSessionMarkerDir` | `string` | unset       | Optional extra crash-recovery tracking. A configuration-free sweep already reaps leftover hidden sessions, so this is only an additional safety net. |
-| `argHints` | `Record<string, string[]>` | `{}` | Argument option lists per slash command, shown as `[a \| b \| c]` after the command name and completed with Tab, e.g. `"/keepwarm": ["6h", "always", "off", "status"]`. |
+| `argHints` | `Record<string, string[]>` | `{}` | Argument option lists per slash command, shown as `[a \| b \| c]` after a complete `/name ` and completed with Tab, e.g. `"/keepwarm": ["6h", "always", "off", "status"]`. Commands without an entry suggest no arguments. |
 
 ## Commands
 
@@ -148,6 +155,12 @@ bun test
 No build step: like other opencode TUI plugins, the package ships TSX source and
 opencode's runtime transpiles it.
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the check suite and commit
+conventions, [AGENTS.md](AGENTS.md) for the design rules, and
+[CHANGELOG.md](CHANGELOG.md) for what changed.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-ghost",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Claude Code-style next-prompt suggestions in the opencode TUI, shown as dimmed ghost text and accepted with Tab. An opencode plugin.",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,15 @@
   "bugs": {
     "url": "https://github.com/ozandogrultan/opencode-ghost/issues"
   },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "ghost-text",
+    "autosuggest",
+    "prompt",
+    "suggestion"
+  ],
   "exports": {
     "./tui": "./src/tui.tsx"
   },
@@ -25,25 +34,19 @@
   "publishConfig": {
     "access": "public"
   },
+  "packageManager": "bun@1.4.2",
+  "engines": {
+    "opencode": ">=1.18.0"
+  },
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "prepare": "husky",
     "test": "bun test && bash tests/changelog.sh",
     "test:unit": "bun test",
     "test:changelog": "bash tests/changelog.sh",
+    "typecheck": "tsc --noEmit",
+    "lint:sh": "for script in install.sh tests/*.sh scripts/*.sh; do bash -n \"$script\" || exit; done",
     "prepublishOnly": "bun run test && bun run typecheck"
   },
-  "engines": {
-    "opencode": ">=1.18.0"
-  },
-  "keywords": [
-    "opencode",
-    "opencode-plugin",
-    "tui",
-    "ghost-text",
-    "autosuggest",
-    "prompt",
-    "suggestion"
-  ],
   "dependencies": {
     "solid-js": "^1.9.12"
   },
@@ -52,11 +55,14 @@
     "solid-js": "*"
   },
   "devDependencies": {
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
     "@opencode-ai/plugin": "1.18.25",
     "@opentui/core": "0.4.5",
     "@opentui/keymap": "0.4.5",
     "@opentui/solid": "0.4.5",
     "@types/node": "24.12.2",
+    "husky": "^9.1.7",
     "typescript": "5.8.2"
   }
 }

package/src/completion.ts

@@ -16,8 +16,6 @@ export type Completion = {
   insert?: string
   /** Argument options shown as `[a | b]`, filtered by the word in progress. */
   args?: string[]
-  /** Non-insertable hint text shown when nothing can be completed. */
-  hint?: string
 }
 
 /** Parse leading `/name args...` from the input; `args` is "" until a space exists. */
@@ -54,7 +52,6 @@ export function completeCommand(
       const hints = argHints[lower]
       return {
         args: hints ? [...hints] : undefined,
-        hint: hints ? undefined : exact.description,
         insert: `/${exact.name} `,
       }
     }
@@ -66,18 +63,13 @@ export function completeCommand(
 
   // `/name args...`: complete the in-progress argument word against hints.
   const hintList = argHints[lower]
-  if (hintList) {
-    const matches = matchOptions(parsed.args, hintList)
-    if (matches) {
-      const completed = parsed.args + matches[0].slice(parsed.args.length)
-      return {
-        args: matches,
-        ghost: matches[0].slice(parsed.args.length),
-        insert: `/${parsed.name} ${completed} `,
-      }
-    }
-    return undefined
+  if (!hintList) return undefined
+  const matches = matchOptions(parsed.args, hintList)
+  if (!matches) return undefined
+  const completed = parsed.args + matches[0].slice(parsed.args.length)
+  return {
+    args: matches,
+    ghost: matches[0].slice(parsed.args.length),
+    insert: `/${parsed.name} ${completed} `,
   }
-  if (exact && parsed.args === "") return { hint: exact.description }
-  return undefined
 }

package/src/text.ts

@@ -33,6 +33,34 @@ export function normalize(raw: string, maxChars: number): string | undefined {
   return cleaned.slice(0, maxChars - 1).trimEnd() + "…"
 }
 
+/**
+ * Number of visual rows `text` occupies when word-wrapped to `width` columns.
+ * Mirrors the greedy word wrap the prompt renderer uses, so a ghost can reserve
+ * exactly as many rows as it needs. Long words break at the column boundary.
+ */
+export function wrapCount(text: string, width: number): number {
+  if (width <= 0) return 1
+  let lines = 1
+  let col = 0
+  for (const word of text.split(/\s+/).filter(Boolean)) {
+    let length = word.length
+    if (col > 0) {
+      if (col + 1 + length <= width) {
+        col += 1 + length
+        continue
+      }
+      lines += 1
+      col = 0
+    }
+    while (length > width) {
+      lines += 1
+      length -= width
+    }
+    col = length
+  }
+  return lines
+}
+
 export function isEcho(suggestion: string, previous: string): boolean {
   const strip = (value: string) =>
     value

package/src/tui.tsx

@@ -4,7 +4,7 @@ import { createSignal } from "solid-js"
 import * as fs from "node:fs"
 import * as path from "node:path"
 import { resolveOptions, type PromptSuggestOptions } from "./options"
-import { clip, isEcho, normalize, parseModel } from "./text"
+import { clip, isEcho, normalize, parseModel, wrapCount } from "./text"
 import { BUILTIN_COMMANDS } from "./builtins"
 import { completeCommand, type CommandPool } from "./completion"
 
@@ -17,6 +17,13 @@ const ORPHAN_SWEEP_INTERVAL_MS = 30_000
 const ORPHAN_MIN_AGE_MS = 15_000
 const MAX_MESSAGE_CHARS = 800
 const MAX_TRANSCRIPT_CHARS = 6000
+// The prompt editor grows to fit a wrapped next-message suggestion only up to
+// this many rows; longer text is clipped. The host caps its editor at >= 6 rows
+// by default, so 5 stays inside that ceiling.
+const MAX_GHOST_LINES = 5
+// Every ghost is drawn at this opacity so it always reads as a suggestion, not
+// typed text. Slash-command ghosts keep the accent hue but are dimmed too.
+const GHOST_OPACITY = 0.6
 const ENABLED_KEY = "ghost.enabled"
 const MODEL_KEY = "ghost.model"
 
@@ -341,10 +348,21 @@ const tui: TuiPlugin = async (api, rawOptions) => {
   // walking the layout tree). Uses the normal render pipeline, so it is visible
   // wherever the prompt is. When the editor or container cannot be located
   // (host layout change) completion falls back to the hint row.
+  type GhostColor = typeof api.theme.current.textMuted
   const [inBox, setInBox] = createSignal<
-    { sessionID: string; x: number; y: number; text: string } | undefined
+    {
+      sessionID: string
+      x: number
+      y: number
+      text: string
+      width: number
+      height: number
+      wrap: boolean
+      color: GhostColor
+      opacity: number
+    } | undefined
   >()
-  let slotNode: { screenX?: number; screenY?: number } | undefined
+  let slotNode: { screenX?: number; screenY?: number; width?: number } | undefined
   // Locate the prompt's editor renderable inside the layout tree.
   const findTextarea = (): unknown => {
     const root = (api.renderer as unknown as { root?: unknown }).root as
@@ -360,6 +378,8 @@ const tui: TuiPlugin = async (api, rawOptions) => {
             visualCursor?: { visualRow?: number; visualCol?: number }
             screenX?: number
             screenY?: number
+            width?: number
+            minHeight?: number
             getChildren?: () => unknown[]
           }
         | undefined
@@ -371,10 +391,38 @@ const tui: TuiPlugin = async (api, rawOptions) => {
     return undefined
   }
 
-  const placeInBoxGhost = (sessionID: string, text: string): boolean => {
+  // A wrapped next-message suggestion is shown by growing the host editor's
+  // min height to the number of rows it needs, so the prompt box grows instead
+  // of clipping the text. The host sets minHeight once at creation (not
+  // reactively), so the value we set survives until we reset it.
+  let heightManaged: { minHeight?: number } | undefined
+  const resetEditorHeight = () => {
+    if (!heightManaged) return
+    try {
+      heightManaged.minHeight = 1
+    } catch {
+      // The editor may have been recreated or destroyed; best effort.
+    }
+    heightManaged = undefined
+  }
+
+  const placeInBoxGhost = (
+    sessionID: string,
+    text: string,
+    color: GhostColor,
+    opacity: number,
+    wrap: boolean,
+  ): boolean => {
+    resetEditorHeight()
     setInBox(undefined)
     const textarea = findTextarea() as
-      | { screenX?: unknown; screenY?: unknown; visualCursor?: { visualRow?: number; visualCol?: number } }
+      | {
+          screenX?: unknown
+          screenY?: unknown
+          width?: unknown
+          minHeight?: number
+          visualCursor?: { visualRow?: number; visualCol?: number }
+        }
       | undefined
     if (
       !textarea ||
@@ -384,6 +432,7 @@ const tui: TuiPlugin = async (api, rawOptions) => {
       return false
     }
     const cursor = textarea.visualCursor ?? {}
+    const visualCol = typeof cursor.visualCol === "number" ? cursor.visualCol : 0
     // Overlay coordinates are relative to the slot container (it anchors the
     // absolute overlay), so subtract its screen origin from the editor's.
     if (
@@ -393,9 +442,30 @@ const tui: TuiPlugin = async (api, rawOptions) => {
     ) {
       return false
     }
-    const x = textarea.screenX - slotNode.screenX + (typeof cursor.visualCol === "number" ? cursor.visualCol : 0)
+    const x = textarea.screenX - slotNode.screenX + visualCol
     const y = textarea.screenY - slotNode.screenY + (typeof cursor.visualRow === "number" ? cursor.visualRow : 0)
-    setInBox({ sessionID, x, y, text })
+    // Keep the ghost inside the prompt box: clip it to the editor's remaining
+    // width so it never spills past the box's right edge.
+    const editorWidth = typeof textarea.width === "number" ? textarea.width : undefined
+    const width =
+      editorWidth !== undefined
+        ? editorWidth - visualCol
+        : typeof slotNode.width === "number"
+          ? slotNode.width - x
+          : undefined
+    if (width === undefined || width <= 0) return false
+    let height = 1
+    if (wrap) {
+      height = Math.max(1, Math.min(MAX_GHOST_LINES, wrapCount(text, width)))
+      try {
+        textarea.minHeight = height
+        heightManaged = textarea
+      } catch {
+        // If the host editor cannot be resized, fall back to a one-row clip.
+        height = 1
+      }
+    }
+    setInBox({ sessionID, x, y, text, width, height, wrap: wrap && height > 1, color, opacity })
     return true
   }
 
@@ -409,37 +479,52 @@ const tui: TuiPlugin = async (api, rawOptions) => {
         setCompletion(undefined)
         setInBox(undefined)
       }
+      resetEditorHeight()
       return
     }
     const input = promptRef?.current.input ?? ""
     if (poolFetchedAt && Date.now() - poolFetchedAt > POOL_TTL_MS) void refreshPool()
+    const isSlash = input.startsWith("/")
+    const startsEmpty = !input.trim()
     // `/name` with no space yet is opencode's native slash menu; the plugin
     // stays out of its way. Our slash completion only covers `/name args...`.
-    const found = !input.startsWith("/")
+    const found = !isSlash
       ? historyCandidate(sessionID, input)
       : input.includes(" ")
         ? completeCommand(input, commandPool, opts.argHints)
         : undefined
     let display = ""
     let insert = ""
+    let wrap = false
+    // Slash-command completions are tinted like commands; every ghost is dimmed
+    // so it cannot be mistaken for typed text.
+    const color = isSlash ? api.theme.current.accent : api.theme.current.textMuted
+    const opacity = GHOST_OPACITY
     if (found) {
       const args = "args" in found ? found.args : undefined
-      const hint = "hint" in found ? found.hint : undefined
       insert = found.insert ?? ""
-      display = args && args.length > 0 ? `[${args.join(" | ")}]` : (found.ghost ?? hint ?? "")
-    } else if (!input.trim()) {
+      display = args && args.length > 0 ? `[${args.join(" | ")}]` : (found.ghost ?? "")
+    } else if (startsEmpty) {
       // Empty prompt: the model's next-message suggestion is ghosted in the
-      // box as well (the accept layer's `accept()` handles Tab for it).
+      // box as well (the accept layer's `accept()` handles Tab for it). It is
+      // the only ghost allowed to wrap and grow the prompt box, since it can be
+      // longer than the visible width and there is no typed text to disturb.
       const next = ghost()
-      if (next && next.sessionID === sessionID) display = next.text
+      if (next && next.sessionID === sessionID) {
+        display = next.text
+        wrap = true
+      }
     }
-    // Include the display in the key: a fresh suggestion for an unchanged
-    // (empty) input must still be re-placed.
-    const key = `${sessionID}\u0000${input}\u0000${display}`
+    // Include the display and renderer width in the key: a fresh suggestion for
+    // an unchanged (empty) input must be re-placed, and a resize must re-wrap.
+    const key = `${sessionID}\u0000${input}\u0000${display}\u0000${api.renderer.width}`
     if (completionKey === key) return
     completionKey = key
-    const drawn = display ? placeInBoxGhost(sessionID, display) : false
-    if (!drawn) setInBox(undefined)
+    const drawn = display ? placeInBoxGhost(sessionID, display, color, opacity, wrap) : false
+    if (!drawn) {
+      setInBox(undefined)
+      resetEditorHeight()
+    }
     setCompletion(
       found
         ? {
@@ -656,6 +741,9 @@ const tui: TuiPlugin = async (api, rawOptions) => {
     if (currentInput().trim()) return false
     promptRef.set({ input: current.text, parts: [] })
     promptRef.focus()
+    completionKey = ""
+    setInBox(undefined)
+    resetEditorHeight()
     showGhost(undefined)
     return true
   }
@@ -706,7 +794,7 @@ const tui: TuiPlugin = async (api, rawOptions) => {
         return (
           <box
             position="relative"
-            ref={(ref: { screenX?: number; screenY?: number }) => {
+            ref={(ref: { screenX?: number; screenY?: number; width?: number }) => {
               slotNode = ref
             }}
           >
@@ -727,8 +815,23 @@ const tui: TuiPlugin = async (api, rawOptions) => {
               }}
             />
             {overlay() ? (
-              <box position="absolute" left={overlay()!.x} top={overlay()!.y} zIndex={100}>
-                <text fg={api.theme.current.textMuted}>{overlay()!.text}</text>
+              <box
+                position="absolute"
+                left={overlay()!.x}
+                top={overlay()!.y}
+                width={overlay()!.width}
+                height={overlay()!.height}
+                overflow="hidden"
+                opacity={overlay()!.opacity}
+                zIndex={100}
+              >
+                <text
+                  fg={overlay()!.color}
+                  wrapMode={overlay()!.wrap ? "word" : "none"}
+                  truncate={!overlay()!.wrap}
+                >
+                  {overlay()!.text}
+                </text>
               </box>
             ) : undefined}
           </box>
@@ -770,6 +873,7 @@ const tui: TuiPlugin = async (api, rawOptions) => {
     clearInterval(sweepTimer)
     clearInterval(pollTimer)
     setInBox(undefined)
+    resetEditorHeight()
     offIdle()
     offStatus()
     backLayer()