wispy-cli

AI workspace assistant — chat, automate, and orchestrate from the terminal.

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.

Table of Contents

• Quick Start
• Commands
• Global Flags
• Feature Highlights
• Providers
• Configuration
• Agent System
• Trust & Security
• Memory System
• Sub-Agent Orchestration
• Browser Integration
• Text-to-Speech
• Code Review
• JSONL Event Stream
• Sessions
• Architecture
• Development
• Credits

Quick Start

# Install
npm install -g wispy-cli

# First-time setup (choose provider, set API key)
wispy setup

# Start chatting
wispy

One-shot (non-interactive):

wispy "summarize the last 10 commits"
wispy exec "list all TODO comments in src/" --json   # JSONL output

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 |

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.

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

{
  "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:

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:

{
  "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."
    }
  }
}

MCP servers: ~/.wispy/mcp.json

Configure Model Context Protocol servers:

{
  "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 |

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:

{
  "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"]
    }
  }
}

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) |

wispy trust                  # Interactive settings
wispy config set securityLevel careful

Tool Permissions

Control which tools the AI can use per-session:

# 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"

Budget Cap

Prevent runaway API spending:

wispy --max-budget-usd 2.00 "analyze all 500 files in src/"

Audit Log

All tool approvals and executions are logged. View with:

wispy trust log

Loop Detection

Detects and breaks repetitive tool-call loops automatically. Configure sensitivity via feature flags.

Memory System

Wispy stores persistent memory in ~/.wispy/memory/. Memory is plain Markdown files, organized by topic.

In-session commands

/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:

wispy features enable auto_memory

Sub-Agent Orchestration

wispy can spawn parallel sub-agents for complex multi-step tasks. Each agent runs in an isolated worker thread.

# Example: analyze entire codebase in parallel
wispy "analyze all modules in src/ in parallel and give me a security report"

Sub-agents share the same tool registry but have isolated conversation state. Results are merged and returned to the orchestrating agent.

Configure with multi_agent feature flag:

wispy features enable multi_agent

Browser Integration

Control a running browser via local-browser-bridge:

# Start the bridge (in another terminal)
npx local-browser-bridge serve

# Then use wispy browser commands
wispy browser tabs
wispy browser navigate https://example.com
wispy browser screenshot output.png

# Or ask wispy to use the browser in chat
wispy "go to github.com and tell me what's trending today"

Enable browser feature: wispy features enable browser_integration

Text-to-Speech

# 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

Voices (OpenAI): alloy, echo, fable, onyx, nova, shimmer

Enable TTS in responses: wispy features enable tts

Code Review

# Review all uncommitted changes
wispy review

# Review against a branch
wispy review --base main

# Review a specific commit
wispy review --commit abc1234

# Get structured JSON output (for CI integration)
wispy review --json > review.json

Review output format:

## Summary
[Brief summary of changes]

## Issues Found
### Critical / Warnings / Info
[Categorized issues]

## File Comments
[Line-level comments]

## Assessment
Verdict: approve | request-changes | comment

JSONL Event Stream

Use wispy exec --json for machine-readable output in CI/CD pipelines:

wispy exec "analyze package.json for security issues" --json

Each line is a JSON event:

{"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:

wispy exec "list all exported functions" --json | jq -r 'select(.type=="content") | .content'

Sessions

All conversations are automatically saved to ~/.wispy/sessions/.

# List recent sessions
wispy sessions

# Resume a specific session
wispy resume abc123

# Resume the most recent session
wispy resume --last

# Fork a session (branch point)
wispy fork --last

# 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:

wispy -w client-project "what's the status?"
wispy -w personal "remind me what I was working on"

Architecture

                         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)

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 |

Development

Requirements

• Node.js >= 18.0.0
• npm >= 9.0.0

Setup

git clone <repo>
cd agent-workstream-os/wispy-cli
npm install
node bin/wispy.mjs doctor

Testing

# 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

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

Project structure

wispy-cli/
├── bin/
│   ├── 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      # Interactive REPL
│   ├── channels/           # Bot channel integrations
│   └── commands/           # CLI command handlers
├── tests/                  # Test suite
└── package.json

Adding a provider

Providers are defined in core/config.mjs under PROVIDERS. Each provider needs:

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)
}

License

MIT

Credits

Built by Minseo & Poropo 🫧