blackhole — the terminal half of Galaxy Blackhole: a coding agent you can run in any repository, plus the launcher for the Galaxy Blackhole web GUI. Published identity is @galaxy-stack/blackhole-cli; the binary is blackhole.

The agent loop, context assembly, tool execution, approvals, checkpoints and completion evidence live in @galaxy-stack/ai-coder-core. This package owns the terminal surface (React 19 + Ink 7) and the web launcher, and nothing else.

Install

npm i -g @galaxy-stack/blackhole-cli@latest
blackhole doctor      # key, model, and whether Ollama is reachable
blackhole chat        # start working

Node.js >= 22.13 is required (the optional SQLite adapter for memory uses node:sqlite, which may print an experimental warning on older runtimes).

Commands

blackhole chat                      Interactive terminal UI (default)
blackhole web [options]             Open the Galaxy Blackhole web GUI
blackhole doctor                    Check the API key and whether Ollama is reachable
blackhole run "task" [--json]       One task; --json writes a single final result
blackhole flow <file.json>          Run sequential prompts in one session and log each step
blackhole skills [show <id>]        Discover or inspect skills
blackhole skills search <query>     Search a configured skill index
blackhole skills install <id>       Install a skill (--skill-version <range>)
blackhole skills update             Update installed skills
blackhole skills remove <id>        Remove an installed skill
blackhole mcp                       Connect configured servers and list tools
blackhole mcp login <server>        Browser login for an HTTP server with auth=oauth
blackhole mcp logout <server>       Forget stored OAuth tokens for a server
blackhole memory search <query>     Recall confirmed workspace notes
blackhole memory list               List notes, including candidates
blackhole memory consolidate        Prune superseded revisions and orphan vectors
blackhole memory remember <key> <text>  Store a user-confirmed note
blackhole memory confirm <key>      Confirm the current candidate
blackhole memory history <key>      Show revisions and provenance
blackhole memory forget <key>      Delete all revisions of a key
blackhole sessions                  List conversation sessions
blackhole logs [n]                  Show the last n runtime log entries (default 20)
blackhole setup                     Ask for the Galaxy API key (--reset to enter a new one)
blackhole config migrate            Consolidate provider keys into ~/.galaxy/credentials.yaml
blackhole config doctor             Check the shared credential document and its mirror
blackhole config path               Print where credentials, config, and backups live
blackhole update                    Update blackhole to the newest version on npm

Every command takes --workspace <dir>; chat, run and flow also accept --model, --base-url, --profile coding|assistant|research, --session <id>, --thinking <level>, --approval full|balanced, --state-dir <outside-workspace>, --agent-config <json>, --no-galaxy-mcp, --skills-dir, --skills-index and the embedding flags. blackhole chat --continue resumes the newest session of this workspace.

Credentials

There is one credential document: ~/.galaxy/credentials.yaml, with one reference per provider (galaxy → GBH_GALAXY_API_KEY). Every host — this CLI, the web GUI, and the VS Code extension — reads it first, so a key entered anywhere is usable everywhere.

blackhole resolves the Galaxy key in this order:

GBH_GALAXY_API_KEY in the environment,
OLLAMA_API_KEY in the environment,
the shared document ~/.galaxy/credentials.yaml (ref GBH_<PROVIDER>_API_KEY),
the legacy mirror ~/.galaxy/config.json → agent[type=manual].apiKey, which is copied into the shared document on the way through, so it is needed at most once,
the web runtime's own store under the gbh home.

blackhole doctor prints the key masked, names which of those sources answered, then probes GET /api/tags and calls POST /api/chat with the active model. Its exit code is the verdict a script can read:

exit	meaning	what to do
0	key, model and network are fine	the failure is elsewhere (for example the web GUI)
1	no key in any store	run `blackhole setup`, or enter it in the web dialog
2	Ollama is unreachable	a proxy or firewall is in the way; no key can help
3	the key was refused (401/403)	enter it again
4	another answer	the body is printed

blackhole config path prints exactly which files are in play, and blackhole config doctor checks that the shared document and the legacy mirror agree.

The web GUI

blackhole web starts the Galaxy Blackhole web GUI from the overlay in web/: the patches under web/patches add the Galaxy route and UI, and the client package in web/brand supplies the brand, the Vietnamese locale, the key dialog, the session tools, the Journey panel (an n8n-style canvas over <workspace>/journey.json), and the reasoning-effort control.

The CLI needs the DSH runtime for this; it ships as an optional dependency (@deepseek-ai/dsh@0.1.5-rc.3), so a normal install starts it through node — no global install and no Windows .cmd shim in the way. GBH_DSH_BIN overrides the choice.

Two commands report on it, from different angles:

blackhole doctor — the model side: key, endpoint, reachability.
blackhole web doctor [--json] — the launcher side: which DSH runtime answered, whether the bundled patches are present, and where the key comes from.

If the brand client cannot be installed (on Windows a directory symlink needs privileges, so the launcher falls back to a junction and then to a copy), the brand patch is dropped with a warning and the GUI still starts. A missing key never stops the server either: the page loads and the in-app dialog asks for the key.

Thinking levels

Reasoning effort belongs to the system and the model, not to the CLI. Ollama takes its think field as a boolean or the levels low/medium/high/max, while other systems expose a different set, so blackhole chat resolves the list per model and shows it as Galaxy Blackhole · Auto · Mức suy luận: …:

Mặc định sends no think field at all, so the model keeps its own default.
A probe that reports no thinking hides the control; a model that requires thinking (for example kimi-k2.7-code) drops Tắt; a model whose capability is unverified keeps the levels and reports a warning.
--thinking accepts auto|default|off|on|minimal|low|medium|high|xhigh|max, validated against the resolved list; an unsupported choice fails and names what that model does offer.

