@cryer/star-cli 0.2.1 → 0.3.0

package/README.md

@@ -15,7 +15,7 @@ Multi-model LLM access · streaming terminal UI · tool calling · permission co
 
 </div>
 
-Features: streaming REPL with slash commands (+ autocomplete) · OpenAI / Anthropic / OpenAI-compatible providers · built-in fs / bash / web tools with a permission gate · git integration (`/commit` drafts Conventional Commits messages, `/diff` shows a colored working-tree diff, repo status injected into the system prompt) · plan mode with read-only research and plan approval · thinking spinner with dim reasoning preview · diff preview on write/edit approval · `@file` mentions · `!cmd` shell passthrough · custom slash commands from Markdown files · conversation compaction (`/compact`) · session persistence and resume with auto-generated titles (`/resume`, `star -r`) · subagent delegation for focused subtasks · lifecycle hooks (`PreToolUse`/`PostToolUse`/`Stop` shell commands from config) · file-write snapshots with `/undo` and checkpoint rollback with `/rewind` · persistent permission allow-rules · TODO task tracking · background shell tasks with status-bar visibility (`/tasks`) · terminal bell on long turns and background-task completion · Markdown session export (`/export`) · `/init` + `/doctor` project scaffolding and environment checks · cost estimation · update notifier · `--json` NDJSON output for scripting.
+Features: streaming REPL with slash commands (+ autocomplete) · OpenAI / Anthropic / OpenAI-compatible providers · built-in fs / bash / web tools with a permission gate · git integration (`/commit` drafts Conventional Commits messages, `/diff` shows a colored working-tree diff, repo status injected into the system prompt) · plan mode with read-only research and plan approval · thinking spinner with dim reasoning preview · diff preview on write/edit approval · `@file` mentions · `!cmd` shell passthrough · custom slash commands from Markdown files · conversation compaction (`/compact`) · session persistence and resume with auto-generated titles (`/resume`, `star -r`) · subagent delegation for focused subtasks · lifecycle hooks (`PreToolUse`/`PostToolUse`/`Stop` shell commands from config) · file-write snapshots with `/undo` and checkpoint rollback with `/rewind` · TODO task tracking · background shell tasks with status-bar visibility (`/tasks`) · terminal bell on long turns and background-task completion · Markdown session export (`/export`) · `/init` + `/doctor` project scaffolding and environment checks · cost estimation · update notifier · `--json` NDJSON output for scripting.
 
 ## Requirements
 
@@ -61,6 +61,9 @@ notifyBellThresholdSec = 10    # turns shorter than this stay silent
 [permissions]
 # persistent allow-rules, written automatically when you pick "a" (always) on a permission prompt
 allow = ["bash(npm test)", "read_file"]   # <tool> or <tool(<pattern>)>, * is a glob wildcard
+# persistent deny-rules — checked after the hard safety rules; they beat auto mode
+# and allow-rules (yolo still bypasses everything)
+deny = ["bash(rm -rf *)"]
 
 [[providers]]
 name = "openai"
@@ -124,9 +127,11 @@ star --clear-sessions all     delete every stored session
 
 | Command | Description |
 |---|---|
-| `/help` | list commands |
-| `/model [name]` | list / switch models |
-| `/resume [id\|--all]` | list sessions for this directory (`--all`: every directory, with cwd shown) or resume a session by id |
+| `/help` | list commands, grouped by category |
+| `/model [name]` | switch models — no argument opens an interactive picker (context window, pricing, current marker) |
+| `/resume [id\|--all]` | resume a session by id — no argument opens an interactive picker of recent sessions (message count, relative time, first-message preview; `--all`: every directory, with cwd shown) |
+| `/fork` | branch the current session into a copy and switch to it — explore another direction without losing the original |
+| `/search <query>` | full-text search across every stored session (messages, tool calls and results), with snippets — resume a hit with `/resume <id>` |
 | `/new` | start a new session with a clean context (the old session stays on disk) |
 | `/clear-sessions [--all]` | delete stored sessions: this directory by default, every session with `--all` (the current session is kept) |
 | `/todo` | show TODO list |
@@ -134,8 +139,9 @@ star --clear-sessions all     delete every stored session
 | `/cost` | show API token usage and estimated $ cost (needs per-model pricing in config) |
 | `/usage` | token usage dashboard across all sessions: totals, per-day bar chart, per-model breakdown with $ estimate |
 | `/config` | show resolved config |
-| `/permission [mode]` | show / set the global permission mode (`ask`, `auto`, `readonly`, `yolo`) — saved to config |
+| `/permission [mode]` | set the permission mode — no argument opens an interactive picker; `ask` / `auto` / `readonly` / `yolo` are saved to config, `plan` stays session-only |
 | `/plan` | toggle plan mode: read-only research, then approve the generated plan before it executes (session-only) |
