⚡ 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

Feature	Claude Code	OpenCode	Void Spirit
Cost	$20/mo subscription	Your API key only	Your API key only
China access	❌ Blocked	⚠️ Possible	✅ DeepSeek, Gemini, Ollama, Qwen
Local models	❌	✅ Ollama	✅ Ollama + LM Studio
Multi-provider	Claude only	✅ 10+	✅ 17+ providers
Login required	✅ Anthropic account	❌ None	❌ None
MCP support	✅	✅	✅ Full MCP host
Token budgets	❌	❌	✅ Per-session caps
Team config	❌	❌	✅ Shared `.void-spirit/team.json`
Audit log	❌	❌	✅ Full action trail + export
LSP integration	❌	✅	❌
Plan/Build modes	❌	✅	Implicit via approval
Session persist	✅	✅	✅
Conversation branching	❌	❌	✅ Fork & switch
Plugin system	❌	❌	✅ GitHub plugins + security
Security sandbox	✅	⚠️	✅ Path + command sandbox
Subagents	✅	❌	✅ Isolated context
Task tracking	✅	❌	✅ Persistent todos
On-demand skills	❌	❌	✅ Load on need
OpenCode compatible	❌	✅	✅ Config + MCP import

OpenCode Compatible

Void Spirit is fully compatible with the OpenCode ecosystem:

MCP Server Support

Connect to any Model Context Protocol server. Configure in .void-spirit/team.json or opencode.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"]
    }
  }
}

MCP tools appear alongside built-in tools automatically. Use /mcp to list connected servers.

Instruction Files

Void Spirit reads project instruction files from multiple formats:

File	Source
`.void-spirit.md`	Void Spirit (highest priority)
`AGENTS.md`	OpenCode
`CLAUDE.md`	Claude Code
`.cursorrules`	Cursor
`.cursor/rules/*.md`	Cursor (directory)
`.github/copilot-instructions.md`	GitHub Copilot

All discovered files are merged into the system prompt automatically.

OpenCode Config Import

Drop an opencode.json or opencode.jsonc in your project root. Void Spirit will:

Import provider and model settings
Import MCP server definitions
Load instruction file references

Your existing OpenCode config works out of the box — no migration needed.

Supported Providers

Provider	Type	Notes
OpenAI	Cloud	GPT-4o, GPT-4, o1, etc.
Google Gemini	Cloud	Via OpenAI-compatible endpoint
Anthropic Claude	Cloud	Native SDK
DeepSeek	Cloud	Reasoner thinking mode ✅
Groq	Cloud	Ultra-fast inference
Ollama	Local	No internet needed
Together AI	Cloud	Open-source models
OpenRouter	Cloud	MiMo, Mistral, Llama, etc.
Mistral	Cloud	Large, Nemo, Pixtral
Perplexity	Cloud	Sonar reasoning
Fireworks	Cloud	Serverless Llama endpoints
Cerebras	Cloud	Ultra-fast hardware
Moonshot / Kimi	Cloud	Native endpoint
Alibaba Qwen	Cloud	DashScope compatible
SambaNova	Cloud	Specialized inference
LM Studio	Local	Like Ollama, no key needed
Custom	Any	Any OpenAI-compatible endpoint

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

Command	Description
`/help`	Show all commands
`/model <name>`	Switch model
`/provider <name>`	Switch provider
`/config`	Show configuration
`/clear`	Clear conversation
`/compact`	Summarize to save context
`/image <path>`	Attach image to next message
`/memory add <text>`	Save a memory
`/memory`	Show saved memories
`/save [name]`	Save current session
`/load [name]`	List or load sessions
`/fork [label]`	Create conversation checkpoint
`/branches`	List checkpoints
`/switch <label>`	Restore a checkpoint
`/diff`	Show file changes vs git HEAD
`/context`	Show context window usage
`/stats`	Show token usage & cost
`/undo`	Undo last file change
`/auto`	Toggle auto-approve mode
`/export`	Export conversation to markdown
`/install <url>`	Install a plugin
`/plugins`	List installed plugins
`/trust <name>`	Trust a plugin (grant declared permissions)
`/untrust <name>`	Revoke trust (restrict to read-only)
`/exit`	Quit

Tools

The AI can use these tools during conversation:

Tool	Description
`read_file`	Read files with line numbers
`write_file`	Create/overwrite files
`edit_file`	Find-and-replace edits
`list_directory`	Browse file system
`search_files`	Glob-based file search
`grep`	Search code contents
`run_command`	Execute shell commands (with approval)
`web_fetch`	Fetch URLs as markdown
`git_command`	Git operations
`create_directory`	Create directories
`delete_file`	Delete files (with approval)
`move_file`	Move/rename files
`spawn_subagent`	Run isolated sub-agent for focused tasks
`todo_write`	AI-managed persistent task tracking
`load_skill`	Load expert knowledge modules on-demand

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

Capability	Risk	Allowed Tools
`fs:read`	🟢 Low	read_file, list_directory, search_files, grep
`fs:write`	🟡 Medium	write_file, edit_file, create_directory
`fs:delete`	🟠 High	delete_file, move_file
`command:run`	🔴 Critical	run_command
`git:read`	🟢 Low	git (status, log, diff)
`git:write`	🟡 Medium	git (commit, push, checkout)
`web:fetch`	🟡 Medium	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

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

Discoverability

Project: Void Spirit CLI
Summary: A terminal AI coding assistant that works with any LLM provider, supports local or remote models, and avoids account lock-in for agentic development workflows.
Primary keywords: ai-agent, ai-coding-assistant, terminal-ai, coding-agent, developer-tools, llm, cli, ai-cli, nodejs, npm-package, openai, gemini
Use cases: Terminal AI coding assistance, Provider-agnostic LLM workflows, Local and remote model experimentation
Live URL: https://www.npmjs.com/package/void-spirit

Void-spirit-CLI

Links

README