Halo Scan user guide

What it is

Halo Scan is a Model Context Protocol (MCP) server over stdio. It exposes read-only tools so a model can orient in a repo, navigate by structure and symbols, search code, and inspect git history — without dumping whole files or leaving the workspace root you pass as --cwd.

It has zero npm dependencies at runtime, no account, and no cloud side. Paths are confined to the workspace. There are no write or edit tools, no test runners, and env/config tools return names and structure only — never secret values. It is free for personal, non-commercial use under the Bitfield Creek Labs EULA.

Prerequisites

• Node.js 20+ — required for npm and the CLI
• An MCP host that speaks newline-delimited JSON-RPC over stdio — e.g. Bitfield Ollama Agent, Cursor, or Claude Desktop — or Aura Wire AI Command Center with Enhanced tools (no separate install)
• A workspace folder to scan (--cwd)

Halo Scan uses only Node built-ins at runtime — no extra npm dependencies after install.

Installation

Recommended: install the published package globally so halo-scan is on your PATH.

npm install -g @bitfieldcreek/halo-scan
halo-scan --cwd /path/to/repo

Try without installing

Use npx for a one-off run:

npx @bitfieldcreek/halo-scan --cwd .

Halo Scan is proprietary software — free for personal, non-commercial use. See the Bitfield Creek Labs EULA. Package page: @bitfieldcreek/halo-scan.

First run

The CLI speaks MCP over stdio — you normally attach it to a host rather than typing into it directly.

Bitfield Ollama Agent

bf-agent --mcp "halo-scan --cwd ."

Cursor / other MCP hosts

{
  "mcpServers": {
    "halo-scan": {
      "command": "npx",
      "args": ["-y", "@bitfieldcreek/halo-scan", "--cwd", "."]
    }
  }
}

Ask the host something that needs structure — “what is this repo?”, “where is the main entrypoint?”, “which tests cover Order.total?” — and prefer outline / symbol tools over whole-file reads.

Tools overview

Twenty-six tools are listed. Prefer the entry point that matches the question, then narrow:

• Orient — repo_overview, project_conventions, entrypoint_map, config_surface, dir_digest
• Navigate — file_brief, file_outline, get_symbol, symbol_context, symbol_search, locate, who_imports
• Search — grep_search, find_files, find_symbol, find_references, markers
• Change / quality / read — changed_symbols, git_history, tests_for, test_inventory, unused_exports, http_surface, read_file, list_dir, and related helpers

Unlisted aliases (search, open_file, ls, …) resolve to the canonical tools when those tools are in the active set. Use --tools / --exclude-tools to trim the surface.

Pair with Aura Wire

Halo Scan is standalone — it does not require Aura Wire AI Command Center. Inside Wire, the same package ships as Enhanced tools:

1. Open a chat in the Aura Wire AI Command Center extension.
2. Open Chat options → Tools → Enhanced tools and turn the switch on.
3. On the next turn, Wire starts the bundled halo-scan against your workspace folder. Tools appear as halo-scan › … cards and run as read-only (including in Ask mode).

Enhanced tools also reach delegated agent runtimes (Cursor / Copilot / Claude) through Wire’s client-tools bridge — no separate MCP config. A workspace MCP server also named halo-scan loses on name clashes (the bundle wins).

See the Aura Wire user guide for install and chat setup.

Privacy and data

• Nothing is sent to Bitfield Creek Labs. Halo Scan has no telemetry, no update check, no license call, and no account. Installing from npm contacts the npm registry like any package.
• Read-only and cwd-confined. Tools only read under --cwd. There are no write/edit tools. Config/env helpers return key names and structure — not secret values.
• Your host and model see tool results. Whatever the MCP host forwards to the model (file excerpts, symbol bodies, git metadata) leaves the machine only if that host/model path does. Local Ollama stays local; cloud providers receive what you route to them under their terms.

What installs, and how to remove it

What Halo Scan puts on your machine

• The npm package — @bitfieldcreek/halo-scan in your global (or project) node_modules, with the halo-scan command on your PATH.
• In-memory / mtime caches only while running — no project side-car folder, no services, no system settings.
• Inside Aura Wire AI Command Center — Enhanced tools uses a copy bundled with the extension (dist/halo-scan/); uninstalling the npm package does not remove that bundle. Turn the Enhanced tools switch off, or uninstall the extension, to stop using it there.

How to remove it completely

1. npm uninstall -g @bitfieldcreek/halo-scan (or npm uninstall in a project that installed it locally).
2. Remove any MCP host config that points at halo-scan or the package.
3. In Aura Wire AI Command Center, turn off Enhanced tools if you enabled it.

After these steps nothing from a standalone Halo Scan install remains (the Wire extension may still ship its own bundled copy until you remove the extension).

Troubleshooting

• Host never calls the tools — confirm the MCP server process starts ( halo-scan --cwd . should stay running on stdio). Some hosts hide MCP tools behind a bridge; prefer native MCP registration when possible.
• Path / permission errors — tools refuse paths outside --cwd. Point --cwd at the repo root you intend to scan.
• Enhanced tools unavailable in Wire — the extension build must include the bundled package; if the row is locked, update the extension or reinstall from the download hub.
• Name clash with a workspace MCP server — a server also named halo-scan loses to Wire’s bundle; rename the workspace entry if you need both.