npcsh

Everything in npcsh is defined via plain files organized into three layers. This allows for easy versioning in git and portability across projects.

1. Context Layer

Files: .ctx, team.ctx, or npc_team/*.ctx
Purpose: Defines shared team context, including default models/providers, environment variables, and MCP servers.

2. Agents Layer

Files: .npc, agents.md, or an agents/ directory
Purpose: Defines agent identities, including their name, persona, directive, model/provider, and available jinxes. You can use any of these file formats as alternatives.

3. Tools Layer

Files: .jinx or skills/
Purpose: Contains reusable tools and workflows (called jinxes) that agents can invoke by name.

Skills are a specialized type of jinx that serve knowledge content and instructional methodology instead of executing code. They use the skill.jinx sub-jinx to return structured information on demand.

Key Characteristics:

• They are not a separate system; they live in jinxes/skills/ and are loaded through the same compiler as regular jinxes.
• They appear in the jinxes_dict alongside all other jinxes.
• Agents access them via the same jinxes: list in .npc files used for standard jinxes.
• When an agent calls a skill, it receives content (methodology/instructions) rather than the output of code execution.

A project consists of three layers: team context, agents, and tools. You can organize them in two main ways:

1. Directory-based layout (npc_team/)

Best for structured teams. Tools are kept in a jinxes/ directory.

./npc_team/
├── team.ctx            # team-level context
├── example1.npc        # agent definition
├── example2.npc
└── jinxes/             # tools
    └── example.jinx

2. Flat layout

Best for simpler projects. Agents can be defined in a single agents.md file or an agents/ directory.

./
├── team.ctx            # team-level context
├── agents.md           # many agents in one file
└── jinxes/             # tools
    └── example.jinx

Note: If both layouts are present, npcsh will prompt you to choose a preferred layout on the first run and save the choice in .NPCSH_PREFERRED_TEAM_NAME.

The easiest way to install npcsh is via the official installation script. This script downloads both the npcsh and npc binaries for your platform into ~/.npcsh/bin.

After running the script, ensure ~/.npcsh/bin is in your PATH to run the commands from anywhere.

# Run the install script
curl -fsSL https://enpisi.com/install-npcsh.sh | sh

# Add to PATH
export PATH="$HOME/.npcsh/bin:$PATH"

# Start npcsh
npcsh

The recommended way to author a skill is to create a folder in jinxes/skills/ containing a SKILL.md file. The folder name determines the skill name.

Directory Structure:

jinxes/skills/skill-name/
  SKILL.md
  scripts/          # Optional
  references/       # Optional
  assets/           # Optional

SKILL.md Requirements:

• Must include YAML frontmatter with a description.
• Must use ##-delimited sections for the content.

Example SKILL.md:

---
description: Deployment checklist. Use when asked about deploying or releasing.
---
# Deployment

## pre-deploy
- Run full test suite
- Check for env var changes

## deploy
- Tag the release
- Deploy to staging first

Follow these standards to ensure a readable and useful project history:

Commit Structure

• Line 1: An imperative summary (e.g., "Add user search") under 72 characters.
• Line 3+: Explain the WHY behind the change. Avoid describing what changed, as the code diff already shows that.

Best Practices

• Ensure each commit contains exactly one logical change. Do not mix refactors with new features.
• If the project uses Conventional Commits, use the following prefixes:
  • feat: for new features
  • fix: for bug fixes
  • chore: for maintenance tasks

feat: add user search
fix: handle null avatar URL
chore: bump eslint to v9

The easiest way to install npcsh is using the official install script. This script downloads the latest npcsh and npc Rust binaries into ~/.npcsh/bin, updates your shell PATH, and assists with the installation of the npcpy Python backend.

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

The weak-writing-generator is a skill designed to generate paired weak and strong technical writing examples. These pairs are intended for training and preference optimization, specifically for storage and reuse in GRPO (Group Relative Policy Optimization) or DPO (Direct Preference Optimization) fine-tuning workflows.

source_jinx: npcsh/npc_team/jinxes/skills/weak-writing-generator.jinx

Once inside the npcsh shell, you can interact with the system using natural language, agent delegation, or built-in slash commands.

• Natural Language: Ask questions directly (e.g., what process is listening on port 5337?).
• Agent Delegation: Use the @ prefix to delegate tasks to a specific agent (e.g., @corca refactor the auth module).
• Git TUI: Use the /gitt command to open the Git TUI after making changes.

npcsh
npcsh> what process is listening on port 5337?
npcsh> @corca refactor the auth module and add tests
npcsh> /gitt

In npcsh, you can interact with different agents using two primary patterns: switching the active agent for the entire session or asking a one-off question.

• Switch Agent: Use /<agent> to change the current session's active agent.
• One-off Question: Use @<agent> to direct a specific question to an agent without changing the current session context.

Example usage:

npcsh> @corca refactor the auth module and add tests
npcsh> @alicanto summarize the last three papers on transformers

If you prefer using Rust's package manager, you can install the npcsh and npc binaries directly from crates.io.

cargo install npcsh