@hansjm10/volt-coding-agent 0.0.0-bootstrap.0 → 0.1.0

package/docs/sessions.md

@@ -0,0 +1,145 @@
+# Sessions
+
+Volt saves conversations as sessions so you can continue work, branch from earlier turns, and revisit previous paths.
+
+## Session Storage
+
+Sessions auto-save to `~/.volt/agent/sessions/`, organized by working directory. Each session is a JSONL file with a tree structure.
+
+```bash
+volt -c                  # Continue most recent session
+volt -r                  # Browse and select from past sessions
+volt --no-session        # Ephemeral mode; do not save
+volt --name "my task"    # Set session display name at startup
+volt --session <path|id> # Use a specific session file or partial session ID
+volt --fork <path|id>    # Fork a session file or partial session ID into a new session
+```
+
+Use `/session` in interactive mode to see the current session file, session ID, message count, tokens, and cost.
+
+For the JSONL file format and SessionManager API, see [Session Format](session-format.md).
+
+## Session Commands
+
+| Command | Description |
+|---------|-------------|
+| `/resume` | Browse and select previous sessions |
+| `/clear` | Start a new session |
+| `/name <name>` | Set the current session display name |
+| `/session` | Show session info |
+| `/tree` | Navigate the current session tree |
+| `/fork` | Create a new session from a previous user message |
+| `/clone` | Duplicate the current active branch into a new session |
+| `/compact [prompt]` | Summarize older context; see [Compaction](compaction.md) |
+| `/export [file]` | Export session to HTML |
+| `/share` | Upload as private GitHub gist with shareable HTML link |
+
+## Resuming and Deleting Sessions
+
+`/resume` opens an interactive session picker for the current project. `volt -r` opens the same picker at startup.
+
+In the picker you can:
+
+- search by typing
+- toggle path display with Ctrl+P
+- toggle sort mode with Ctrl+S
+- filter to named sessions with Ctrl+N
+- rename with Ctrl+R
+- delete with Ctrl+D, then confirm
+
+When available, volt uses the `trash` CLI for deletion instead of permanently removing files.
+
+## Naming Sessions
+
+Use `/name <name>` to set a human-readable session name:
+
+```text
+/name Refactor auth module
+```
+
+Set the name at startup with `--name` or `-n`:
+
+```bash
+volt --name "Refactor auth module"
+volt --name "CI audit" -p "Review this build failure"
+```
+
+Named sessions are easier to find in `/resume` and `volt -r`.
+
+## Branching with `/tree`
+
+Sessions are stored as trees. Every entry has an `id` and `parentId`, and the current position is the active leaf. `/tree` lets you jump to any previous point and continue from there without creating a new file.
+
+<p align="center"><img src="images/tree-view.png" alt="Tree View" width="600"></p>
+
+Example shape:
+
+```text
+├─ user: "Hello, can you help..."
+│  └─ assistant: "Of course! I can..."
+│     ├─ user: "Let's try approach A..."
+│     │  └─ assistant: "For approach A..."
+│     │     └─ user: "That worked..."  ← active
+│     └─ user: "Actually, approach B..."
+│        └─ assistant: "For approach B..."
+```
+
+### Tree Controls
+
+| Key | Action |
+|-----|--------|
+| ↑/↓ | Navigate visible entries |
+| ←/→ | Page up/down |
+| Ctrl+←/Ctrl+→ or Alt+←/Alt+→ | Fold/unfold or jump between branch segments |
+| Shift+L | Set or clear a label on the selected entry |
+| Shift+T | Toggle label timestamps |
+| Enter | Select entry |
+| Escape/Ctrl+C | Cancel |
+| Ctrl+O | Cycle filter mode |
+
+Filter modes are: default, no-tools, user-only, labeled-only, and all. Configure the default with `treeFilterMode` in [Settings](settings.md).
+
+### Selection Behavior
+
+Selecting a user or custom message:
+
+1. Moves the leaf to the selected message's parent.
+2. Places the selected message text in the editor.
+3. Lets you edit and resubmit, creating a new branch.
+
+Selecting an assistant, tool, compaction, or other non-user entry:
+
+1. Moves the leaf to that entry.
+2. Leaves the editor empty.
+3. Lets you continue from that point.
+
+Selecting the root user message resets the leaf to an empty conversation and places the original prompt in the editor.
+
+## `/tree`, `/fork`, and `/clone`
+
+| Feature | `/tree` | `/fork` | `/clone` |
+|---------|---------|---------|----------|
+| Output | Same session file | New session file | New session file |
+| View | Full tree | User-message selector | Current active branch |
+| Typical use | Explore alternatives in place | Start a new session from an earlier prompt | Duplicate current work before continuing |
+| Summary | Optional branch summary | None | None |
+
+Use `/tree` when you want to keep alternatives together. Use `/fork` or `/clone` when you want a separate session file.
+
+## Branch Summaries
+
+When `/tree` switches away from one branch to another, volt can summarize the abandoned branch and attach that summary at the new position. This preserves important context from the path you left without replaying the whole branch.
+
+When prompted, choose one of:
+
+1. no summary
+2. summarize with the default prompt
+3. summarize with custom focus instructions
+
+See [Compaction](compaction.md) for branch summarization internals and extension hooks.
+
+## Session Format
+
+Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, compactions, branch summaries, and extension entries.
+
+For parsers, extensions, SDK usage, and the full SessionManager API, see [Session Format](session-format.md).

