⚡ Void Spirit

Terminal AI coding assistant — any LLM, no login, no geo-restrictions.

Inspired by the agent engineering principles from learn-claude-code. Built for developers who want the same agentic power with any LLM provider — no Anthropic subscription required.

Why Void Spirit?

Most AI coding agents lock you into a single provider. Void Spirit doesn't.

• 🌏 Works from China — Use DeepSeek, Gemini, or any accessible API. No VPN gymnastics.
• 🔓 No login, no account — Bring your own API key. That's it.
• 🏠 Run locally — Full offline mode with Ollama. Your code never leaves your machine.
• 💰 Zero subscription — Pay only for what you use via API. No $20/mo paywall.
• 🧠 DeepSeek thinking mode — First-class support for DeepSeek Reasoner's chain-of-thought.

Who Is Void Spirit For?

🧑‍💻 Personal — Indie Devs, Students, Hobbyists

• Free AI pair programming with any model you choose
• Learn to code with AI — no subscription paywall
• Built-in productivity skills: daily planner, notes, learning paths
• Privacy-first: run Ollama locally, your code stays on your machine

🏢 Teams & Business — Consultants, Startups, Enterprise

• Token budgets — Cap spending per session (--budget 50000 or --budget-usd 0.50)
• Team config — Share standardized settings via .void-spirit/team.json in your repo
• Audit log — Full trail of every AI action for compliance (/audit, --export-audit)
• Data sovereignty — Run with Ollama or LM Studio, air-gapped, zero data exfiltration
• Plugin security — Three-tier trust model with SHA-256 integrity verification

Install

# Run instantly (no install)
npx void-spirit

# Or install globally
npm install -g void-spirit
void-spirit   # or: vs

First run will launch the setup wizard to pick your provider and model.

How It Compares

Supported Providers

Features

• 🛠️ 15 built-in tools — File ops, shell commands, git, web fetch, grep, search, subagents, todos, skills
• 🤖 Subagents — Spawn isolated sub-agents for focused tasks, keeping main context clean
• 📋 Task tracking — AI-managed todo list that persists across sessions
• 📚 On-demand skills — Load expert knowledge modules only when needed (saves context)
• 💾 Session persistence — Auto-save on exit, resume with --resume
• 🌿 Conversation branching — Fork checkpoints, switch between them
• ⚡ Parallel tool execution — Read-only tools run concurrently for speed
• 📝 Streaming markdown — Rich formatted output in terminal
• 🧠 Persistent memory — Cross-session memory with /memory add
• 📊 Token tracking — Real-time usage and cost estimation
• 💵 Token budgets — Per-session spending caps (--budget, --budget-usd)
• 👥 Team config — Shared settings via .void-spirit/team.json
• 🎯 Project detection — Auto-detects project type and adapts context
• 🔒 Security sandbox — Path sandboxing, command blocklist, audit log
• 📋 Audit export — Export AI action log for compliance (--export-audit)
• ↩️ Undo/rollback — Revert file changes with /undo
• 🔌 Plugin system — Install from GitHub with /install <url>

Quick Start

# Start with specific provider
void-spirit --provider deepseek --model deepseek-reasoner --api-key YOUR_KEY

# Use local Ollama
void-spirit --provider ollama --model codellama

# Resume last session
void-spirit --resume

Commands

Tools

The AI can use these tools during conversation:

Plugins

Install plugins from GitHub:

# Inside Void Spirit
/install https://github.com/user/void-spirit-plugin

Plugins are stored in ~/.void-spirit/plugins/.

Plugin Security

Void Spirit enforces a three-layer plugin security model:

Permission Scoping — Plugins declare capabilities in manifest.json:

{ "permissions": ["fs:read", "fs:write", "web:fetch"] }

Trust Tiers — 🟢 Built-in (full) · 🔵 Verified (declared perms) · 🟡 Untrusted (read-only). Use /trust and /untrust to manage. Verified plugins include SHA-256 integrity checking.

Sandboxed Execution — Plugin tool calls go through a proxy executor that blocks unauthorized tools, restricts file paths, and logs all blocked attempts.

Architecture

src/
├── index.js            # CLI entry point
├── config.js           # Provider/model configuration
├── conversation.js     # Message management
├── memory.js           # Persistent memory
├── session.js          # Session save/load
├── token-tracker.js    # Usage & cost tracking
├── security.js         # Path sandbox & command blocklist
├── project-detector.js # Auto-detect project type
├── skill-loader.js     # On-demand skill loading
├── providers/          # LLM provider adapters
│   ├── index.js        # Provider factory
│   ├── openai-compat.js# OpenAI-compatible (most providers)
│   └── anthropic.js    # Native Anthropic SDK
├── tools/              # Agent tool definitions
│   ├── definitions.js  # Tool schemas (15 tools)
│   ├── executor.js     # Tool execution logic
│   ├── subagent.js     # Isolated sub-agent execution
│   └── todo.js         # Persistent task tracking
├── skills/             # Built-in skill prompts
├── plugins/            # Plugin system
│   ├── loader.js       # Plugin loader + security integration
│   ├── plugin-permissions.js  # Capability → tool mapping
│   ├── plugin-sandbox.js      # Sandboxed tool executor
│   └── trust-manager.js       # Three-tier trust model
└── ui/                 # Terminal UI
    ├── banner.js       # Startup banner
    ├── renderer.js     # Markdown renderer
    └── repl.js         # Interactive REPL

Contributing

See CONTRIBUTING.md for setup and guidelines.

License

MIT © silverlion2

⚡ Any LLM. No login. No restrictions. Just code.