🌑 NightShade

The open-source, terminal-based AI coding agent powered by Mistral AI

A Claude Code-style agentic CLI that reads, edits, and runs your code — running entirely on Mistral models (Devstral, Codestral, Mistral Large).

---

What is NightShade?

NightShade is a free, open-source AI coding agent for your terminal — an autonomous pair programmer that lives in your shell, understands your codebase, and edits files and runs commands to complete real engineering tasks. Think of it as an open-source Claude Code alternative that runs on Mistral AI instead of Anthropic's models.

Point it at a task in plain English and NightShade will read the relevant files, plan the work, make surgical edits (with reviewable diffs), run your tests, and iterate until it's done — asking your permission before touching anything that matters.

nightshade "add input validation to the signup form and write a test for it"

Why NightShade?

• 🧠 Powered by Mistral — uses Devstral (agentic coding), Codestral (fast code generation), and Mistral Large (reasoning), with smart routing and one-command switching.
• 🔓 Truly open source (MIT) — no proprietary bundle, no telemetry, no lock-in. Read every line.
• 🇪🇺 EU-friendly — run on Mistral's European models for data-residency-conscious teams.
• 🛠️ Real agent, real tools — reads, writes, and edits files, searches your repo, and runs shell commands in a proper tool-calling loop.
• 🔐 Permission-first & safe — approval prompts before edits and commands, four permission modes, dangerous-command guardrails, and a read-only plan mode.
• 📋 Plans like a pro — built-in task tracking so you can watch multi-step work progress in real time.
• 🎨 Clean terminal UX — streaming responses, colored diffs, and collapsed tool summaries.
• 🪶 Zero runtime dependencies — a small, auditable TypeScript codebase.

Features

