The agentic shell for building and running AI teams from the command line.

npcsh makes the most of multi-modal LLMs and agents through slash commands and interactive modes, all from the command line. Build teams of agents, schedule them on jobs, engineer context, and design custom Jinja Execution templates (Jinxes) for you and your agents to invoke.

pip install 'npcsh[lite]'

Once installed, run npcsh to enter the NPC shell. Also provides the CLI tools npc, wander, spool, yap, and nql.

.npc and .jinx files are directly executable with shebangs (#!/usr/bin/env npc):

npc ./myagent.npc "summarize this repo"     # run an NPC with a prompt
npc ./script.jinx bash_command="ls -la"     # run a jinx directly
./myagent.npc "hello"                       # or just execute it (with shebang)

How well can a model drive npcsh as an agentic shell? 125 tasks across 15 categories — from basic shell commands to multi-step workflows, code debugging, and tool chaining — scored pass/fail. Comparisons with other agent coders coming soon.

python -m npcsh.benchmark.local_runner --model qwen3:4b --provider ollama

• Get help with a task:

  npcsh>can you help me identify what process is listening on port 5337?

• Edit files:

  npcsh>please read through the markdown files in the docs folder and suggest changes

• Search & Knowledge

  /web_search "cerulean city"            # Web search
  /db_search "query"                     # Database search
  /file_search "pattern"                 # File search
  /memories                              # Interactive memory browser TUI
  /kg                                    # Interactive knowledge graph TUI
  /nql                                   # Database query TUI

  

• Computer Use

  /computer_use

  

• Generate Images

  /vixynt 'generate an image of a rabbit eating ham in the brink of dawn' model='gpt-image-1' provider='openai'

  

• Generate Videos

  /roll 'generate a video of a hat riding a dog' veo-3.1-fast-generate-preview  gemini

  

• Multi-Agent Discussions

  /convene "Is the universe a simulation?" npcs=alicanto,corca,guac rounds=3

  

• Serve an NPC Team

  /serve --port 5337 --cors='http://localhost:5137/'

npcsh supports multiple ways to define agents inside your npc_team/ directory. You can mix all three formats — .npc files take precedence if names collide.

.npc files — Full-featured YAML agent definitions with model, provider, jinxes, and more:

#!/usr/bin/env npc
name: analyst
primary_directive: You analyze data and provide insights.
model: qwen3:8b
provider: ollama
jinxes:
  - skills/data-analysis

agents.md — Define multiple agents in a single markdown file. Each ## heading = agent name, body = directive:

## 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. Filename (minus .md) = agent name. Supports YAML frontmatter:

---
model: gemini-2.5-flash
provider: gemini
---
You translate content between languages while preserving tone and idiom.

All three formats are supported by both the Python and Rust editions of npcsh. Agents from agents.md and agents/ inherit the team's default model/provider from team.ctx.

The full team structure:

npc_team/
├── team.ctx           # Team config (model, provider, forenpc, context)
├── coordinator.npc    # YAML agent definitions
├── analyst.npc
├── agents.md          # Markdown-defined agents
├── agents/            # One .md file per agent
│   └── translator.md
├── jinxes/            # Workflows and tools
│   ├── research.jinx
│   └── skills/        # Knowledge-content skills
└── tools/             # Custom tool functions

This means you can bring agents from other ecosystems — if you already have an agents.md or an agents/ directory from Claude Code, Codex, Amp, or any other tool, just drop them into your npc_team/ and npcsh will pick them up alongside your .npc files.

Your npc_team/ works beyond npcsh — you can launch any major AI coding tool as an NPC from your team using the CLI launchers from npcpy. Each tool gets the NPC's persona injected and gains awareness of the other team members.

pip install npcpy   # if not already installed

# Launch Claude Code as an NPC (interactive picker)
npc-claude

# Launch as a specific NPC
npc-claude --npc corca

# Same for other coding tools
npc-codex --npc researcher
npc-gemini --npc analyst
npc-opencode --npc coder
npc-aider --npc reviewer
npc-amp --npc writer

# Point to a specific team directory
npc-claude --team ./my_project/npc_team

The launcher discovers your team from ./npc_team or ~/.npcsh/npc_team, lets you pick an NPC, and starts the tool with that NPC's directive. For Claude Code, it also passes the other NPCs as sub-agents via --agents.

For deeper integration (jinxes exposed as MCP tools, team switching mid-conversation), register the NPC plugin:

npc-plugin claude    # install MCP server + hooks
npc-plugin codex     # same for Codex
npc-plugin gemini    # same for Gemini CLI

• Agents (NPCs) — AI agents with personas, directives, and tool sets
• Team Orchestration — Delegation, review loops, multi-NPC discussions
• Jinxes — Jinja Execution templates — reusable tools for users and agents
• Skills — Knowledge-content jinxes with progressive section disclosure
• NQL — SQL models with embedded AI functions (Snowflake, BigQuery, Databricks, SQLite)
• Knowledge Graphs — Build and evolve knowledge graphs from conversations
• Deep Research — Multi-agent hypothesis generation, persona sub-agents, paper writing
• Computer Use — GUI automation with vision
• Image, Audio & Video — Generation via Ollama, diffusers, OpenAI, Gemini
• MCP Integration — Full MCP server support with agentic shell TUI
• API Server — Serve teams via OpenAI-compatible REST API

Works with all major LLM providers through LiteLLM: ollama, openai, anthropic, gemini, deepseek, openai-like, and more.

pip install 'npcsh[lite]'        # API providers (ollama, gemini, anthropic, openai, etc.)
pip install 'npcsh[local]'       # Local models (diffusers/transformers/torch)
pip install 'npcsh[yap]'         # Voice mode
pip install 'npcsh[all]'         # Everything

sudo apt-get install espeak portaudio19-dev python3-pyaudio ffmpeg libcairo2-dev libgirepository1.0-dev
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen3.5:2b

brew install portaudio ffmpeg pygobject3 ollama
brew services start ollama
ollama pull qwen3.5:2b

API keys go in a .env file:

export OPENAI_API_KEY="your_key"
export ANTHROPIC_API_KEY="your_key"
export GEMINI_API_KEY="your_key"

A native Rust build of npcsh is available — same shell, same DB, same team files, faster startup. Still experimental.

cd npcsh/rust && cargo build --release
cp target/release/npcsh ~/.local/bin/npc   # or wherever you want

Both editions share ~/npcsh_history.db and ~/.npcsh/npc_team/ and can be used interchangeably.

Full documentation, guides, and API reference at npc-shell.readthedocs.io.

• npcpy — Python framework for building AI agents and teams
• Incognide — Desktop workspace for the NPC Toolkit (download)
• Newsletter — Stay in the loop

• Quantum-like nature of natural language interpretation: arxiv, accepted at QNLP 2025
• Simulating hormonal cycles for AI: arxiv

Discord | Monthly donation | Merch | Consulting: [email protected]

Contributions welcome! Submit issues and pull requests on the GitHub repository.

MIT License.