@halcyonlabs/app

中文文档
0.47.0-halcyon.405发布于 2026/11/16SEE LICENSE IN LICENSETypeScriptES Module近 30 天下载 4.4万

bb app launcher for npx

原始使用文档
文档目录11 节
  1. Quick Start
  2. Prerequisites
  3. Supported host environments
  4. Install and run
  5. The bb command
  6. Updating from the app
  7. CLI
  8. Scripting with the SDK
  9. Provider Credentials
  10. Configuration
  11. Further Reading

Moonlet

Moonlet

npm version

Moonlet is an agentic IDE that builds itself. It can control, customize, and automate itself, laying the groundwork for your own software factory.

This package provides the npx -y -p @halcyonlabs/app bb-app launcher, bundled bb CLI entry, and Node SDK export. Every surface — the web app, CLI, and HTTP API — is a first-class way to drive Moonlet. Work runs in threads you can follow live, steer at any point, or hand off to another agent.

Note: Moonlet is in active development. Workflows and surfaces are still evolving.

Quick Start

Moonlet runs from npm and orchestrates coding agents you already have installed.

Prerequisites

  • Node.js 22.19, 24, or 26.
  • Git.
  • At least one supported agent provider: Claude Code, Codex, Cursor via ACP, Pi, or another ACP-compatible agent.

If you already use one of these providers, Moonlet will pick up your existing credentials. If you use multiple providers, you can mix and match per task.

Supported host environments

  • macOS
  • Linux
Windows via Ubuntu on WSL2

Run all bb commands inside WSL2, install Node.js, Git, and your provider CLIs inside that WSL2 distro, and use Linux-style paths such as /home/me/repo or /mnt/c/Users/me/repo.

Inside WSL2, use Linux paths rather than drive-letter or UNC paths. Repos inside the WSL filesystem are recommended; /mnt/c/... is intentionally supported so you can keep an existing Windows checkout, but it is slower and less reliable for file watching.

Install and run

npx -y -p @halcyonlabs/app@latest bb-app

Then open: http://localhost:38886

To opt into the automated nightly channel:

npx -y -p @halcyonlabs/app@nightly bb-app

Nightly versions are built from main and may be unstable. The nightly dist-tag moves independently of the stable latest tag.

npm 12 and later block dependency install scripts by default. Moonlet needs those scripts to build its native add-ons (better-sqlite3, node-pty, @parcel/watcher). Without them Moonlet stops at startup with Could not locate the bindings file. If your npm version is 12 or later, allow the scripts for the install:

npx --allow-scripts=better-sqlite3,node-pty,@parcel/watcher -y -p @halcyonlabs/app@latest bb-app

Or set the policy once for all global installs:

npm config set allow-scripts=better-sqlite3,node-pty,@parcel/watcher --location=user

npx -y -p @halcyonlabs/app@latest bb-app downloads the published @halcyonlabs/app package, starts the server and local host daemon, and serves the web app. It stores Moonlet-managed state under ~/.bb/ by default. If either managed child process exits unexpectedly, the launcher restarts that child without stopping the other one. Press Ctrl+C in the terminal to stop both processes and exit with status 0.

If another live Moonlet owns the runtime record for the same data directory and a healthy server answers on the configured local address, startup exits with status 1 without starting either child process. The existing instance keeps running. A runtime record without a healthy server does not prevent startup.

Application logs rotate in logs/server.N.log and logs/host-daemon.N.log under the data directory, keeping the five newest files per service. Output that bypasses the logger, such as startup errors and crashes, goes directly to logs/server-stdio.log and logs/host-daemon-stdio.log. These files append across restarts; when one is over 10 MB as a service starts, it is renamed to -stdio.1.log, replacing the previous one. The launcher prints status and log locations without forwarding service output to the terminal, so a stalled terminal cannot block service logging. To follow everything with the default data directory:

tail -F ~/.bb/logs/*.log

Launcher status output is plain when stdout is redirected, including in CI. Set FORCE_COLOR=1 to request color or NO_COLOR=1 to disable it; NO_COLOR takes precedence. In-place progress updates require a stdout TTY.

The same output capture applies to bb-server and bb-host-daemon.

To stop a Moonlet install that runs in another terminal or in the background:

npx -y -p @halcyonlabs/app bb-app stop

stop reads bb-app-runtime.json from the data directory, confirms that the recorded process really is that launcher, then stops it. Pass --data-dir when the Moonlet install you want to stop does not use the default ~/.bb/.

The bb command

To control Moonlet from outside Moonlet, open Settings → General → Command line and choose Install next to Moonlet CLI. Threads in Moonlet already have bb; this is for your own terminals, scripts, and agents running outside Moonlet, such as Claude Code or Codex. Moonlet links a launcher from ~/.bb/bin/bb into a folder on your PATH (~/.local/bin on Linux; /opt/homebrew/bin, /usr/local/bin, or ~/.local/bin on macOS). On Windows it adds ~/.bb/bin to your user PATH; open a new terminal afterwards. Remove takes it off again. Moonlet leaves any other bb you already have in place.

From a terminal, before bb is on your PATH:

npx -y -p @halcyonlabs/app bb settings cli-command install

Updating from the app

When Moonlet has an update, Settings → Updates shows an Update button (or run bb updates app apply). Moonlet downloads the new version into ~/.bb/app-versions/, restarts into it, and reconnects the page. Moonlet does not roll back: if the new version fails to start, run a newer release (npx -y -p @halcyonlabs/app@latest bb-app) or fix the cause. Later npx -y -p @halcyonlabs/app bb-app runs use the newer installed version; pass --bundled to run the copy npx downloaded instead. Start Moonlet with --no-in-app-updates to turn in-app updates off.

After the server moves to another machine, the old data directory keeps server-moved.json. bb-app there starts no server: it runs this computer's host daemon against the new server address in config.json, restarting it when it exits, and answers the old server port. API requests get 410 server_moved with the new address; browser pages redirect to it for a direct address or link to it for Moonlet Connect. While a move back to this computer is in progress (server-import.json), it frees that port for the incoming server. When server-moved.json goes away, after that move completes or bb server unlock, it starts the server and co-located daemon again. bb-server exits with status 3 instead of starting, except for the incoming server of a move back.

From the app, add or open a project, start a thread, and choose the provider you want that thread to use.

CLI

The package also exposes the bb CLI for an already-running Moonlet server:

npx -y -p @halcyonlabs/app bb --help

The CLI uses the same BB_SERVER_URL and Moonlet config resolution as the SDK. When unset, it targets the default local packaged server at http://127.0.0.1:38886.

Scripting with the SDK

The package also exposes a Node SDK for scripts that drive an already-running Moonlet server:

import { BBSdk } from "bb-app";

const bb = new BBSdk();
const thread = await bb.threads.spawn({
  projectId: "proj_personal",
  environment: { type: "host", workspace: { type: "personal" } },
  prompt: "Summarize my active bb work.",
});
await bb.threads.wait({ threadId: String(thread.id), status: "idle" });
console.log(await bb.threads.output({ threadId: String(thread.id) }));

new BBSdk() uses the same BB_SERVER_URL and Moonlet config resolution as the CLI. Pass new BBSdk({ baseUrl: "http://host:38886" }) for remote or test targets (see the remote-access note below). Scripts launched by Moonlet already receive BB_SERVER_URL and BB_THREAD_ID in their environment.

Provider Credentials

Moonlet uses whichever providers you have configured. Common providers:

ProviderSetup
codexInstall the Codex CLI. Then run codex login or configure credentials per the Codex docs.
claude-codeInstall Claude Code and authenticate per its docs.
cursorInstall Cursor's agent CLI (cursor-agent) and authenticate per Cursor's docs.
piInstall Pi with npm install -g @earendil-works/pi-coding-agent (0.84.0 or newer) and authenticate per its docs; Moonlet can run the install from Settings.
opencodeInstall opencode and authenticate per its docs.
grokInstall Grok Build and authenticate with grok login or XAI_API_KEY.
hermes-agentInstall Hermes Agent, configure credentials with hermes model, then verify ACP with hermes acp --check.

Moonlet indexes the documented native skill roots for Codex, Claude Code, Pi, Cursor, OpenCode, omp, Grok Build, and Hermes Agent. It includes user roots, project roots, and compatibility roots such as .agents/skills. These skills appear in the selected provider's / command menu. The Skills page and bb skill list show native skills for Claude Code, Codex, and Cursor. Moonlet also reads configured Pi, omp, Grok, and Hermes skill directories, plus enabled provider plugin skills.

Moonlet reads Pi's global ~/.pi/agent files and each workspace's .pi files. This includes settings, credentials, models, packages, extensions, skills, prompts, themes, and context files. Pi extensions can add models and tools. Moonlet loads project resources only after Pi's saved or global trust policy approves the workspace. An unresolved ask decision stays untrusted because Moonlet has no Pi trust prompt. You can still use the Pi CLI and /login to create this configuration.

Custom ACP agents are configured through the ACP providers plugin's customAgents setting: bb plugin config provider-acp set customAgents '[...]'. See the configuration docs for the optional modelCli and reasoningCli or nativeReasoning reasoning settings. The optional nativeSkillRoots field adds provider-native skills to the composer. Its user paths resolve from the target host home directory. Its project paths resolve from the selected workspace. Top-level sharedSkillRoots uses the same user and project path format. Moonlet lists these sources as read-only skills. Moonlet injects them into Codex, Claude, Pi, and ACP threads. This permits one physical skill collection for Moonlet and a standalone provider CLI.

Configuration

Use bb-app config for persistent non-secret package settings under ~/.bb/config.json:

npx -y -p @halcyonlabs/app bb-app config set BB_APP_URL https://<machine>.<tailnet>.ts.net
npx -y -p @halcyonlabs/app bb-app config list
npx -y -p @halcyonlabs/app bb-app config refresh

For remote access, use Moonlet Connect or publish the default loopback listener with Tailscale Serve. Direct tailnet or LAN access to port 38886 requires the explicit, security-sensitive --server-bind-host 0.0.0.0 compatibility option; see the multiple-devices guide.

Use bb-app client ssh-target to configure local editor opens for remote Moonlet servers under ~/.bb/client.json. The target is the value that works after ssh, such as devbox or user@devbox:

npx -y -p @halcyonlabs/app bb-app client ssh-target set https://bb.example.test devbox --host-id host_abc
npx -y -p @halcyonlabs/app bb-app client ssh-target list

Use bb-app env for provider credentials under ~/.bb/env.json:

npx -y -p @halcyonlabs/app bb-app env set OPENAI_API_KEY <key>
npx -y -p @halcyonlabs/app bb-app env list
npx -y -p @halcyonlabs/app bb-app env unset OPENAI_API_KEY

env list redacts all values. Config and env writes ask a running local Moonlet server to reload; if Moonlet is stopped, the values apply on the next start.

For all config keys, precedence, startup flags, and source-development .env behavior, see the configuration docs.

Further Reading

版本与发布记录

@halcyonlabs/app 共发布 212 个版本,首次发布于 2026/10/25;过去 12 个月发布了 212 个版本。

版本发布日期距今
0.47.0-halcyon.405latest2026/11/161 天前
0.47.0-halcyon.4042026/11/161 天前
0.47.0-halcyon.4032026/11/161 天前
0.47.0-halcyon.4022026/11/161 天前
0.47.0-halcyon.4012026/11/151 天前
0.47.0-halcyon.3992026/11/151 天前

关于 @halcyonlabs/app 的常见问题

@halcyonlabs/app 是什么?

bb app launcher for npx

如何安装 @halcyonlabs/app?

在项目目录运行 npm install @halcyonlabs/app,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bb、bb-app、bb-server、bb-host-daemon,可以用 npx bb 直接运行。

@halcyonlabs/app 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@halcyonlabs/app 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@halcyonlabs/app 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js ^22.19.0 || ^24.0.0 || ^26.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@halcyonlabs/app 可以商用吗?

@halcyonlabs/app 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中,请阅读该文件确认可否商用。以上为概括,不构成法律意见,请以许可原文为准。

@halcyonlabs/app 的下载量有多少?

根据 npm 官方下载统计,@halcyonlabs/app 在 2026/10/17 – 2026/11/15 这 30 天内被下载 43,510 次,日均约 1,450 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@halcyonlabs/app 还在维护吗?

最新版本 0.47.0-halcyon.405 发布于 2026/11/16(1 天前);至今共发布 212 个版本,其中过去 12 个月发布了 212 个;首次发布于 2026/10/25。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。