+| `/memory [add <text>]` | show the long-term memory file (`~/.star-cli/MEMORY.md`, injected into every session's system prompt), or append a line to it — see [Long-term memory](#long-term-memory) |
 | `/compact` | compact conversation history to free up context |
 | `/export [path]` | export the current session to a Markdown file |
 | `/undo` | undo the last conversation turn: revert its file changes (write_file/edit_file) and retract its messages — earlier turns are never touched |
@@ -150,7 +156,7 @@ star --clear-sessions all     delete every stored session
 | `/exit` | quit |
 | `/q` | quit (alias of `/exit`) |
 
-Keys: `ESC` / `Ctrl+C` interrupts the current stream; on a permission prompt: `y` allow, `n` deny, `a` always allow — the generated allow-rule (e.g. `bash(npm test)`) is saved to `permissions.allow` in the config file and survives restarts. Write/edit prompts include a colored diff preview of the pending change. `Shift+Tab` cycles the permission mode for the session (`ask` → `auto` → `readonly` → `plan`; not saved to config). Input editing: arrow keys move the cursor, `Ctrl+A`/`Ctrl+E` jump to start/end, `Ctrl+U`/`Ctrl+K` delete before/after the cursor, `Ctrl+W` deletes the previous word, up/down recall history. Typing `/` shows slash-command suggestions — `↑`/`↓` to highlight, `Tab` (or `→` at end of input) to complete, `ESC` to dismiss. Typing `@` completes file paths relative to the working directory with the same keys; directories end in `/` so `Tab` descends, and `node_modules`, `.git` and `dist` are skipped. `Alt+V` pastes an image from the clipboard as an attachment (each one shows as `[image attached: clipboard.png]` above the input; uses PowerShell on Windows, pngpaste/osascript on macOS, xclip on Linux). `Ctrl+V` also works where the terminal passes it through — Windows Terminal binds Ctrl+V to its own paste, so use `Alt+V` there. While a turn is streaming you can keep typing: submitted prompts (and `!` bangs) queue up as dimmed entries and auto-send in order once the turn finishes; `ESC` during a turn aborts it and clears the queue. Pressing `ESC` twice within half a second while idle retracts your last prompt and restores its text into the input for editing.
+Keys: `ESC` / `Ctrl+C` interrupts the current stream; on a permission prompt: `y` allow, `n` deny, `a` always allow — the generated allow-rule (e.g. `bash(npm test)`) is saved to `permissions.allow` in the config file and survives restarts. Write/edit prompts include a colored diff preview of the pending change. `Shift+Tab` cycles the permission mode for the session (`ask` → `auto` → `readonly` → `plan`; not saved to config). Input editing: arrow keys move the cursor, `Ctrl+A`/`Ctrl+E` jump to start/end, `Ctrl+U`/`Ctrl+K` delete before/after the cursor, `Ctrl+W` deletes the previous word, up/down recall history (persisted to `~/.star-cli/history` across sessions, consecutive duplicates collapsed). Multi-line input: `Shift+Enter` inserts a newline where the terminal reports it; on terminals that don't (e.g. Windows Terminal) use `Ctrl+J` or end the line with `\` and press `Enter` — pasted multi-line text is kept intact. Typing `/` shows slash-command suggestions with their usage — prefix matches first, then fuzzy subsequence matches; `↑`/`↓` to highlight, `Tab` (or `→` at end of input) to complete, `ESC` to dismiss, and an unknown command name gets a `Did you mean: …` hint. Typing `@` completes file paths relative to the working directory with the same keys; directories end in `/` so `Tab` descends, and `node_modules`, `.git`, `dist` and `.starignore` entries are skipped. `Alt+V` pastes an image from the clipboard as an attachment (each one shows as `[image attached: clipboard.png]` above the input; uses PowerShell on Windows, pngpaste/osascript on macOS, xclip on Linux). `Ctrl+V` also works where the terminal passes it through — Windows Terminal binds Ctrl+V to its own paste, so use `Alt+V` there. While a turn is streaming you can keep typing: submitted prompts (and `!` bangs) queue up as dimmed entries and auto-send in order once the turn finishes; `ESC` during a turn aborts it and clears the queue. Pressing `ESC` twice within half a second while idle retracts your last prompt and restores its text into the input for editing.
 
 While the model is working, a spinner (`- \ | /`) shows `star is thinking…`; reasoning models also stream a dimmed tail of their thinking (last ~200 chars), which collapses to a one-line summary once the answer starts.
 
@@ -238,6 +244,10 @@ Check error handling, naming, and test coverage. Report concrete findings with f
 
 Available skills are listed in the system prompt (name + description only, so they cost almost no tokens until used). When a request matches one, the agent calls the read-level `skill` tool to load the full body — supporting files next to the `SKILL.md` (scripts, templates, examples) are resolved relative to the skill's directory. Skills added mid-session are picked up on the next turn; `/skills` lists what's currently visible. Bodies are capped at 32KB.
 
+## Long-term memory
+
+`~/.star-cli/MEMORY.md` is user-curated long-term memory, injected into the system prompt at the start of every turn (next to the project `AGENTS.md`, capped at 32KB) so preferences and conventions survive across sessions and projects. It is only ever written when you say so: `/memory add <text>` appends a bullet, and the agent's `remember` tool (write permission level, so it goes through the permission gate in `ask` mode) is contractually restricted to explicit "remember this" requests — nothing is recorded autonomously. `/memory` with no argument shows the current content and path; editing the file directly works too, and changes are picked up on the next turn.
+
 ## @file mentions
 
 Prefix a path with `@` in any prompt to attach its content (REPL and print mode alike):
@@ -256,13 +266,17 @@ Invalid `--image` paths (unsupported type, missing, unreadable, or oversized) ab
 
 Missing, binary, oversized (>100KB for text, >5MB for images), or sensitive files (`.env`, private keys) are skipped with a note. The chat history keeps your original `@path` text, so resumed sessions don't carry the injected bulk.
 
+## .starignore
+
+A `.starignore` file in the working directory hides paths from the agent: the `glob` and `grep` tools skip matching files (ignored directories are pruned entirely), and `@file` completion filters them too. Syntax mirrors `.gitignore` basics — one pattern per line, `#` comments, bare patterns match basenames (`*.log`), patterns with `/` match relative paths (`build/**`), a trailing `/` marks directory-only (`private/`). Negation (`!`) is not supported, and an explicitly requested file (e.g. `grep` with an exact `path`) is still read. Changes are picked up immediately.
+
 ## Built-in tools
 
-`read_file`, `write_file`, `edit_file`, `glob`, `grep`, `bash`, `web_fetch`, `web_search` (DuckDuckGo, no API key needed), `todo_read`, `todo_write`, `task_list`, `task_output`, `task_kill`, `subagent`, `skill` — each declares a permission level (`read` / `write` / `exec`) enforced by the permission gate. Hard safety rules (dangerous shell commands, paths outside the working directory, secret files like `.env` / private keys) are denied in `ask` / `auto` / `readonly` and cannot be overridden by allow-rules.
+`read_file`, `write_file`, `edit_file`, `glob`, `grep`, `bash`, `web_fetch`, `web_search` (DuckDuckGo, no API key needed), `todo_read`, `todo_write`, `task_list`, `task_output`, `task_kill`, `subagent`, `skill`, `remember` — each declares a permission level (`read` / `write` / `exec`) enforced by the permission gate. Hard safety rules (dangerous shell commands, paths outside the working directory, secret files like `.env` / private keys) are denied in `ask` / `auto` / `readonly` and cannot be overridden by allow-rules.
 
 The `subagent` tool (`exec` level, so it is hidden in plan mode and denied in readonly) spawns a child agent loop with the same built-in tools to handle a focused, self-contained subtask — research, exploration, or an isolated change — and returns the child's final report as the tool result. Subagents run one level deep (a subagent cannot spawn further subagents), share the parent's permission mode and confirmation prompt, and their conversation is not persisted to the session.
 
-Permission modes: `ask` (reads allowed, writes/exec ask) · `auto` (everything allowed except the hard-denied rules above) · `readonly` (read-only) · `yolo` (allow everything, never ask — **all safety checks disabled**, use at your own risk) · `plan` (read-only research with a plan-approval flow, see above — session-only). Switch at runtime with `/permission` (persisted to the config file), per session with `/plan` or `Shift+Tab`, or at startup with `--permission-mode`.
+Permission modes: `ask` (reads allowed, writes/exec ask) · `auto` (everything allowed except the hard-denied rules above) · `readonly` (read-only) · `yolo` (allow everything, never ask — **all safety checks disabled**, use at your own risk) · `plan` (read-only research with a plan-approval flow, see above — session-only). Switch at runtime with `/permission` (persisted to the config file), per session with `/plan` or `Shift+Tab`, or at startup with `--permission-mode`. On top of the modes, the `[permissions]` config block holds persistent `allow` and `deny` rule lists (same `bash(npm test *)` syntax); deny rules are evaluated right after the hard safety rules and beat both `auto` mode and allow-rules, while `yolo` bypasses everything.
 
 Every successful `write_file` / `edit_file` first snapshots the file's previous content (in-memory, last 50 writes per session); `/undo` restores the most recent snapshot, deleting the file if it didn't exist before.
 
@@ -274,7 +288,7 @@ Checkpoints are persisted under `~/.star-cli/sessions/<id>/checkpoints/` (an `in
 
 ## Sessions
 
-Sessions persist under `~/.star-cli/sessions/<id>/` (messages as JSONL + `meta.json`). List with `/resume` (only sessions started in the current directory, most recently active first, with message counts and relative times) or `/resume --all` (every directory, with each session's cwd shown), resume with `/resume <id>` or `star -r <id>` — both accept the short id shown in the list. `star -c` (`--continue`) jumps straight back into the most recently active session for the current directory, in the REPL and in print mode alike; when the directory has no sessions it says so and starts a fresh one. `-r` and `-c` are mutually exclusive, and a bare `star -r` prints the session list instead of erroring. Sessions are created lazily — opening the REPL and exiting without chatting leaves nothing on disk, and print mode (`-p`) doesn't create a session unless resuming with `-r` or `-c`. Token usage is accumulated in `meta.json`, so `/cost` reflects resumed history too. `/usage` is the global counterpart of `/cost` (which stays session-scoped): it aggregates every session's `meta.json` across all directories into a dashboard — grand totals, a per-day bar chart of the last 14 days with usage, and a per-model breakdown with a $ estimate for models that have pricing configured (models without pricing are listed but excluded from the total). Per-day numbers come from a `usageByDay` bucket map recorded from now on; usage recorded before that field existed only has grand totals and shows up as a single "earlier usage" line. `/new` abandons the in-memory conversation and attaches a fresh lazy session store (the old session stays on disk); deletion is a separate explicit action — `/clear-sessions` removes the sessions recorded for the current directory, `/clear-sessions --all` wipes every session directory (including ones with an unreadable `meta.json`), and both keep the live session; `star --clear-sessions [all]` does the same non-interactively and exits.
+Sessions persist under `~/.star-cli/sessions/<id>/` (messages as JSONL + `meta.json`). `/resume` with no argument opens an interactive picker of this directory's sessions (most recently active first, message counts, relative times, a preview of the first message, and a `current` marker on the live session; `/resume --all` covers every directory with each session's cwd shown), while `/resume <id>` and `star -r <id>` jump straight to one — both accept the short id shown in the list. `/fork` branches the live session: every message is copied into a new session titled `Fork of …` which becomes the active one, so you can explore a different direction while the original stays intact (checkpoints and rewind history are not carried over). `/search <query>` full-text-searches every stored session — message text plus tool-call arguments and results — and lists matching sessions with a snippet, ready for `/resume <id>`. `star -c` (`--continue`) jumps straight back into the most recently active session for the current directory, in the REPL and in print mode alike; when the directory has no sessions it says so and starts a fresh one. `-r` and `-c` are mutually exclusive, and a bare `star -r` prints the session list instead of erroring. Sessions are created lazily — opening the REPL and exiting without chatting leaves nothing on disk, and print mode (`-p`) doesn't create a session unless resuming with `-r` or `-c`. Token usage is accumulated in `meta.json`, so `/cost` reflects resumed history too. `/usage` is the global counterpart of `/cost` (which stays session-scoped): it aggregates every session's `meta.json` across all directories into a dashboard — grand totals, a per-day bar chart of the last 14 days with usage, and a per-model breakdown with a $ estimate for models that have pricing configured (models without pricing are listed but excluded from the total). Per-day numbers come from a `usageByDay` bucket map recorded from now on; usage recorded before that field existed only has grand totals and shows up as a single "earlier usage" line. `/new` abandons the in-memory conversation and attaches a fresh lazy session store (the old session stays on disk); deletion is a separate explicit action — `/clear-sessions` removes the sessions recorded for the current directory, `/clear-sessions --all` wipes every session directory (including ones with an unreadable `meta.json`), and both keep the live session; `star --clear-sessions [all]` does the same non-interactively and exits.
 
 After the first turn of a session (the first user message gets its first assistant reply), a lightweight background LLM request — same model, capped at 20 output tokens — summarizes the first user message into a short title (≤50 chars, matching the message's language) and stores it in `meta.json`, where the `/resume` list picks it up. Title generation is fire-and-forget: it never blocks the REPL or print-mode output, it runs only when the session has no title yet (resumed sessions keep their existing title; untitled older sessions get one after their next turn), and if the request fails the title simply stays empty — untitled sessions show as `(无标题)` in the list. An unfinished request is abandoned when the process exits. It applies wherever a session is attached, including print mode when resuming with `-r`/`-c`.