Spidey CLI: Agentic Terminal Runtime

A state-of-the-art terminal AI client featuring an autonomous Agent Runtime, modular multi-provider backend, LSP diagnostics verification, and a high-performance Ink/React TUI.

┌──────────────────────┐
│      TUI Client      │
│   (Terminal UI)      │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│    Agent Runtime     │
│ - Planning           │
│ - Context Mgmt       │
│ - Permissions        │
│ - Sessions           │
└──────────┬───────────┘
           │
   ┌───────┼────────┐
   ▼       ▼        ▼
 Models   Tools    LSP
 Claude   Bash     TS/Go/Python/Rust
 GPT      Files    Diagnostics
 Gemini   Git      Syntax Verifier
 Local
 OpenRouter

🚀 Key Capabilities

• Autonomous Agent Planning: Dynamic task decomposition, step tracking, tool routing, and verification loop.
• Context Management: Workspace indexing with ignore filters (.gitignore, node_modules, .git), file relevance tracking, and sliding-window history pruning within token budgets.
• Default-Deny Security & Permissions: High/medium/low risk classification with interactive approval prompts ([Y] Allow Once, [A] Always Allow in Session, [N] Deny).
• Persistent Sessions: JSON-backed state storage at ~/.spidey/sessions/ preserving full conversation history, plan progress, and active file context with 0600 permissions.
• Multi-Provider LLM Engine:
  • 🟣 Anthropic Claude (claude-3-7-sonnet, claude-3-5-sonnet, claude-3-5-haiku, claude-3-opus)
  • 🟢 OpenAI GPT (gpt-4o, gpt-4o-mini, gpt-4.5-preview, o3-mini, o1)
  • 🔵 Google Gemini (gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash, gemini-1.5-pro)
  • 🟡 Local Ollama / vLLM (qwen2.5-coder, llama3.3, deepseek-r1, mistral, codellama)
  • 🌐 OpenRouter (claude-3.7-sonnet, deepseek-r1, gpt-4.5-preview, gemini-2.5-flash, llama-3.3-70b)
• Full Tool Suite:
  • bash / shell execution with timeout handling
  • read_file, write_file, edit_file with diff matching
  • list_dir, grep_search (with ripgrep & grep fallbacks)
  • git_status, git_diff, git_log, git_commit
• LSP Diagnostics & Compiler Verification: Integrated post-edit syntax checks and diagnostics across TypeScript/JavaScript (tsc, eslint), Python (py_compile, ruff, flake8), Go (go vet), and Rust (cargo check).

🛠️ Quick Start

1. Configure Environment or Local Keys

cp .env.example .env
# Fill in any keys you want to use:
# ANTHROPIC_API_KEY=...
# OPENAI_API_KEY=...
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...
# LOCAL_MODEL_URL=http://localhost:11434/v1

2. Launch Interactive Terminal UI

cd frontend
npm install
npm start

⌨️ In-Chat Commands & Hotkeys

| Shortcut | Command | Action | |---|---|---| | m | /models | Open interactive Model & Provider picker | | s | /sessions | Open Session Manager (switch, delete, or create new) | | k | /keys | Open Local Key Vault (~/.spidey/keys.json) | | p | /plan | View task decomposition and step execution status | | c | /context | Inspect workspace index, active files, and token usage | | d | /diagnostics | Run LSP diagnostics across workspace or file | | | /agent | Toggle autonomous agent mode (tools & planning) | | | /provider <name> | Switch provider (claude, gpt, gemini, local, openrouter) | | | /model <name> | Switch active model | | | /permissions <mode> | Change security mode (interactive, safe, auto_approve) | | | /git | View git status & diff | | | /clear | Clear chat and start a clean session | | | /exit | Exit Spidey CLI |

🖥️ Command Line Usage (CLI & Headless)

1. List Providers & Check Local Ollama Status

python3 backend/agent.py --list-models

2. Run Direct or Autonomous Prompt

# Direct single prompt
python3 backend/agent.py --provider gemini --model gemini-2.5-flash --prompt "Explain Python dataclasses"

# Autonomous task execution with planning & tools
python3 backend/agent.py --provider claude --model claude-3-7-sonnet --agent --prompt "Add user authentication middleware"

3. Run Workspace LSP Diagnostics

python3 backend/agent.py --diagnostics --workspace .

4. Headless Sandbox & Benchmark Runner (Terminal-Bench 2.1)

export OPENROUTER_API_KEY=your_key
python3 backend/spidey_agent.py --unsafe --provider openrouter --model openai/gpt-4.1-mini --instruction "Fix failing tests in auth module"

🔒 Security Architecture

By default, Spidey enforces an Interactive Security Policy:

• Read-only tools (read_file, list_dir, grep_search, git_status, lsp_diagnostics) are permitted automatically.
• Mutating tools (write_file, edit_file, git_commit) and shell commands (bash) require explicit interactive approval or session whitelisting.
• High-risk patterns (rm -rf, sudo, dd, fork bombs, etc.) are strictly flagged as high-risk.
• In isolated containers or CI environments, --unsafe / permission_mode=auto_approve can be enabled.