Galaxy Blackhole CLI

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      # check the API key and the connection
blackhole web         # open the Galaxy Blackhole web GUI
blackhole chat        # start working

Node.js >= 22.13 is required.

Commands

blackhole chat                      Interactive terminal UI (default)
blackhole web [options]             Open the Galaxy Blackhole web GUI
blackhole doctor                    Check the API key and the connection
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.

API key

One key, one place: ~/.galaxy/credentials.yaml. Enter it once with blackhole setup, or in the web GUI's dialog, or in the VS Code extension — all three read the same document, so a key entered anywhere works everywhere. Setting GBH_GALAXY_API_KEY in the environment also works if you would rather not store it on disk.

blackhole doctor prints the key masked, says which source answered, and then checks that the model actually replies:

| 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 | the provider 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.

The web GUI

blackhole web opens the same agent in a browser: threaded sessions per workspace, the key dialog, the session tools, and a Journey panel — a canvas over <workspace>/journey.json that the agent edits in place while you watch the run progress.

The GUI starts even before you have a key: the page loads and the dialog asks for one, and a launcher problem is reported as a warning rather than a failure to start.

blackhole doctor checks the model side; blackhole web doctor reports on the launcher itself.

Thinking levels

Reasoning effort belongs to the system and the model, not to the CLI: a provider takes the think field as a boolean or as levels such as low/medium/high/max, and different systems expose different sets, 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 default provider is auto — Galaxy Blackhole resolves it to its own model, deepseek-v4.1-flash, local or cloud; you never pick a vendor. blackhole chat shows it as Galaxy Blackhole · auto · Mức suy luận …. 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.