@burtson-labs/bandit-stealth-cli 1.7.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Burtson Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+<a href="https://burtson.ai">
+  <picture>
+    <img src="https://cdn.burtson.ai/logos/bandit-stealth.png" alt="Bandit Stealth" width="140" style="width: 140px !important; max-width: 140px !important; height: auto; display: inline-block;" />
+  </picture>
+</a>
+
+# Bandit — Agent CLI
+
+**Local-first AI coding agent for your terminal.**
+
+Your code never leaves your machine. Works with any Ollama model.
+
+*Prefer an IDE?* The sibling Bandit Stealth extension for VS Code / Cursor ships the same runtime, skills, and tool-use loop — install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=BurtsonLabs.bandit-stealth) or [Open VSX](https://open-vsx.org/extension/BurtsonLabs/bandit-stealth).
+
+[![npm](https://img.shields.io/npm/v/%40burtson-labs%2Fbandit-stealth-cli?logo=npm&color=cb3837)](https://www.npmjs.com/package/@burtson-labs/bandit-stealth-cli)
+[![node](https://img.shields.io/node/v/@burtson-labs/bandit-stealth-cli.svg)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+<p>
+  <img src="https://cdn.burtson.ai/images/cli.png" alt="Bandit CLI boot banner in a terminal" width="780" />
+</p>
+
+---
+
+## Install
+
+1. Install **[Ollama](https://ollama.com)** and pull a model:
+
+   ```bash
+   brew install ollama                       # or download installer
+   ollama pull qwen2.5-coder:7b              # fast, tool-calling, ~4.7 GB
+   ```
+
+2. Install the CLI globally:
+
+   ```bash
+   npm i -g @burtson-labs/bandit-stealth-cli
+   ```
+
+3. Run it:
+
+   ```bash
+   bandit                                     # interactive REPL
+   bandit "explain @src/auth/login.ts"        # one-shot with a file mention
+   ```
+
+That's it. No API keys. No cloud services. The agent reads your code, searches, runs commands, and writes changes — all locally.
+
+---
+
+## What it does
+
+- **Agentic tool use** — automatically reads files, searches code, runs commands, writes changes
+- **Unified-diff approval gate** — every `write_file` / `apply_edit` shows a colored diff before touching disk
+- **Pre-write validation** — TypeScript, Python, JSON, C# are syntax-checked before the agent can write them
+- **Skills system** — the agent activates specialized skills based on your prompt, and can create its own
+- **Plan execution** — structured multi-step plans for complex refactors
+- **Session persistence** — every REPL session saved as JSONL under `~/.bandit/sessions/` for later resume
+- **Project memory** — drop a `BANDIT.md` or `CLAUDE.md` at your workspace root and it's auto-loaded into the system prompt
+- **File + image mentions** — `@path` auto-inlines files; images are either sent multimodally or OCR'd locally (Apple Vision / tesseract)
+- **Clipboard paste** — `Ctrl+V` in the REPL pastes an image straight from your clipboard
+- **Hooks** — `PreToolUse` / `PostToolUse` / `Stop` shell hooks via `.bandit/settings.json`
+
+---
+
+## Slash commands
+
+| Command | Does |
+|---|---|
+| `/help` | List slash commands |
+| `/clear` | Reset conversation (keeps session id) |
+| `/model <name>` | Switch model mid-session |
+| `/skills` | List loaded skills |
+| `/session list` / `resume <id>` / `new` | Manage sessions |
+| `/memory` | Show auto-loaded `BANDIT.md` / `CLAUDE.md` |
+| `/config` | Show effective config (secrets redacted) |
+| `/exit` | Quit |
+
+---
+
+## Skills
+
+The agent activates specialized skills based on your prompt:
+
+| Skill | Trigger | What it does |
+|---|---|---|
+| Filesystem | always | Read, write, search, list, run commands |
+| Git | always | Status, diff, log, commit |
+| Code Review | "review my changes" | Diff + full file context |
+| Testing | "write tests" | Auto-detect runner, generate tests |
+| Planning | "refactor the auth system" | Structured multi-step decomposition |
+| Semantic Search | "how is auth implemented" | Local embedding search |
+
+### Custom skills (the agent can make its own)
+
+Ask: *"create a skill that runs my linter"*
+
+The agent writes `.bandit/skills/linter.md`. Next prompt, it's live. Ask *"lint my code"* and it runs.
+
+---
+
+## Recommended models
+
+Pull one with `ollama pull <model>`. Bandit auto-detects each model's capabilities and takes the native tool-calling path when supported.
+
+| Model | Where | Notes |
+|---|---|---|
+| `qwen2.5-coder:7b` | Local / Mac (~4.7 GB) | **Fast default** — native tool calling, strong coding quality. |
+| `gemma4:26b` | Local / Mac 32GB+ (~17 GB) | Sane default for recent Macs — fast, solid quality. |
+| `gemma4:31b` | Local / Mac 64GB+, GPU node | Bigger context, better reasoning. |
+| `qwen2.5-coder:32b-instruct-q8_0` | Local / Mac 48GB+, RTX 5090 | **Best for agents** — native tool calling, strong coding quality. |
+| `qwen2.5-coder:14b-instruct-q8_0` | Local / Mac (~18 GB), 24GB GPUs | Lighter Qwen — native tool calling, fast. |
+| `devstral:latest` | Local / Mac 32GB+ | Mistral's agent-tuned model — excellent tool use. |
+
+**Capability dispatch**:
+
+- **Native tool calling** — Qwen 2.5 Coder, Llama 3.1+, Devstral, DeepSeek-Coder-V2+. Tool schemas go in Ollama's `tools:` field. Saves ~1500–3000 tokens per turn.
+- **Text-parsing fallback** — Gemma 3/4 and anything else. XML-style tool block lives in the system prompt with the full mitigation stack armed.
+
+Any Ollama model works — capabilities auto-detect via `/api/show`.
+
+---
+
+## Configuration
+
+### Config file (preferred)
+
+`~/.bandit/config.json` or `<workspace>/.bandit/config.json`:
+
+```jsonc
+{
+  "provider": "ollama",                       // or "bandit"
+  "model": "qwen2.5-coder:7b",
+  "ollama": {
+    "url": "http://localhost:11434",
+    "headers": { "Authorization": "Bearer ..." }  // optional
+  },
+  "bandit": {
+    "apiKey": "bnd_...",
+    "apiUrl": "https://api.burtson.ai"
+  }
+}
+```
+
+Workspace config overrides user config. Secrets belong in the user-level file, not in a committed workspace file.
+
+### Environment variables
+
+| Var | Default | Description |
+|---|---|---|
+| `BANDIT_PROVIDER` | `ollama` | `ollama` or `bandit` |
+| `BANDIT_MODEL` | `gemma4:e4b` | Model ID |
+| `BANDIT_API_KEY` | — | Required when `BANDIT_PROVIDER=bandit` |
+| `BANDIT_API_URL` | `https://api.burtson.ai` | Override Bandit API endpoint |
+| `OLLAMA_URL` | `http://localhost:11434` | Ollama endpoint |
+| `BANDIT_MAX_ITERATIONS` | `20` | Tool-use loop cap |
+| `BANDIT_AUTO_APPROVE` | `0` | `1`/`true` to skip write-approval prompts |
+| `NO_COLOR` | — | Disable ANSI colors |
+
+### Remote GPU
+
+Running a bigger model on a remote Ollama instance? Point `OLLAMA_URL` at the remote endpoint and set `BANDIT_MODEL` to the bigger model. Requests route to the remote node; everything else stays local.
+
+---
+
+## Security & privacy
+
+- **Local-first by default** — with `provider=ollama`, nothing leaves your machine.
+- **Approval gate** — all file writes show a unified diff before touching disk (unless `BANDIT_AUTO_APPROVE=1`).
+- **Command allowlist** — `run_command` only executes from an internal allowlist (git, gh, kubectl, helm, brew, standard *nix tools). Arbitrary shell is refused.
+- **Secret hygiene** — API keys are redacted in `/config` output and never logged.
+- **Local sessions** — stored as JSONL under `~/.bandit/sessions/`. Inspect at any time.
+
+---
+
+## Requirements
+
+- Node.js 20+
+- [Ollama](https://ollama.com) running locally (or remote via `OLLAMA_URL`) — unless you use `BANDIT_PROVIDER=bandit`
+- `rg` (ripgrep) on `PATH` for fast code search; falls back to `grep` if absent
+
+---
+
+## Troubleshooting
+
+**Ollama not detected** — Make sure it's running: `ollama serve`. The CLI checks on startup and surfaces a setup hint if it can't connect.
+
+**Model not installed** — Pull it: `ollama pull <model>`. Run `/model <name>` in the REPL to switch without restarting.
+
+**Slow responses** — Check your model size against available VRAM. Switch to a smaller model from the recommended list.
+
+**Stuck approval prompt in CI** — Set `BANDIT_AUTO_APPROVE=1` to skip the diff-approval gate.
+
+---
+
+## Support
+
+- Issues, feature requests, and questions: [team@burtson.ai](mailto:team@burtson.ai)
+- More from Burtson Labs: [burtson.ai](https://burtson.ai)
+
+*Bandit CLI is built by [Burtson Labs](https://burtson.ai). Source for the runtime packages is currently private — open source release planned.*