NPC-Worldwide/npcsh

npcsh – a composable multi‑agent shell

What it is – npcsh is a command‑line interface that lets you type ordinary Bash commands or natural‑language requests. Under the hood it routes the request to a language‑model‑powered “agent” which can run shell commands, call tools, or invoke custom Jinja‑based jinxes (templates) you define. In short, it turns an LLM into an interactive shell assistant.

Key ideas

• Agents – defined in .npc YAML, markdown, or per‑file agents/ formats. Each agent has a name, a primary directive, and optional model/provider overrides.
• Jinxes – reusable Jinja templates that encode prompts, tool‑calls, or scripts. Agents invoke them as “skills”.
• Context layer – a npcsh.ctx file holds user‑defined keys that persist across updates, enabling custom instruction hooks.
• Provider‑agnostic – works with any model supported by LiteLLM (Ollama, LM Studio, OpenAI, Anthropic, Gemini, DeepSeek, Minimax, etc.).
• Benchmark – a built‑in suite evaluates how well a model can drive the shell across 100 tasks; scores for many popular models are listed in the README.

Installation

1. Quick script (recommended) –

   curl -fsSL https://enpisi.com/install-npcsh.sh | sh
   

   This installs the Rust binaries (npcsh, npc) and sets up the Python backend (npcpy).
2. Cargo – cargo install npcsh (if you prefer building from source).
3. Python backend – pip install npcpy (required for the inference loop; will be replaced by a Rust runner in the future).

First‑run configuration – a ~/.npcshrc is created with sensible defaults, e.g.:

export NPCSH_CHAT_MODEL=qwen3.5:2b
export NPCSH_CHAT_PROVIDER=ollama
export NPCSH_DEFAULT_MODE=agent

You can add API keys for OpenAI, Anthropic, Gemini, etc., in the same file or any shell rc.

Typical workflow

npcsh> what process is listening on port 5337?
# LLM‑agent runs `lsof -i :5337` and returns the answer.

npcsh> @corca refactor the auth module and add tests
# The `@corca` agent (defined in your team) receives the request, generates code changes, runs them, and can open the Git TUI.

npcsh> /git
# Opens an integrated Git text‑UI for reviewing commits.

Commands prefixed with / are built‑in shell shortcuts (/update, /sync, /git, …).

Extending npcsh

• Add skills – drop a Jinja file under npc_team/jinxes/skills/ and compile it with the skill macro.
• Create agents – write a .npc file or markdown entry describing a new role (e.g., a data‑analysis analyst) and reference its skills.
• Custom context keys – edit ~/.npcsh/npc_team/npcsh.ctx with any non‑reserved key; the value will be available to all agents.

Documentation & community

• Full docs: https://npc-shell.readthedocs.io
• Discord chat, donation link, merch, and consulting contact are listed in the README.

License – MIT.

---

Bottom line – npcsh is a real, open‑source Rust/Python project that lets you interact with LLM‑backed agents directly from the terminal, providing a programmable, extensible environment for command‑line automation, coding assistance, and multi‑step workflows.