Capability	Details
Agentic loop	Streaming, multi-step tool-calling against the Mistral API until the task is complete.
File tools	read_file, write_file, edit_file, multi_edit — with colored diff previews before every change.
Search tools	glob (file matching) and grep (content search) to navigate any codebase.
Shell	bash tool with timeouts, output capture, and safety checks.
Web tools	web_fetch (URL → readable text) and web_search (Tavily/Brave/DuckDuckGo).
Subagents	task tool delegates well-scoped work to a fresh child agent with shared cost accounting.
Task tracking	todo_write renders a live checklist for multi-step work.
Permissions	default, acceptEdits, plan, and bypassPermissions modes; per-tool allow/deny rules that persist.
MCP support	Connect any Model Context Protocol server via .mcp.json — its tools become NightShade tools.
Hooks	PreToolUse / PostToolUse / UserPromptSubmit / Stop shell hooks; a hook can block an action.
Sessions	Every run is saved; resume with --continue / --resume / /resume.
Cost & context	Live token/cost tracking (/cost), plus auto-compaction and /compact to stay within the context window.
Custom commands	Drop .nightshade/commands/*.md files to define your own /slash commands with $ARGUMENTS, @file, and !`cmd`.
Settings	Layered settings.json (user → project → local) for permissions, env, hooks, and MCP servers.
Memory	Loads NIGHTSHADE.md / CLAUDE.md project + user memory files, with @import support; /init generates one.
Model routing	devstral, codestral, large aliases, switchable mid-session with /model.
Two modes	Interactive REPL and one-shot (nightshade "task") for scripts and CI.
Tested	Zero-dependency node:test suite covering the core modules (npm test).

Installation

# Clone
git clone https://github.com/Anicodeth/nightshade.git
cd nightshade

# Install & build
npm install
npm run build

# (Optional) install globally so `nightshade` is on your PATH
npm link

Requires Node.js ≥ 18 (Node 20+ recommended for native streaming).

Setup

Get a free API key from the Mistral console, then either export it or drop it in a .env file:

# .env
MISTRAL_API_KEY=your_key_here
NIGHTSHADE_MODEL=devstral   # optional: devstral | codestral | large

Usage

Interactive session

nightshade

nightshade › refactor utils/date.ts to use date-fns and update the callers

One-shot (great for scripts & CI)

nightshade "fix the failing test in auth.test.ts"
nightshade -m codestral "generate a REST client for the API in openapi.yaml"
nightshade --plan "outline how you'd migrate this project to TypeScript"

Command-line options

Flag	Description
-m, --model <name>	Model: devstral, codestral, large, or any Mistral model id.
-c, --continue	Resume the most recent session for this directory.
--resume [id]	Resume a specific session (lists sessions if no id given).
--plan	Read-only planning mode — NightShade won't change anything.
--accept-edits	Auto-approve file edits (still asks before shell commands).
--yes	Bypass all approval prompts (use with care).
-h, --help	Show help.

Slash commands (interactive)

Command	Description
/model <name>	Switch the active model.
/mode <name>	Switch permission mode (default / acceptEdits / plan / bypassPermissions).
/cost	Show token usage and estimated cost.
/compact	Summarize and shrink the conversation context.
/resume [id]	List past sessions, or resume one by id.
/init	Generate a NIGHTSHADE.md for the current project.
/todos	Show the current task list.
/clear	Reset the conversation.
/help	Show help.
/exit	Quit.

Any .nightshade/commands/<name>.md file adds a custom /<name> command.

Permission modes

NightShade never edits files or runs commands behind your back. Choose how much it asks:

• default — asks before any file change or shell command.
• acceptEdits — auto-approves file edits, still asks before running commands.
• plan — read-only; NightShade researches and proposes a plan but changes nothing.
• bypassPermissions — runs freely without prompts (for trusted, sandboxed environments).

Approvals you mark as "always" are saved to .nightshade/settings.local.json so you're not asked twice for the same thing.

Project memory

Drop a NIGHTSHADE.md (or reuse an existing CLAUDE.md) in your repo to give NightShade persistent context — conventions, architecture notes, commands to run. It's loaded automatically and supports @import of other files.

How it compares

NightShade is inspired by the developer experience of Claude Code, rebuilt from scratch as an independent open-source project on Mistral models. It is not affiliated with or derived from Anthropic's Claude Code — it's a clean-room implementation under the MIT license.

Architecture

src/
├── index.ts        # CLI entry: REPL, one-shot, slash commands, approval prompts, wiring
├── agent.ts        # The agentic tool-calling loop (usage, hooks, subagents, compaction)
├── mistral.ts      # Mistral API client (streaming + non-streaming, usage capture)
├── tools.ts        # Built-in tools: read/write/edit/multi_edit/glob/grep/bash/todo/task
├── webtools.ts     # web_fetch and web_search tools
├── mcp.ts          # MCP client: .mcp.json, stdio JSON-RPC, remote tools
├── permissions.ts  # Permission modes, allow/deny rules, safety guardrails
├── hooks.ts        # PreToolUse/PostToolUse/UserPromptSubmit/Stop shell hooks
├── settings.ts     # Layered settings.json loading + env injection
├── commands.ts     # Custom slash commands (.nightshade/commands)
├── session.ts      # Session persistence (save/load/list/resume)
├── context.ts      # Token/cost tracking + context compaction
├── memory.ts       # NIGHTSHADE.md / CLAUDE.md memory loading with @imports
├── diff.ts         # Colored unified-diff renderer
├── config.ts       # Config, model routing, .env loading
└── ui.ts           # Terminal styling

tests/              # node:test suite (npm test)

MCP (Model Context Protocol)

NightShade can use any MCP server. Create a .mcp.json in your project:

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
  }
}

On startup, NightShade connects to each server, discovers its tools, and exposes them as mcp__<server>__<tool> — gated by the same permission system as built-in tools.

Hooks

Automate actions around the agent via .nightshade/settings.json:

{
  "hooks": {
    "PreToolUse": [{ "matcher": "bash", "command": "./scripts/audit-command.sh" }]
  }
}

A PreToolUse hook that exits with code 2 blocks the tool call — useful for policy enforcement, secret scanning, or command auditing.

Testing

npm test

A zero-dependency node:test suite covers the diff renderer, permission engine, cost tracking, tools (including glob/edit/multi_edit), memory, sessions, custom commands, hooks, and MCP config parsing.

Roadmap

• Session persistence & resume
• Cost/token tracking (/cost)
• MCP (Model Context Protocol) server support
• Subagents (task tool)
• Hooks (pre/post tool-use)
• Web fetch & search tools
• MCP over HTTP/SSE + OAuth
• Background/parallel subagents
• Checkpointing & /rewind
• Vim mode & @-mention typeahead

Contributing

Contributions are welcome! Open an issue or PR. Please keep the codebase dependency-light and the tools well-documented.

License

MIT © Anicodeth

---

Keywords: Mistral AI coding agent · open-source Claude Code alternative · Devstral CLI · Codestral · terminal AI coding assistant · AI pair programmer · agentic coding tool · LLM developer tools · autonomous code editor