wispy-cli 2.7.15 → 2.7.17

package/README.md

@@ -1,486 +1,804 @@
-# Wispy CLI
+# wispy-cli
 
-Wispy CLI is a terminal-first AI workspace assistant for operators who want one place to chat, delegate, automate, audit, remember, and hand work across local and remote sessions.
+**AI workspace assistant — chat, automate, and orchestrate from the terminal.**
 
-Version `2.7.4` centers the product around an interactive workflow: onboarding, setup, and operator-facing commands guide you through menus instead of dropping you into brittle flag-heavy flows. The chat stack combines a REPL, a six-view TUI workspace, long-term memory, sub-agent orchestration, MCP, multi-channel messaging, scheduling, and a trust model built for real execution.
+wispy-cli puts a trustworthy AI co-pilot in your shell. It handles multi-turn conversations, tool execution with approval controls, session persistence, sub-agent orchestration, code review, browser automation, and more — all from a single `wispy` command.
 
-## Highlights
+---
 
-| Area | What ships in v2.7.4 |
-| --- | --- |
-| Model access | 29 AI providers across hosted, aggregator, OAuth, and local/self-hosted routes, including Google, Anthropic, OpenAI, Groq, DeepSeek, Ollama, OpenRouter, Mistral, Cohere, Perplexity, Together, Fireworks, Replicate, Anyscale, and GitHub Copilot |
-| Auth | API key flows plus OAuth-based auth, including GitHub Copilot support introduced in `v2.6.0` |
-| Interaction | Interactive command flows since `v2.7.0`; no-arg command entry routes into menus instead of dead-ending |
-| Terminal UX | REPL with autocomplete and inline preview hints, plus shell completion auto-installed during setup |
-| TUI | Multi-panel workspace OS with 6 views: `chat`, `overview`, `agents`, `memory`, `audit`, `settings` |
-| Trust | `careful`, `balanced`, `yolo`, dry-run previews, receipts, approval prompts, permissions, audit trail, replay |
-| Continuity | `where`, `handoff`, `sync` for local/remote awareness and state transfer |
-| Memory | `remember`, `recall`, `forget`, `memories` plus persistent memory files |
-| Skills | `teach`, `improve`, skill loading, reusable learned workflows |
-| Orchestration | Agents, sub-agents, pipeline-style delegation, MCP integration, 18+ built-in tools |
-| Channels | Telegram, Discord, Slack, WhatsApp, Signal, Email |
-| Scheduling | Cron-based task scheduling with persisted jobs and history |
-| Quality | Test suite passing: `91/91` |
+## Table of Contents
 
