The agentic shell for building and running AI teams from the command line.
npcsh makes the most of LLMs and agents through an interactive shell. Build teams of agents, schedule them on jobs, engineer context, and design custom Jinja Execution templates (Jinxes) for your agents to invoke for tool-use, prompts, and skills.
Install npcsh:
curl -fsSL https://enpisi.com/install-npcsh.sh | sh
npcshAsk a question:
npcsh> what process is listening on port 5337?Delegate to a coding agent:
npcsh> @corca refactor the auth module and add testsOpen the Git TUI after changes:
npcsh> /gittThe benchmark suite measures how well a model can drive npcsh as an agentic shell. It covers 100 tasks across 10 categories, from basic shell commands and file operations to multi-step workflows, debugging, git, and scripting. Each task is scored pass/fail by an automated verifier.
The table below shows scores (100 tasks).
| Family | Model | Version | Score |
|---|---|---|---|
| Qwen3.5 | 35b | v2.1.5 | 97/100 (97%) |
| 9b | v2.1.5 | 95/100 (95%) | |
| 397b | v2.1.7 | 96/100 (96%) | |
| Ornith | 35b | v2.1.7 | 97/100 (97%) |
| 9b | v2.1.5 | 57/100 (57%) | |
| Kimi K2.7-Code | 1t (32b active) | v2.1.7 | 97/100 (97%) |
| Minimax | m3 428b (23b active) | v2.1.7 | 96/100 (96%) |
| DeepSeek | v4-flash 284b (13b active) | v2.1.7 | 95/100 (95%) |
| Mistral | devstral-2 123b | v2.1.7 | 94/100 (94%) |
| devstral-small-2 24b | v2.1.7 | 94/100 (94%) | |
| large-3 675b | v2.1.7 | 89/100 (89%) | |
| North Mini Code 1.0 | 30b (3b active) | v2.1.5 | 93/100 (93%) |
| Gemma 4 | 31b | v2.1.7 | 92/100 (92%) |
| Qwen3.6 | 35b | v2.1.5 | 91/100 (91%) |
| Nemotron | 3-super 120b (12b active) | v2.1.7 | 88/100 (88%) |
| Laguna XS 2.1 | 33b (3b active) | v2.1.5 | 24/100 (24%) |
For a more comprehensive view of npcsh's capabilities and the advantages of the NPC Context-Agent-Tool data layer, see ALARA for Agents: Least-Privilege Context Engineering Through Portable Composable Multi-Agent Teams.
curl -fsSL https://enpisi.com/install-npcsh.sh | shThis downloads the latest npcsh and npc Rust binaries for your platform into ~/.npcsh/bin, adds that directory to your PATH in your shell rc file, and walks you through installing the npcpy Python backend — offering any existing virtualenvs it finds, or a fresh one via uv, pyenv, or python3 -m venv. Then run npcsh.
See Python backend (npcpy) below for details on that requirement.
cargo install npcshNote: this is a temporary requirement. The
npcpyserver will be replaced by a Rust-native runner for the AI parsing once npcrs reaches greater stability.
npcsh drives its agent loop through a local npcpy server, which it spawns automatically on startup — there is nothing to run manually, but the Python interpreter npcsh uses must have npcpy importable:
pip install npcpyRequires Python 3.10 or newer.
By default npcsh runs python3 -m npcpy.serve on 127.0.0.1:5237. If npcpy lives in a non-default Python (a venv, conda env, or pyenv version), point npcsh at that interpreter:
export BACKEND_PYTHON_PATH=/path/to/python # PYTHON_PATH also worksThe server bind address can be changed with NPCSH_SERVER_HOST and NPCSH_SERVER_PORT.
If startup fails with failed to spawn npcpy.serve or npcpy server did not become reachable after spawn, the selected Python does not have npcpy installed, or the port is already taken by a stale server process.
brew install ollama
brew services start ollama
ollama pull qwen3.5:2b# Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen3.5:2bInstall Ollama, then use the install script from PowerShell via WSL, or install with cargo.
cd rust
cargo build --release
cp target/release/npcsh ~/.npcsh/bin/npcsh
cp target/release/npc ~/.npcsh/bin/npcFor normal use, install the pre-built release via the install script or cargo. The source build is for development only.
On first run, npcsh creates ~/.npcshrc:
export NPCSH_CHAT_MODEL=qwen3.5:2b
export NPCSH_CHAT_PROVIDER=ollama
export NPCSH_DEFAULT_MODE=agent
export NPCSH_EMBEDDING_MODEL=nomic-embed-text
export NPCSH_EMBEDDING_PROVIDER=ollamaAPI keys can go in ~/.npcshrc, ~/.bashrc, or a project .env:
export OPENAI_API_KEY="your_key"
export ANTHROPIC_API_KEY="your_key"
export GEMINI_API_KEY="your_key"
export DEEPSEEK_API_KEY="your_key"The agent layer can be written in three formats. They can be mixed; .npc files take precedence if names collide.
.npc files — full-featured YAML agent definitions:
#!/usr/bin/env npc
name: analyst
primary_directive: You analyze data and provide insights.
model: qwen3:8b
provider: ollama
jinxes:
- skills/data-analysisagents.md — multiple agents in one markdown file:
## summarizer
You summarize long documents into concise bullet points.
## fact_checker
You verify claims against reliable sources and flag inaccuracies.agents/ directory — one .md file per agent:
---
model: gemini-2.5-flash
provider: gemini
---
You translate content between languages while preserving tone and idiom.All formats inherit the team's default model/provider from team.ctx when not specified.
Full guides and API reference at npc-shell.readthedocs.io.
Discord | Monthly donation | Merch | Consulting: info@npcworldwi.de
Contributions welcome! Submit issues and pull requests on the GitHub repository.
MIT License.