Declare your own levels per model in ~/.galaxy/config.json when the built-in list does not fit (same shape as the web overlay):

{
  "agent": [{
    "type": "manual",
    "model": "my-model:cloud",
    "thinking": "low",
    "reasoningEfforts": { "off": null, "low": "low", "max": "max" }
  }]
}

Inside the TUI: Ctrl+T cycles the effort, Ctrl+M picks a model, Ctrl+H shows or hides the thinking transcript, Ctrl+O toggles tool details.

Terminal UI

The TUI uses the terminal's alternate screen, with a pinned header, a bottom input and a scrollable center. While a run is active, an animated label reports Connecting, Thinking, Responding, Running tools or Validating, next to a live tool line.

Key	Action
Enter	Send the request
Esc	Cancel the active request
Ctrl+C	Exit and restore the terminal
Mouse wheel / trackpad over messages	Scroll the transcript using terminal mouse reporting
↑ / ↓, PageUp / PageDown	Scroll by a line / page (Fn+↑ / Fn+↓ on compact Mac keyboards)
Ctrl+G	Return to the latest output and resume following it
Ctrl+T	Show/hide provider thinking
Ctrl+O	Expand/collapse tool details; pending calls include their arguments
← / →, Home / End, Ctrl+A / Ctrl+E	Edit the input without moving the transcript
Delete / Backspace, Fn+Delete	Delete the previous / next grapheme (including Vietnamese accents and emoji)
Ctrl+U / Ctrl+W	Delete input before the cursor / previous word

Approval stays above the input and accepts y/n. It expires after at most five minutes (or earlier if the run ends). Scratch directories do not need git init: the host detects Git availability, and outside a repository review_changes compares snapshots instead.

--profile coding retains the workspace inspection and completion guarantees; assistant and research allow tasks that do not touch the workspace.

Providers

The working adapter is Ollama, local or cloud. An existing manual-provider entry in ~/.galaxy/config.json is picked up as-is; blackhole setup writes a new one. Base URL, model and credentials are all overridable per run with --base-url, --model and the environment.

MCP

Explicit host configuration is read from ~/.galaxy/agent.json or --agent-config:

{
  "mcpServers": [
    { "name": "project", "transport": "stdio", "command": "my-mcp-server", "args": [], "timeoutMs": 30000 },
    { "name": "remote", "transport": "http", "url": "http://127.0.0.1:8080/mcp" }
  ]
}

Stdio commands execute only when a configured server is connected, and tool names are namespaced. Remote HTTP servers can use browser OAuth: set "auth": "oauth" on the connection and run blackhole mcp login <server>. The CLI also ships the first-party orbit and nebula servers and uses them by default; skip them with --no-galaxy-mcp.

Skills and memory

Skills are discovered in ~/.agents/skills/<name>/SKILL.md and <workspace>/.agents/skills/<name>/SKILL.md. Host state defaults to ~/.galaxy/agent/ and must be outside the selected workspace; override with --state-dir.

Memory uses SQLite WAL + FTS5 with revision checks, provenance and supersession. Explicit CLI notes are confirmed; model-written notes stay candidates until blackhole memory confirm.

Runtime logs

Every command writes JSON lines to <state-dir>/logs/cli-<date>.ndjson (0600, rotated at 5 MB, keeping recent segments) and blackhole logs [n] reads them back. Session history resumes with --session or --continue; simultaneous writers to the same session are rejected.

End-to-end verification

blackhole flow <file.json> runs the prompts of a flow sequentially in one session and one workspace, which is how this package is verified:

Every step streams to step-NN-<id>.ndjson as it happens, plus a compact progress.log (bounded, secret-free tool arguments), so a multi-hour run can be tailed and diagnosed.
scripts/e2e-report.mjs <run-root> summarises a run and flags what a passing step can hide: a step that never called its expected tool, component files written with no scaffold call, a whole-project check run through the shell, servers left running, evidence ordered after the last write, duplicate calls inside one turn.
--flow-from <step-id> and --flow-until <step-id> resume or bound a run in the same session, workspace and state; --flow-step-retries <n> retries a step that hit a transport outage or the host deadline. The report is written even when the run dies, and records fatal, resumedFrom, stoppedAfter, skippedSteps and retriedSteps, so a crash can never read as a pass.
--max-turns <n> and --run-minutes <n> raise the per-run budget (48 model turns, and a deadline of 24 minutes interactive or 30 non-interactive) for steps that need more.

Development

cd ../galaxy-ai-coder-core && npm ci && npm run build
cd ../galaxy-code && npm ci
npm run check                                  # core build + typecheck + tests + bundle
npm run dev -- chat --workspace /path/to/project

A source checkout symlinks the sibling core into node_modules (node_modules/@galaxy-stack/ai-coder-core -> ../../../galaxy-ai-coder-core), so the local core's dist/ must be built before this package typechecks. The manifest itself pins the published version, which is what a release installs.

Releases run through publish.yml (GitHub Actions with npm OIDC trusted publishing) and fire on every push to main, so a merged change is a published version.

Testing and migration

npm run check
cd ../galaxy-ai-coder-core/testing
npm ci
npm run test:local
npm run dev -- health --live --scenario live/scenarios/01-write-and-validate.json --json

eval, campaign, health, run --fixture and their live scenarios live in galaxy-ai-coder-core/testing. The older doctor in that package is unrelated to blackhole doctor here, which checks this product's key and endpoint.

Input and activity feedback

The composer positions the native terminal caret so the terminal's IME preedit appears inside the input. Delete on macOS and word motions follow the platform's grapheme rules. A single blank terminal row below the footer is reserved for Ink's render newline, which avoids native cursor drift.

For a terminal protocol regression on macOS/Linux, run python3 scripts/verify-tui-input.py with pyte installed.