package/docs/settings.md

@@ -0,0 +1,371 @@
+# Settings
+
+Volt uses JSON settings files with project settings overriding global settings.
+
+| Location | Scope |
+|----------|-------|
+| `~/.volt/agent/settings.json` | Global (all projects) |
+| `.volt/settings.json` | Project (current directory) |
+
+Edit directly or use `/settings` for common options.
+
+## Project Trust
+
+On interactive startup, volt asks before trusting a project folder that contains project-local settings, MCP server config, resources, or project `.agents/skills` and has no saved decision for the folder or a parent folder in `~/.volt/agent/trust.json`. Trusting a project allows volt to load `.volt/settings.json`, `.mcp.json`/`.volt/mcp.json`, and `.volt` resources, install missing project packages, and execute project extensions.
+
+Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore those project resources, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
+
+If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.volt/agent/settings.json`, or change it with `/settings`.
+
+`volt config` and package commands use the same project trust flow, except `volt update` never prompts. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them.
+
+Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.volt/agent/trust.json` only; the current session is not reloaded, so restart volt for changes to take effect.
+
+MCP server configuration is not stored in `settings.json`; use `~/.volt/agent/mcp.json` for user-local servers, shared `~/.config/mcp/mcp.json`, trusted project `.mcp.json`, or trusted project `.volt/mcp.json`. OAuth tokens for MCP HTTP/SSE servers are stored separately in `~/.volt/agent/mcp-auth.json`. See [MCP](mcp.md).
+
+## Profiles
+
+Profiles are named settings overlays for switching workflows. Select one at startup with `--profile <name>`, set `VOLT_PROFILE`, or set `defaultProfile` in settings. In interactive mode, use `/profile` to show the active profile, switch to another profile, or create an empty global profile and switch to it. When interactive mode exits, Volt remembers the active profile by saving it as `defaultProfile`. Profiles can override normal settings such as packages, extensions, skills, prompts, themes, model defaults, model cycling, thinking level, and UI preferences.
+
+Global and project profiles follow the normal settings precedence and trust model: global settings load first, the selected global profile overlays them, trusted project settings overlay that, and the selected trusted project profile overlays last. Without project trust, project profiles are ignored. Switching profiles with `/profile` reloads the current session's settings-backed resources so profile resource changes apply without restarting.
+
+```json
+{
+  "defaultProfile": "development",
+  "profiles": {
+    "development": {
+      "packages": ["npm:@me/dev-tools"],
+      "extensions": ["./extensions/dev.ts"],
+      "enabledModels": ["anthropic/*", "openai/*"]
+    },
+    "work": {
+      "packages": ["npm:@corp/work-tools"],
+      "defaultProvider": "github-copilot",
+      "enabledModels": ["github-copilot/*"]
+    }
+  }
+}
+```
+
+Profiles do not isolate auth or sessions yet. `sessionDir` and reserved profile `storage` settings are ignored for now so future auth/session profile support can be added without changing the profile shape.
+
+## All Settings
+
+### Profiles
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `defaultProfile` | string | - | Profile to apply when `--profile` and `VOLT_PROFILE` are not set; updated to the active profile when interactive mode exits |
+| `profiles` | object | `{}` | Named settings overlays keyed by profile name |
+
+### Model & Thinking
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `defaultProvider` | string | - | Default provider (e.g., `"anthropic"`, `"openai"`) |
+| `defaultModel` | string | - | Default model ID |
+| `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"` |
+| `reviewModel` | string | - | Model for `/review` (e.g. `"anthropic/claude-opus-4-5"`); falls back to the session model |
+| `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
+| `thinkingBudgets` | object | - | Custom token budgets per thinking level |
+
+#### thinkingBudgets
+
+```json
+{
+  "thinkingBudgets": {
+    "minimal": 1024,
+    "low": 4096,
+    "medium": 10240,
+    "high": 32768
+  }
+}
+```
+
+### UI & Display
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `theme` | string | `"dark"` | Theme name (`"dark"`, `"light"`, or custom) |
+| `quietStartup` | boolean | `false` | Hide startup header |
+| `defaultProjectTrust` | string | `"ask"` | Fallback project trust behavior: `"ask"`, `"always"`, or `"never"`. Global setting only |
+| `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
+| `enableInstallTelemetry` | boolean | `true` | Send an anonymous install/update version ping after first install or changelog-detected updates. This does not control update checks |
+| `enableAnalytics` | boolean | `false` | Opt-in analytics data sharing. Currently only asked for during the experimental first-time setup (`VOLT_EXPERIMENTAL=1`) |
+| `trackingId` | string | - | Analytics tracking identifier, generated when `enableAnalytics` is turned on |
+| `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
+| `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` |
+| `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) |
+| `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) |
+| `showHardwareCursor` | boolean | `false` | Show the terminal cursor while TUI positions it for IME support |
+
+### Telemetry and update checks
+
+`enableInstallTelemetry` controls install/update telemetry and provider attribution headers. Hosted install/update pings are disabled unless `VOLT_REPORT_INSTALL_URL` is set. Hosted version checks are disabled unless `VOLT_LATEST_VERSION_URL` is set.
+
+Set `VOLT_SKIP_VERSION_CHECK=1` to disable the Volt version update check. Use `--offline` or `VOLT_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry.
+
+### Network
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `httpProxy` | string | - | HTTP proxy URL applied as `HTTP_PROXY` and `HTTPS_PROXY`. Global setting only. |
+
+```json
+{
+  "httpProxy": "http://127.0.0.1:7890"
+}
+```
+
+### Warnings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `warnings.anthropicExtraUsage` | boolean | `true` | Show a warning when Anthropic subscription auth may use paid extra usage |
+
+```json
+{
+  "warnings": {
+    "anthropicExtraUsage": false
+  }
+}
+```
+
+### Compaction
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `compaction.enabled` | boolean | `true` | Enable auto-compaction |
+| `compaction.reserveTokens` | number | `16384` | Tokens reserved for LLM response |
+| `compaction.keepRecentTokens` | number | `20000` | Recent tokens to keep (not summarized) |
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000
+  }
+}
+```
+
+### Branch Summary
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `branchSummary.reserveTokens` | number | `16384` | Tokens reserved for branch summarization |
+| `branchSummary.skipPrompt` | boolean | `false` | Skip "Summarize branch?" prompt on `/tree` navigation (defaults to no summary) |
+
+### Retry
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `retry.enabled` | boolean | `true` | Enable automatic agent-level retry on transient errors |
+| `retry.maxRetries` | number | `3` | Maximum agent-level retry attempts |
+| `retry.baseDelayMs` | number | `2000` | Base delay for agent-level exponential backoff (2s, 4s, 8s) |
+| `retry.provider.timeoutMs` | number | SDK default | Provider/SDK request timeout in milliseconds |
+| `retry.provider.maxRetries` | number | `0` | Provider/SDK retry attempts |
+| `retry.provider.maxRetryDelayMs` | number | `60000` | Max server-requested delay before failing (60s) |
+
+When a provider requests a retry delay longer than `retry.provider.maxRetryDelayMs` (e.g., Google's "quota will reset after 5h"), the request fails immediately with an informative error instead of waiting silently. Set to `0` to disable the cap.
+
+Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explicitly needed. Setting it above `0` can make SDK/provider retries handle out-of-usage-limit errors before Volt sees them, which may block the agent until the provider quota resets in some circumstances.
+
+```json
+{
+  "retry": {
+    "enabled": true,
+    "maxRetries": 3,
+    "baseDelayMs": 2000,
+    "provider": {
+      "timeoutMs": 3600000,
+      "maxRetries": 0,
+      "maxRetryDelayMs": 60000
+    }
+  }
+}
+```
+
+### Message Delivery
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `steeringMode` | string | `"one-at-a-time"` | How steering messages are sent: `"all"` or `"one-at-a-time"` |
+| `followUpMode` | string | `"one-at-a-time"` | How follow-up messages are sent: `"all"` or `"one-at-a-time"` |
+| `transport` | string | `"auto"` | Preferred transport for providers that support multiple transports: `"sse"`, `"websocket"`, `"websocket-cached"`, or `"auto"` |
+| `httpIdleTimeoutMs` | number | `300000` | HTTP header/body idle timeout in milliseconds, also used by providers with explicit stream idle timeouts. Set to `0` to disable. |
+| `websocketConnectTimeoutMs` | number | `15000` | WebSocket connect/open handshake timeout in milliseconds for providers that support WebSocket transports. Set to `0` to disable. |
+
+### Terminal & Images
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `terminal.showImages` | boolean | `true` | Show images in terminal (if supported) |
+| `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells |
+| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker) |
+| `terminal.showTerminalProgress` | boolean | `false` | Show OSC 9;4 indeterminate progress in supporting terminal tab bars |
+| `terminal.turnDoneAlert` | string | `"off"` | Alert when Volt finishes a response: `"off"`, `"bell"`, or `"notify"`. `"bell"` writes the terminal BEL sequence, which most terminals and tmux handle as an audible/visual alert according to terminal settings. `"notify"` posts a desktop notification on terminals that support one (kitty via OSC 99; WezTerm, Ghostty, foot, and urxvt via OSC 777; iTerm2 and ConEmu via OSC 9) and falls back to the BEL sequence everywhere else (Windows Terminal, Apple Terminal, VS Code, tmux/screen, unknown terminals). On terminals that support focus reporting (DECSET 1004), the alert is suppressed while the terminal window is focused; terminals without focus reporting always alert |
+| `images.autoResize` | boolean | `true` | Resize images to 2000x2000 max |
+| `images.blockImages` | boolean | `false` | Block all images from being sent to LLM |
+
+### Shell
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `shellPath` | string | - | Custom shell path (e.g., for Cygwin on Windows) |
+| `shellCommandPrefix` | string | - | Prefix for every bash command (e.g., `"shopt -s expand_aliases"`) |
+| `npmCommand` | string[] | - | Command argv used for npm package lookup/install operations (e.g., `["mise", "exec", "node@20", "--", "npm"]`) |
+
+```json
+{
+  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
+}
+```
+
+`npmCommand` is used for all npm package-manager operations, including installs, uninstalls, and dependency installs inside git packages. User-scoped npm packages install under `~/.volt/agent/npm/`; project-scoped npm packages install under `.volt/npm/`. Use argv-style entries exactly as the process should be launched. When `npmCommand` is configured, git package dependency installs use plain `install` to avoid npm-specific flags in wrappers or alternate package managers.
+
+### Sessions
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `sessionDir` | string | - | Directory where session files are stored. Accepts absolute or relative paths, plus `~`. |
+
+```json
+{ "sessionDir": ".volt/sessions" }
+```
+
+When multiple sources specify a session directory, precedence is `--session-dir`, `VOLT_CODING_AGENT_SESSION_DIR`, then `sessionDir` in settings.json.
+
+### Model Cycling
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `enabledModels` | string[] | - | Model patterns for Ctrl+P cycling (same format as `--models` CLI flag) |
+
+```json
+{
+  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
+}
+```
+
+### Markdown
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `markdown.codeBlockIndent` | string | `"  "` | Indentation for code blocks |
+
+### LSP Diagnostics
+
+See [LSP Diagnostics](lsp.md) for the full reference, including built-in server defaults.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `lsp.enabled` | boolean | `true` | Run language servers and append diagnostics to `edit`/`write` results; set `false` to disable (`--lsp` force-enables per run) |
+| `lsp.servers` | object | built-ins | Server definitions keyed by name, merged over the built-in defaults |
+| `lsp.settleMs` | number | `1500` | How long to wait for published diagnostics after a change |
+| `lsp.firstSettleMs` | number | `10000` | Wait window for the first diagnostics from a freshly started server |
+| `lsp.idleShutdownMs` | number | `600000` | Shut down servers idle for this long; `0` disables |
+| `lsp.traceFile` | string | | Append LSP protocol traffic and server stderr to this file |
+| `lsp.maxDiagnostics` | number | `20` | Maximum diagnostics reported per tool call |
+| `lsp.severity` | string | `"error"` | Minimum severity to report: `error`, `warning`, `information`, or `hint` |
+
+### Remote Access (daemon)
+
+Settings for the background daemon and live shared sessions; see [Background daemon](daemon.md).
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `remote.background` | boolean | `false` | Interactive Volt starts the daemon automatically. Supported TUIs connect to an already-running daemon regardless, auto-register their workspace, and acquire a conversation lease. |
+| `remote.detachedRuntimeTtlMs` | number | `1800000` | How long the daemon retains an idle detached headless runtime (30 minutes) |
+| `remote.allowTools` | string[] | - | Additional tool ceiling for daemon-owned headless runtimes, intersected with the paired client's persisted grant and any workspace ceiling; `[]` denies all tools. TUI-owned conversations use the TUI session's full tool set. |
+
+### Resources
+
+These settings define where to load extensions, skills, prompts, and themes from.
+
+Paths in `~/.volt/agent/settings.json` resolve relative to `~/.volt/agent`. Paths in `.volt/settings.json` resolve relative to `.volt`. Absolute paths and `~` are supported.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `packages` | array | `[]` | npm/git packages to load resources from |
+| `extensions` | string[] | `[]` | Local extension file paths or directories |
+| `skills` | string[] | `[]` | Local skill file paths or directories |
+| `prompts` | string[] | `[]` | Local prompt template paths or directories |
+| `themes` | string[] | `[]` | Local theme file paths or directories |
+| `enableSkillCommands` | boolean | `true` | Register skills as `/skill:name` commands |
+
+Arrays support glob patterns and exclusions. Use `!pattern` to exclude. Use `+path` to force-include an exact path and `-path` to force-exclude an exact path.
+
+#### packages
+
+String form loads all resources from a package:
+
+```json
+{
+  "packages": ["volt-skills", "@org/my-extension"]
+}
+```
+
+Object form filters which resources to load:
+
+```json
+{
+  "packages": [
+    {
+      "source": "volt-skills",
+      "skills": ["brave-search", "transcribe"],
+      "extensions": []
+    }
+  ]
+}
+```
+
+See [packages.md](packages.md) for package management details.
+
+## Example
+
+```json
+{
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-20250514",
+  "defaultThinkingLevel": "medium",
+  "theme": "dark",
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000
+  },
+  "retry": {
+    "enabled": true,
+    "maxRetries": 3
+  },
+  "enabledModels": ["claude-*", "gpt-4o"],
+  "warnings": {
+    "anthropicExtraUsage": true
+  },
+  "packages": ["volt-skills"]
+}
+```
+
+## Project Overrides
+
+Project settings (`.volt/settings.json`) override global settings. Nested objects are merged:
+
+```json
+// ~/.volt/agent/settings.json (global)
+{
+  "theme": "dark",
+  "compaction": { "enabled": true, "reserveTokens": 16384 }
+}
+
+// .volt/settings.json (project)
+{
+  "compaction": { "reserveTokens": 8192 }
+}
+
+// Result
+{
+  "theme": "dark",
+  "compaction": { "enabled": true, "reserveTokens": 8192 }
+}
+```

package/docs/shell-aliases.md

@@ -0,0 +1,13 @@
+# Shell Aliases
+
+Volt runs bash in non-interactive mode (`bash -c`), which doesn't expand aliases by default.
+
+To enable your shell aliases, add to `~/.volt/agent/settings.json`:
+
+```json
+{
+  "shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\""
+}
+```
+
+Adjust the path (`~/.zshrc`, `~/.bashrc`, etc.) to match your shell config.