-## Installation
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+- [Global Flags](#global-flags)
+- [Feature Highlights](#feature-highlights)
+- [Providers](#providers)
+- [Configuration](#configuration)
+- [Agent System](#agent-system)
+- [Trust & Security](#trust--security)
+- [Memory System](#memory-system)
+- [Sub-Agent Orchestration](#sub-agent-orchestration)
+- [Browser Integration](#browser-integration)
+- [Text-to-Speech](#text-to-speech)
+- [Code Review](#code-review)
+- [JSONL Event Stream](#jsonl-event-stream)
+- [Sessions](#sessions)
+- [Architecture](#architecture)
+- [Development](#development)
+- [Credits](#credits)
 
-### Requirements
-
-| Requirement | Version |
-| --- | --- |
-| Node.js | `>= 18` |
-| Package manager | `npm` |
+---
 
-### Install globally
+## Quick Start
 
 ```bash
+# Install
 npm install -g wispy-cli
+
+# First-time setup (choose provider, set API key)
+wispy setup
+
+# Start chatting
+wispy
 ```
 
-### Run
+One-shot (non-interactive):
 
 ```bash
-wispy
+wispy "summarize the last 10 commits"
+wispy exec "list all TODO comments in src/" --json   # JSONL output
 ```
 
-On first run, Wispy launches guided setup, helps configure a provider, and installs shell completion automatically for supported shells.
+---
+
+## Commands
+
+### Core
+
+| Command | Description |
+|---------|-------------|
+| `wispy` | Start interactive REPL |
+| `wispy <message>` | One-shot chat |
+| `wispy exec <message>` | Non-interactive one-shot (CI/pipeline friendly) |
+| `wispy setup` | Run first-time setup wizard |
+
+### Configuration
+
+| Command | Description |
+|---------|-------------|
+| `wispy config show` | Print full config as JSON |
+| `wispy config path` | Print path to config file |
+| `wispy config get <key>` | Get a config value |
+| `wispy config set <key> <value>` | Set a config value |
+| `wispy config delete <key>` | Delete a config key |
+| `wispy config reset` | Reset config to defaults (with confirmation) |
+| `wispy config edit` | Open config in `$EDITOR` |
+
+### System
+
+| Command | Description |
+|---------|-------------|
+| `wispy doctor` | Check system health (provider, API key, dirs) |
+| `wispy model` | Interactive model/provider picker |
+| `wispy model list` | List all available models by provider |
+| `wispy model <name>` | Set model directly (e.g. `wispy model gpt-4o`) |
+| `wispy where` | Show current mode, provider, workstream, and memory stats |
+
+### Feature Flags
+
+| Command | Description |
+|---------|-------------|
+| `wispy features list` | List all feature flags with status |
+| `wispy features enable <name>` | Enable a feature flag |
+| `wispy features disable <name>` | Disable a feature flag |
+
+### Agents
+
+| Command | Description |
+|---------|-------------|
+| `wispy agents` | List available agents (built-in + custom) |
+| `wispy agents list` | Alias for `wispy agents` |
+
+### Sessions
+
+| Command | Description |
+|---------|-------------|
+| `wispy sessions` | List sessions (interactive picker) |
+| `wispy sessions --all` | List sessions from all workstreams |
+| `wispy sessions --no-interactive` | Non-interactive listing |
+| `wispy resume [session-id]` | Resume a previous session |
+| `wispy resume --last` | Resume the most recent session |
+| `wispy fork [session-id]` | Fork a session (branch from history) |
+| `wispy fork --last` | Fork the most recent session |
+
+### Code Review
+
+| Command | Description |
+|---------|-------------|
+| `wispy review` | Review uncommitted changes (staged + unstaged) |
+| `wispy review --base <branch>` | Review changes against a base branch |
+| `wispy review --commit <sha>` | Review a specific commit |
+| `wispy review --json` | Output review as structured JSON |
+| `wispy review --title <title>` | Add context title to review |
+
+### Secrets
+
+| Command | Description |
+|---------|-------------|
+| `wispy secrets list` | List stored secret keys |
+| `wispy secrets set <key> <value>` | Store an encrypted secret |
+| `wispy secrets get <key>` | Retrieve a secret (masked) |
+| `wispy secrets get <key> --reveal` | Show the actual value |
+| `wispy secrets delete <key>` | Delete a secret |
+
+### Browser
+
+| Command | Description |
+|---------|-------------|
+| `wispy browser` | Show browser bridge status |
+| `wispy browser status` | Alias for `wispy browser` |
+| `wispy browser tabs [browser]` | List open tabs |
+| `wispy browser attach [browser]` | Attach to a running browser |
+| `wispy browser navigate <url>` | Navigate to URL |
+| `wispy browser screenshot [file]` | Take a screenshot |
+| `wispy browser doctor` | Full browser bridge diagnostics |
+
+### Text-to-Speech
+
+| Command | Description |
+|---------|-------------|
+| `wispy tts "<text>"` | Speak text (OpenAI TTS or macOS `say`) |
+| `wispy tts "<text>" --voice <name>` | Use a specific voice |
+| `wispy tts "<text>" --provider openai\|macos` | Force a TTS provider |
+| `wispy tts "<text>" --play` | Play audio immediately (macOS) |
+
+### Trust & Security
+
+| Command | Description |
+|---------|-------------|
+| `wispy trust` | Interactive trust settings (level, audit log) |
+| `wispy trust level` | Show/set security level |
+| `wispy trust log` | View approval audit log |
+
+### Continuity
+
+| Command | Description |
+|---------|-------------|
+| `wispy where` | Show current mode, workstream, provider |
+| `wispy handoff cloud` | Push local context to cloud |
+| `wispy handoff local` | Pull remote context to local |
 
-## Quick Start
+### Skills
+
+| Command | Description |
+|---------|-------------|
+| `wispy skill list` | List learned skills |
+| `wispy skill run <name>` | Run a skill |
+| `wispy teach <name>` | Create a skill from conversation |
+| `wispy improve <name>` | Improve an existing skill |
+
+### Server & TUI
+
+| Command | Description |
+|---------|-------------|
+| `wispy server start` | Start HTTP/WebSocket server |
+| `wispy server stop` | Stop server |
+| `wispy server status` | Show server status |
+| `wispy tui` | Launch full-screen terminal UI |
+| `wispy overview` | Director view of all workstreams |
+
+### Cost
+
+| Command | Description |
+|---------|-------------|
+| `wispy cost` | Show API spending report (session + all-time) |
+| `wispy budget` | Alias for `wispy cost` |
+
+---
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `-w, --workstream <name>` | Set active workstream |
+| `-p, --profile <name>` | Use a named config profile |
+| `-i, --image <path>` | Attach image (can repeat for multiple) |
+| `--session <id>` | Resume an existing session |
+| `--name <name>` | Give this session a display name |
+| `--model <name>` | Override AI model for this run |
+| `--provider <name>` | Override AI provider for this run |
+| `--personality <name>` | Set personality (`pragmatic`, `concise`, `explanatory`, `friendly`, `strict`) |
+| `--agent <name>` | Use a named agent (`reviewer`, `planner`, `explorer`, or custom) |
+| `--effort <level>` | Effort level: `low`, `medium`, `high`, `max` (default: `medium`) |
+| `--system-prompt <text>` | Replace default system prompt entirely |
+| `--append-system-prompt <text>` | Append text to the default system prompt |
+| `--max-budget-usd <amount>` | Session budget cap (e.g. `5.00`) |
+| `--allowedTools <patterns>` | Only allow specified tools (e.g. `"read_file Bash(git:*)"`) |
+| `--disallowedTools <patterns>` | Block specified tools (e.g. `"write_file delete_file"`) |
+| `--json` | Output JSONL events (for `exec` command, CI use) |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+---
+
+## Feature Highlights
+
+### Smart Routing
+
+Automatically routes tasks to the most suitable model based on task type. Complex reasoning goes to capable models; quick lookups use fast models.
+
+Enable: `wispy features enable smart_routing`
+
+### Task Decomposition
+
+Splits complex tasks into parallel subtasks and executes them concurrently, then merges results. Dramatically faster for multi-file operations.
+
+Enable: `wispy features enable task_decomposition`
+
+### Context Compaction
+
+Automatically summarizes older conversation history when approaching token limits, keeping context fresh without losing important information.
+
+Enable: `wispy features enable context_compaction`
+
+### Loop Detection
+
+Detects when the AI is stuck in a repetitive tool-call loop and breaks out gracefully with a summary.
+
+Enable: `wispy features enable loop_detection`
+
+### Browser Integration
+
+Control a real browser via `local-browser-bridge`. Navigate pages, take screenshots, list tabs, extract content.
 
-### Start the main REPL
+Enable: `wispy features enable browser_integration`
+
+Requires: `npx local-browser-bridge serve`
+
+### Auto Memory
+
+Automatically extracts facts, decisions, and preferences from conversations and saves them to the memory store for future sessions.
+
+Enable: `wispy features enable auto_memory`
+
+### Multi-Agent Orchestration
+
+Spawn concurrent sub-agents for parallel execution. Each agent runs in an isolated worker thread with its own tool access.
+
+Enable: `wispy features enable multi_agent`
+
+### TTS
+
+Automatic text-to-speech output. Supports OpenAI TTS (multiple voices) and macOS `say` as fallback.
+
+Enable: `wispy features enable tts`
+
+---
+
+## Providers
+
+wispy-cli supports 27 AI providers out of the box:
+
+| Provider | Key | Notes |
+|----------|-----|-------|
+| Google AI | `google` | Gemini 2.0/2.5 series |
+| Anthropic | `anthropic` | Claude 3.x/4.x series |
+| OpenAI | `openai` | GPT-4o, o1, o3 series |
+| xAI | `xai` | Grok models |
+| Mistral | `mistral` | Mistral + Codestral |
+| Together AI | `together` | Open-source model hosting |
+| NVIDIA | `nvidia` | NVIDIA NIM |
+| Groq | `groq` | Ultra-fast inference |
+| DeepSeek | `deepseek` | DeepSeek-V3/R1 |
+| Chutes | `chutes` | Chutes API |
+| OpenRouter | `openrouter` | 200+ models via one key |
+| Vercel AI SDK | `vercelai` | Vercel AI gateway |
+| Kimi | `kimi` | Moonshot AI |
+| MiniMax | `minimax` | MiniMax models |
+| Venice | `venice` | Privacy-focused |
+| Hugging Face | `huggingface` | HF Inference API |
+| Cloudflare | `cloudflare` | Workers AI |
+| VolcEngine | `volcengine` | ByteDance cloud |
+| BytePlus | `byteplus` | BytePlus models |
+| ZAI | `zai` | ZAI models |
+| DashScope | `dashscope` | Alibaba Cloud |
+| Xiaomi | `xiaomi` | Xiaomi models |
+| GitHub Copilot | `github-copilot` | Copilot models |
+| Ollama | `ollama` | Local models (no key) |
+| vLLM | `vllm` | Self-hosted vLLM |
+| SGLang | `sglang` | Self-hosted SGLang |
+| LiteLLM | `litellm` | LiteLLM proxy |
+
+Set via `wispy setup`, env vars (`GOOGLE_API_KEY`, `ANTHROPIC_API_KEY`, etc.), or `~/.wispy/config.json`.
+
+---
+
+## Configuration
+
+### Global config: `~/.wispy/config.json`
+
+```json
+{
+  "provider": "google",
+  "model": "gemini-2.5-flash",
+  "workstream": "default",
+  "personality": "pragmatic",
+  "securityLevel": "balanced",
+  "locale": "en",
+  "memory": {
+    "enabled": true,
+    "autoExtract": false
+  }
+}
+```
+
+### Profiles
+
+Named config sets for switching between environments:
 
 ```bash
-wispy
+wispy config set profiles.work.provider anthropic
+wispy config set profiles.work.model claude-3-5-sonnet-20241022
+wispy -p work "review this architecture"
+```
+
+### Per-project settings: `.wispy/settings.json`
+
+wispy walks up from `cwd` to find a project settings file:
+
+```json
+{
+  "personality": "strict",
+  "model": "claude-3-5-sonnet-20241022",
+  "allowedTools": ["read_file", "list_directory", "run_command"],
+  "agents": {
+    "custom-reviewer": {
+      "description": "Security-focused code reviewer",
+      "systemPrompt": "You are a security expert. Focus on vulnerabilities."
+    }
+  }
+}
 ```
 
-### Send a one-shot message
+### MCP servers: `~/.wispy/mcp.json`
+
+Configure Model Context Protocol servers:
+
+```json
+{
+  "servers": [
+    {
+      "name": "filesystem",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
+    }
+  ]
+}
+```
+
+---
+
+## Agent System
+
+### Built-in Agents
+
+| Agent | Description |
+|-------|-------------|
+| `default` | General-purpose assistant |
+| `reviewer` | Code reviewer — bugs, security, performance, best practices |
+| `planner` | Project planner — breaks tasks into concrete steps |
+| `explorer` | Codebase explorer — navigates files, understands architecture |
 
 ```bash
-wispy "Summarize the current repository and suggest next steps."
+wispy --agent reviewer "check auth.mjs for security issues"
+wispy --agent planner "build a REST API with authentication"
+```
+
+### Custom Agents
+
+Define custom agents in `~/.wispy/config.json` or `.wispy/settings.json`:
+
+```json
+{
+  "agents": {
+    "devops": {
+      "description": "Infrastructure and deployment specialist",
+      "systemPrompt": "You are a DevOps engineer. Focus on reliability and automation.",
+      "personality": "pragmatic",
+      "allowedTools": ["run_command", "read_file"]
+    }
+  }
+}
 ```
 
-### Open a specific workstream
+Use with: `wispy --agent devops "set up CI/CD pipeline"`
+
+---
+
+## Trust & Security
+
+### Security Levels
+
+| Level | Behavior |
+|-------|----------|
+| `careful` | Approve all file writes, all commands |
+| `balanced` | Approve dangerous ops, notify writes (default) |
+| `yolo` | Auto-approve everything (use with caution) |
 
 ```bash
-wispy -w infra
+wispy trust                  # Interactive settings
+wispy config set securityLevel careful
 ```
 
-### Launch the full terminal UI
+### Tool Permissions
+
+Control which tools the AI can use per-session:
 
 ```bash
-wispy-tui
+# Allow only read tools
+wispy --allowedTools "read_file list_directory" "explain this codebase"
+
+# Block destructive tools
+wispy --disallowedTools "delete_file run_command" "refactor auth module"
+
+# Bash command patterns
+wispy --allowedTools "read_file Bash(git:*)" "show git history"
 ```
 
-### Check current execution context
+### Budget Cap
+
+Prevent runaway API spending:
 
 ```bash
-wispy where
+wispy --max-budget-usd 2.00 "analyze all 500 files in src/"
 ```
 
-### Inspect configuration
+### Audit Log
+
+All tool approvals and executions are logged. View with:
 
 ```bash
-wispy config show
-wispy config get provider
-wispy config set provider openai
-wispy config delete apiKey
-wispy config reset
-wispy config path
-wispy config edit
+wispy trust log
 ```
 
-## Provider Support
+### Loop Detection
 
-Wispy v2.7.4 is positioned as a multi-provider workspace client with support spanning hosted APIs, local runtimes, aggregators, and OAuth-backed access.
+Detects and breaks repetitive tool-call loops automatically. Configure sensitivity via feature flags.
 
-| Category | Examples |
-| --- | --- |
-| Hosted frontier APIs | Google, Anthropic, OpenAI, xAI, Mistral, Cohere, Perplexity |
-| Fast and cost-focused | Groq, DeepSeek, Together, Fireworks, Replicate, Anyscale |
-| Aggregators and gateways | OpenRouter, Vercel AI Gateway |
-| Regional and specialist providers | Kimi, MiniMax, Z.AI/GLM, DashScope, Volcengine, BytePlus, Xiaomi |
-| Local and self-hosted | Ollama, vLLM, SGLang, LiteLLM |
-| OAuth-backed access | GitHub Copilot |
+---
 
-### Authentication
+## Memory System
 
-| Mode | Notes |
-| --- | --- |
-| API keys | Standard provider key flow |
-| OAuth | Device flow support, including GitHub Copilot |
-| Local runtimes | Host/base URL driven for local inference stacks |
+Wispy stores persistent memory in `~/.wispy/memory/`. Memory is plain Markdown files, organized by topic.
 
-Examples:
+### In-session commands
 
-```bash
-export GOOGLE_AI_KEY=...
-wispy
 ```
-
-```bash
-wispy auth github-copilot
-wispy
+/memory                   Show memory summary
+/remember <fact>          Save a fact to memory
+/forget <topic>           Delete a memory topic
+/memory search <query>    Search memory
 ```
 
+### Auto-memory
+
+When `auto_memory` feature is enabled, wispy automatically extracts facts from conversations:
+
 ```bash
-export OLLAMA_HOST=http://localhost:11434
-wispy
+wispy features enable auto_memory
 ```
 
-## Interfaces
+---
+
+## Sub-Agent Orchestration
 
-### REPL
+wispy can spawn parallel sub-agents for complex multi-step tasks. Each agent runs in an isolated worker thread.
 
-The default `wispy` interface is a conversational REPL with:
+```bash
+# Example: analyze entire codebase in parallel
+wispy "analyze all modules in src/ in parallel and give me a security report"
+```
 
-- slash commands
-- command autocomplete
-- inline preview hints
-- one-shot and persistent workstream usage
-- token and cost visibility
+Sub-agents share the same tool registry but have isolated conversation state. Results are merged and returned to the orchestrating agent.
 
-Examples:
+Configure with `multi_agent` feature flag:
 
 ```bash
-wispy
-wispy -w product
-wispy "Search this repo for sync-related code paths."
+wispy features enable multi_agent
 ```
 
-### TUI Workspace OS
+---
+
+## Browser Integration
 
-`wispy-tui` is a multi-panel terminal workspace with six built-in views.
+Control a running browser via [local-browser-bridge](https://www.npmjs.com/package/local-browser-bridge):
+
+```bash
+# Start the bridge (in another terminal)
+npx local-browser-bridge serve
 
-| View | Purpose |
-| --- | --- |
-| `chat` | Main conversation and tool execution surface |
-| `overview` | Cross-workstream status and recent activity |
-| `agents` | Running and recent agent/sub-agent activity |
-| `memory` | Search and inspect persistent memories |
-| `audit` | Execution timeline, approvals, and receipts |
-| `settings` | Model, provider, and runtime status surface |
+# Then use wispy browser commands
+wispy browser tabs
+wispy browser navigate https://example.com
+wispy browser screenshot output.png
 
-## Trust and Execution Model
+# Or ask wispy to use the browser in chat
+wispy "go to github.com and tell me what's trending today"
+```
 
-Wispy is built around trustworthy execution rather than blind automation.
+Enable browser feature: `wispy features enable browser_integration`
 
-| Capability | Description |
-| --- | --- |
-| Trust modes | `careful`, `balanced`, `yolo` |
-| Dry-run | Preview actions before execution |
-| Receipts | Inspect recent execution details |
-| Approval prompts | Human-in-the-loop confirmation for sensitive actions |
-| Audit trail | Persisted audit log and replayable session history |
-| Permissions | Per-tool policy visibility and overrides |
+---
 
-Examples:
+## Text-to-Speech
 
 ```bash
-wispy trust
-wispy trust level careful
-wispy trust log --today
-wispy trust receipt <session-id>
-wispy trust replay <session-id>
+# Speak with auto-detected provider (OpenAI > macOS say)
+wispy tts "Hello, I am Wispy"
+
+# Use OpenAI with a specific voice
+wispy tts "Welcome back" --provider openai --voice nova --play
+
+# Use macOS say
+wispy tts "Build complete" --provider macos --play
 ```
 
-## Continuity
+Voices (OpenAI): `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`
 
-Wispy keeps workspace state portable across local and remote environments.
+Enable TTS in responses: `wispy features enable tts`
 
-| Command | Purpose |
-| --- | --- |
-| `where` | Show current mode, provider, workstream, sync, memory, and session context |
-| `handoff` | Push or pull state and generate a handoff summary |
-| `sync` | Sync sessions, memory, workstreams, cron metadata, and permissions |
+---
 
-Examples:
+## Code Review
 
 ```bash
-wispy where
-wispy handoff cloud
-wispy handoff local
-wispy sync
-```
+# Review all uncommitted changes
+wispy review
 
-## Memory, Skills, and Agents
+# Review against a branch
+wispy review --base main
 
-### Memory
+# Review a specific commit
+wispy review --commit abc1234
 
-Wispy stores long-term memory under `~/.wispy/memory/` and exposes both natural-language and command-driven memory operations.
+# Get structured JSON output (for CI integration)
+wispy review --json > review.json
+```
+
+Review output format:
+
+```
+## Summary
+[Brief summary of changes]
 
-| Command | Purpose |
-| --- | --- |
-| `remember` | Save something important |
-| `recall` | Search memories |
-| `memories` | List saved memories |
-| `forget` | Remove a memory |
+## Issues Found
+### Critical / Warnings / Info
+[Categorized issues]
 
-Examples:
+## File Comments
+[Line-level comments]
 
-```text
-/remember The staging server runs on port 8090.
-/recall staging server
-/memories
-/forget old-note
+## Assessment
+Verdict: approve | request-changes | comment
 ```
 
-### Skills
+---
 
-Skills turn successful workflows into reusable commands.
+## JSONL Event Stream
 
-| Command | Purpose |
-| --- | --- |
-| `skills` | List learned skills |
-| `teach` | Create a skill from recent conversation context |
-| `improve` | Refine an existing skill |
+Use `wispy exec --json` for machine-readable output in CI/CD pipelines:
 
-Examples:
+```bash
+wispy exec "analyze package.json for security issues" --json
+```
+
+Each line is a JSON event:
+
+```jsonl
+{"type":"start","session":"abc123","timestamp":"2026-04-04T..."}
+{"type":"chunk","content":"Analyzing..."}
+{"type":"tool_call","tool":"read_file","args":{"path":"package.json"}}
+{"type":"tool_result","tool":"read_file","result":"..."}
+{"type":"content","content":"Here are the security issues..."}
+{"type":"done","tokens":{"input":1250,"output":380},"duration_ms":2340}
+```
+
+Parse with `jq`:
 
 ```bash
-wispy skill
-wispy teach release-checklist
-wispy improve release-checklist "Make it verify cron and channel health."
+wispy exec "list all exported functions" --json | jq -r 'select(.type=="content") | .content'
 ```
 
-### Agents and sub-agents
+---
 
-Wispy supports delegated execution through agent and sub-agent orchestration.
+## Sessions
 
-| Capability | Description |
-| --- | --- |
-| Agent listing | Inspect active and recent workers |
-| Agent detail | Pull status and results |
-| Agent termination | Kill a running task |
-| Parallel delegation | Spawn task-specific workers |
-| Pipelines | Chain role-based execution stages |
+All conversations are automatically saved to `~/.wispy/sessions/`.
 
-Examples:
+```bash
+# List recent sessions
+wispy sessions
 
-```text
-/agents
-/agent agent-123
-/kill agent-123
-```
+# Resume a specific session
+wispy resume abc123
 
-## MCP and Built-in Tools
+# Resume the most recent session
+wispy resume --last
 
-Wispy can merge Model Context Protocol tools with its own built-in tool registry.
+# Fork a session (branch point)
+wispy fork --last
 
-### MCP
+# Give a session a name for easy retrieval
+wispy --name "auth-refactor" "let's refactor the auth module"
+```
+
+Sessions are organized by workstream. Use `-w <name>` to switch workstreams:
 
 ```bash
-wispy mcp
-wispy mcp list
-wispy mcp connect
-wispy mcp disconnect
-wispy mcp reload
-wispy mcp config
+wispy -w client-project "what's the status?"
+wispy -w personal "remind me what I was working on"
 ```
 
-### Built-in tools
+---
+
+## Architecture
 
-Wispy ships with 18+ built-in tools across file operations, shell execution, git, web access, memory, planning, and delegation.
+```
+                         wispy-cli
+                              │
+              ┌───────────────┼───────────────┐
+              │               │               │
+         bin/wispy.mjs   lib/wispy-repl  lib/channels/
+         (CLI router)    (REPL/TUI)      (TG/DC/Slack)
+              │               │               │
+              └───────────────┼───────────────┘
+                              │
+                    core/engine.mjs (WispyEngine)
+                    ├── processMessage()
+                    ├── tool loop + approvals
+                    └── sub-agent dispatch
+                              │
+          ┌───────────────────┼───────────────────┐
+          │                   │                   │
+   core/providers.mjs  core/tools.mjs    core/session.mjs
+   (27 providers)      (built-in tools   (persistence,
+                        + MCP tools)      workstreams)
+                              │
+          ┌───────────────────┼───────────────────┐
+          │                   │                   │
+   core/harness.mjs    core/memory.mjs   core/subagents.mjs
+   (trust/approvals)   (long-term         (worker threads)
+                        memory)
+```
 
-| Tool family | Examples |
-| --- | --- |
-| Files | `read_file`, `write_file`, `file_edit`, `file_search`, `list_directory` |
-| Execution | `run_command`, `git`, `web_search`, `web_fetch` |
-| System | `keychain`, `clipboard` |
-| Planning | `update_plan`, `pipeline`, `ralph_loop` |
-| Agents | `spawn_agent`, `spawn_async_agent`, `spawn_subagent`, `list_agents`, `list_subagents`, `get_agent_result`, `get_subagent_result`, `kill_subagent` |
+### Key modules
+
+| Module | Purpose |
+|--------|---------|
+| `core/engine.mjs` | Main chat loop — message → AI → tools → response |
+| `core/providers.mjs` | Multi-provider adapter (27 providers) |
+| `core/tools.mjs` | Tool registry + execution |
+| `core/session.mjs` | Session management and persistence |
+| `core/harness.mjs` | Trust levels, approval gate, audit log |
+| `core/memory.mjs` | Long-term memory (Markdown files) |
+| `core/subagents.mjs` | Sub-agent orchestration (Worker threads) |
+| `core/budget.mjs` | Token counting and spend tracking |
+| `core/features.mjs` | Feature flag management |
+| `core/browser.mjs` | Browser bridge client |
+| `core/secrets.mjs` | Encrypted secret storage |
+| `core/tts.mjs` | Text-to-speech (OpenAI + macOS) |
+| `core/agents.mjs` | Agent definitions (built-in + custom) |
+| `core/task-router.mjs` | Smart task routing |
+| `core/task-decomposer.mjs` | Parallel task splitting |
+| `core/loop-detector.mjs` | Repetitive loop detection and break |
+| `lib/wispy-repl.mjs` | Interactive REPL shell |
+| `lib/commands/review.mjs` | Code review command |
+| `lib/commands/trust.mjs` | Trust/security settings |
+| `lib/jsonl-emitter.mjs` | JSONL event stream for CI |
+
+---
 
-## Channels and Scheduling
+## Development
 
-### Messaging channels
+### Requirements
 
-| Channel | Status in repo |
-| --- | --- |
-| Telegram | Built-in adapter |
-| Discord | Built-in adapter |
-| Slack | Built-in adapter |
-| WhatsApp | Built-in adapter |
-| Signal | Built-in adapter |
-| Email | Built-in adapter |
+- Node.js >= 18.0.0
+- npm >= 9.0.0
 
-Example setup paths:
+### Setup
 
 ```bash
-wispy channel setup telegram
-wispy channel setup discord
-wispy channel setup slack
+git clone <repo>
+cd agent-workstream-os/wispy-cli
+npm install
+node bin/wispy.mjs doctor
 ```
 
-### Cron scheduler
-
-Use Wispy as an operator that wakes itself up and delivers work on schedule.
+### Testing
 
 ```bash
-wispy cron add
-wispy cron list
-wispy cron run <job-id>
-wispy cron remove <job-id>
-wispy cron history <job-id>
-wispy cron start
-```
-
-## Slash Commands
-
-The shared command registry powers REPL completion, the TUI command palette, and shell completion.
-
-### By category
-
-| Category | Commands |
-| --- | --- |
-| Workstream | `/ws`, `/ws new <name>`, `/ws <name>`, `/ws status`, `/ws search <query>`, `/ws archive <name>`, `/ws delete <name>` |
-| Trust | `/trust`, `/trust <level>`, `/trust log`, `/dry`, `/receipt`, `/replay`, `/permissions`, `/permit <tool> <level>`, `/audit` |
-| Continuity | `/where`, `/handoff`, `/sync` |
-| Skills | `/skills`, `/teach <name>`, `/improve <name>` |
-| Session | `/clear`, `/model`, `/cost`, `/compact`, `/sessions`, `/history` |
-| Memory | `/remember <text>`, `/recall <query>`, `/memories`, `/forget <key>` |
-| Agents | `/agents`, `/agent <id>`, `/kill <id>` |
-| MCP | `/mcp`, `/mcp list`, `/mcp connect`, `/mcp disconnect`, `/mcp reload`, `/mcp config` |
-| Quick aliases | `/o`, `/w`, `/a`, `/m`, `/t`, `/s`, `/d` |
-| Meta | `/help`, `/quit`, `/exit`, `/provider`, `/overview`, `/search <keyword>` |
-
-### Full scan list
-
-```text
-/ws
-/trust
-/dry
-/receipt
-/replay
-/where
-/handoff
-/sync
-/skills
-/teach
-/improve
-/clear
-/model
-/cost
-/compact
-/sessions
-/history
-/remember
-/recall
-/memories
-/forget
-/agents
-/agent
-/kill
-/mcp
-/permissions
-/permit
-/audit
-/o
-/w
-/a
-/m
-/t
-/s
-/d
-/help
-/quit
-/exit
-/provider
-/overview
-/search
+# Run all tests
+npm test
+
+# Run with verbose reporter
+npm run test:verbose
+
+# Run specific test file
+node --test tests/smoke.test.mjs
+
+# Run basic tests only
+npm run test:basic
 ```
 
-## Architecture
+### Test structure
+
+```
+tests/
+├── smoke.test.mjs          # CLI command smoke tests
+├── channels.test.mjs       # Channel integration tests
+├── core-agents.test.mjs    # Agent system tests
+├── core-browser.test.mjs   # Browser bridge tests
+├── core-budget.test.mjs    # Budget/cost tracking tests
+├── core-cron.test.mjs      # Cron scheduler tests
+├── core-engine.test.mjs    # Engine unit tests
+├── core-harness-filters.test.mjs  # Trust/approval tests
+├── core-loop-detector.test.mjs    # Loop detection tests
+├── core-memory.test.mjs    # Memory system tests
+├── core-secrets.test.mjs   # Secrets manager tests
+├── core-session.test.mjs   # Session manager tests
+├── core-subagents.test.mjs # Sub-agent tests
+├── core-tools.test.mjs     # Tool registry tests
+└── core-tts.test.mjs       # TTS manager tests
+```
 
-The repository is organized around two entrypoints, a core runtime, user-facing command modules, channel adapters, and a focused test suite.
+### Project structure
 
-```text
+```
 wispy-cli/
 ├── bin/
-│   ├── wispy.mjs
-│   ├── wispy-tui.mjs
-├── core/
-│   ├── engine.mjs
-│   ├── providers.mjs
-│   ├── auth.mjs
-│   ├── config.mjs
-│   ├── permissions.mjs
-│   ├── audit.mjs
-│   ├── session.mjs
-│   ├── memory.mjs
-│   ├── skills.mjs
-│   ├── subagents.mjs
-│   ├── mcp.mjs
-│   ├── cron.mjs
-│   ├── sync.mjs
-│   ├── onboarding.mjs
-│   └── ...
+│   ├── wispy.mjs           # Main CLI entry point (command router)
+│   └── wispy-tui.mjs       # TUI entry point
+├── core/                   # Core engine modules
+│   ├── engine.mjs          # WispyEngine (main chat loop)
+│   ├── providers.mjs       # Multi-provider adapter
+│   ├── tools.mjs           # Tool registry
+│   ├── session.mjs         # Session management
+│   ├── harness.mjs         # Trust/approval system
+│   ├── memory.mjs          # Long-term memory
+│   ├── subagents.mjs       # Sub-agent orchestration
+│   └── ...                 # (other modules)
 ├── lib/
-│   ├── wispy-repl.mjs
-│   ├── wispy-tui.mjs
-│   ├── command-registry.mjs
-│   ├── channels/
-│   │   ├── index.mjs
-│   │   ├── telegram.mjs
-│   │   ├── discord.mjs
-│   │   ├── slack.mjs
-│   │   ├── whatsapp.mjs
-│   │   ├── signal.mjs
-│   │   ├── email.mjs
-│   │   └── base.mjs
-│   └── commands/
-│       ├── ws.mjs
-│       ├── trust.mjs
-│       ├── continuity.mjs
-│       ├── skills-cmd.mjs
-│       └── ws-interactive-enhancement.js
-└── tests/
-    ├── channels.test.mjs
-    ├── core-engine.test.mjs
-    ├── core-tools.test.mjs
-    ├── core-memory.test.mjs
-    ├── core-session.test.mjs
-    ├── core-subagents.test.mjs
-    └── core-cron.test.mjs
-```
-
-### Runtime flow
-
-```text
-bin/wispy.mjs
-  -> lib/wispy-repl.mjs
-  -> core/engine.mjs
-     -> core/providers.mjs
-     -> core/tools.mjs
-     -> core/session.mjs
-     -> core/memory.mjs
-     -> core/subagents.mjs
-     -> core/mcp.mjs
-     -> core/audit.mjs
-     -> core/permissions.mjs
-
-bin/wispy-tui.mjs
-  -> lib/wispy-tui.mjs
-  -> core/engine.mjs
+│   ├── wispy-repl.mjs      # Interactive REPL
+│   ├── channels/           # Bot channel integrations
+│   └── commands/           # CLI command handlers
+├── tests/                  # Test suite
+└── package.json
 ```
 
-## Development
+### Adding a provider
 
-### Tests
+Providers are defined in `core/config.mjs` under `PROVIDERS`. Each provider needs:
 
-```bash
-npm test
+```js
+myProvider: {
+  label: "My Provider",
+  envKeys: ["MY_PROVIDER_API_KEY"],
+  baseUrl: "https://api.myprovider.com/v1",
+  defaultModel: "my-model-v1",
+  models: ["my-model-v1", "my-model-v2"],
+  chatPath: "/chat/completions",
+  // or: custom: true (for non-OpenAI-compatible APIs)
+}
 ```
 
-Current status:
-
-| Metric | Value |
-| --- | --- |
-| Test suites | `8` |
-| Tests | `91` |
-| Passing | `91` |
-| Failing | `0` |
+---
 
 ## License
 
 MIT
 
-Built by Minseo & Poropo 🫧
+---
+
+## Credits
+
+Built by **Minseo & Poropo** 🫧