Spidy CLI — spidy-agent

A sharp, friendly AI partner built into your terminal. Powered by NVIDIA NIM cloud models & local Ollama. Works on Linux, macOS, and Windows.

---

⚡ Install (Any OS)

pip install spidy-agent

Then just run:

spidy

⚠️ Got an install error?

On Linux (externally-managed-environment error)

On modern Linux distributions (like Ubuntu 23.04+, Debian, Fedora), system-wide pip installs are blocked by default. You can resolve this using one of these options:

• Option A: Install via pipx (Recommended):

  sudo apt install pipx
  pipx ensurepath
  # (Restart your terminal here)
  pipx install spidy-agent
  

• Option B: Force User Install:

  pip install spidy-agent --break-system-packages
  

On Windows (PermissionError or path issues)

If installation fails on Windows or if spidy command is not recognized after installation:

• Option A: Run as Administrator: Open Command Prompt or PowerShell as Administrator and run:

  pip install --upgrade spidy-agent
  

• Option B: User-only install:

  pip install --upgrade --user spidy-agent
  

• Option C: Use isolated environment:

  python -m venv %USERPROFILE%\.spidy-env
  %USERPROFILE%\.spidy-env\Scripts\pip install spidy-agent
  # To run: %USERPROFILE%\.spidy-env\Scripts\spidy
  

---

🖥️ OS Support

OS	Install	Works?
Ubuntu / Debian	pip install spidy-agent	✅
Fedora / Arch Linux	pip install spidy-agent	✅
macOS	pip install spidy-agent	✅
Windows 10/11	pip install spidy-agent	✅
Any OS with Python 3.10+	pip install spidy-agent	✅

---

📦 One-Line Installers (Alternative)

Linux / macOS

curl -sSL https://raw.githubusercontent.com/karthik/spidy-cli/main/install.sh | bash

Windows (PowerShell)

pip install spidy-agent

Or double-click install.bat from the downloaded release.

---

🚀 Features

• 💬 Smart Chat — Short, friendly, professional replies. Matches your energy.
• 🌐 Live News — Fetches real-time headlines. Supports regional queries (e.g., "news in Tamilnadu").
• 🕐 Time & Date — Instant time, date, calendar info.
• 🖥️ System Diagnostics — Live CPU, RAM, disk, battery stats via psutil.
• 🔐 Security Scanner — Built-in heuristic scanner, no ClamAV needed.
• 📁 File Manager — Find, open, and manage files via chat.
• 🗺️ Maps & Directions — Ask for directions or locations.
• 💻 Code Assistant — Write, debug, and generate code.
• 🌐 Web Developer — Generate HTML/CSS/JS apps from a description.
• ⚡ Command Runner — Safely execute shell commands on any OS.
• 🌍 Multi-language — English, Tamil, Tanglish support.

---

📁 Chat History

Every conversation is automatically saved locally — no database needed.

your-folder/
└── spidy-chat-history/
    ├── 2026-07-04_16-35-42.jsonl   ← this session
    └── 2026-07-03_10-12-00.jsonl   ← previous session

Each file is plain JSONL — one message per line, human-readable.

---

⚙️ Configuration (Optional)

To use NVIDIA NIM cloud models, create ~/.spidy/config.yaml:

spidy:
  llm_model: phi3:mini   # Local Ollama model (optional)

apis:
  nvidia_nim:
    deepseek_v4_flash: YOUR_NIM_API_KEY
    llama_3_2_11b_vision_instruct: YOUR_NIM_API_KEY

Get a free NVIDIA NIM API key at: https://build.nvidia.com/

Without a config file, Spidy works with a local Ollama instance.

---

🔧 Requirements

• Python 3.10+
• pip (comes with Python)
• Internet connection (for cloud LLM models)
• Optional: Ollama for fully local/offline operation

---

📄 License

MIT License — free to use, modify, and distribute.