This monorepo contains two main packages: @vybestack/llxprt-code and @vybestack/llxprt-code-core.

@vybestack/llxprt-code

This is the main package for the LLxprt Code. It is responsible for the user interface, command parsing, and all other user-facing functionality.

LLxprt Code runs on the Bun runtime. The published package ships platform-native launchers (packages/cli/bin/llxprt) as its bin entry. On POSIX, a valid #!/bin/sh shebang makes it directly execve-compatible; the launcher resolves the package-local Bun (from the package's own bun dependency, never a global PATH Bun) and execs the TypeScript (.ts) entry point directly. On Windows, the CLI workspace postinstall (packages/cli/scripts/install-native-launchers.cjs) replaces npm's generated cmd-shim with a native .cmd / .ps1 launcher that invokes the same package-local Bun. (The root scripts/postinstall.cjs delegates to this script on Windows after linking internal workspace packages.) No Node process is started on the installed command path. No compilation to JavaScript happens at install or run time, and no pre-compiled dist/ artifact is shipped or required. Type checking uses tsc --noEmit. The esbuild bundle artifact has been retired.

@vybestack/llxprt-code-core

This package contains the core logic for interacting with the Gemini API. It is responsible for making API requests, handling authentication, and managing the local cache.

This package is not bundled. When it is published, it is published as a standard npm package with its own dependencies. This allows it to be used as a standalone package in other projects, if needed. The package ships its TypeScript source (index.ts, src/), which Bun consumers resolve directly via the bun export condition.

Testing uses vitest, which is retained as the test runner.

Release Process

This project follows a structured release process to ensure that all packages are versioned and published correctly. The process is designed to be as automated as possible.

How To Release

Releases are managed through the release.yml GitHub Actions workflow. To perform a manual release for a patch or hotfix:

1. Navigate to the Actions tab of the repository.
2. Select the Release workflow from the list.
3. Click the Run workflow dropdown button.
4. Fill in the required inputs:
   • Version: The exact version to release (e.g., v0.2.1).
   • Ref: The branch or commit SHA to release from (defaults to main).
   • Dry Run: Leave as true to test the workflow without publishing, or set to false to perform a live release.
5. Click Run workflow.

Nightly Releases

In addition to manual releases, this project has an automated nightly release process to provide the latest "bleeding edge" version for testing and development.

Process

Every night at midnight UTC, the Release workflow runs automatically on a schedule. It performs the following steps:

1. Checks out the latest code from the main branch.
2. Installs all dependencies.
3. Runs the full suite of preflight checks and integration tests.
4. If all tests succeed, it calculates the next nightly version number. The base version is taken from package.json for scheduled runs. For manual nightly dispatch (create_nightly_release), the optional version input is used as the nightly base when provided as a stable X.Y.Z or vX.Y.Z; otherwise package.json is used. The resulting tag has the shape vX.Y.Z-nightly.YYMMDD.shortsha (e.g., v0.1.0-nightly.250720.abcdef), where YYMMDD is the UTC date and shortsha is the short commit SHA.
5. It then builds and publishes the packages to npm with the nightly dist-tag.
6. Finally, it creates a GitHub Release for the nightly version.

Failure Handling

If the nightly workflow fails, the notify_failure job creates (or comments on) a GitHub issue labeled ci/cd linking to the failed workflow run. (Release workflow failures create an issue labeled ci/cd as well.) These issues are tracked for debugging rather than being filed as generic bugs.

How to Use the Nightly Build

To install the latest nightly build, use the @nightly tag:

npm install -g @vybestack/llxprt-code@nightly

We also run a Google cloud build called release-docker.yml. Which publishes the sandbox docker to match your release. This will also be moved to GH and combined with the main release file once service account permissions are sorted out.

VS Code Companion toggle inputs

The release workflow now exposes two additional booleans:

• publish_vscode_only: build/publish just the VS Code companion (llxprt-code-vscode-ide-companion) without touching npm packages. Use this for hotfixes to the marketplace / Open VSX extension.
• skip_vscode_publish: skip companion publishing entirely (nightly runs set this to true so the extension isn’t rebuilt every day).

Make sure these inputs are set appropriately before triggering manual releases; nightly automation defaults to "skip" so the IDE extension matches tagged releases only.

After the Release

After the workflow has successfully completed, you can monitor its progress in the GitHub Actions tab. Once complete, you should:

1. Go to the pull requests page of the repository.
2. Create a new pull request from the release/vX.Y.Z branch to main.
3. Review the pull request (it should only contain version updates in package.json files) and merge it. This keeps the version in main up-to-date.

Release Validation

After pushing a new release smoke testing should be performed to ensure that the packages are working as expected. This can be done by installing the packages locally and running a set of tests to ensure that they are functioning correctly.

• npx -y @vybestack/llxprt-code@latest --version to validate the push worked as expected if you were not doing a rc or dev tag
• npx -y @vybestack/llxprt-code@<release tag> --version to validate the tag pushed appropriately
• This is destructive locally npm uninstall @vybestack/llxprt-code && npm uninstall -g @vybestack/llxprt-code && npm cache clean --force && npm install @vybestack/llxprt-code@<version>
• Smoke testing a basic run through of exercising a few llm commands and tools is recommended to ensure that the packages are working as expected. We'll codify this more in the future.

When to merge the version change, or not?

The above pattern for creating patch or hotfix releases from current or older commits leaves the repository in the following state:

1. The Tag (vX.Y.Z-patch.1): This tag correctly points to the original commit on main that contains the stable code you intended to release. This is crucial. Anyone checking out this tag gets the exact code that was published.
2. The Branch (release-vX.Y.Z-patch.1): This branch contains one new commit on top of the tagged commit. That new commit only contains the version number change in package.json (and other related files like package-lock.json).

This separation is good. It keeps your main branch history clean of release-specific version bumps until you decide to merge them.

This is the critical decision, and it depends entirely on the nature of the release.

Merge Back for Stable Patches and Hotfixes

You almost always want to merge the release-<tag> branch back into main for any stable patch or hotfix release.

• Why? The primary reason is to update the version in main's package.json. If you release v1.2.1 from an older commit but never merge the version bump back, your main branch's package.json will still say "version": "1.2.0". The next developer who starts work for the next feature release (v1.3.0) will be branching from a codebase that has an incorrect, older version number. This leads to confusion and requires manual version bumping later.
• The Process: After the release-v1.2.1 branch is created and the package is successfully published, you should open a pull request to merge release-v1.2.1 into main. This PR will contain just one commit: "chore: bump version to v1.2.1". It's a clean, simple integration that keeps your main branch in sync with the latest released version.

Do NOT Merge Back for Pre-Releases (RC, Beta, Dev)

You typically do not merge release branches for pre-releases back into main.

• Why? Pre-release versions (e.g., v1.3.0-rc.1, v1.3.0-rc.2) are, by definition, not stable and are temporary. You don't want to pollute your main branch's history with a series of version bumps for release candidates. The package.json in main should reflect the latest stable release version, not an RC.
• The Process: The release-v1.3.0-rc.1 branch is created, the npm publish --tag rc happens, and then... the branch has served its purpose. You can simply delete it. The code for the RC is already on main (or a feature branch), so no functional code is lost. The release branch was just a temporary vehicle for the version number.

Local Testing and Validation: Changes to the Packaging and Publishing Process

If you need to test the release process without actually publishing to NPM or creating a public GitHub release, you can trigger the workflow manually from the GitHub UI.

1. Go to the Actions tab of the repository.
2. Click on the "Run workflow" dropdown.
3. Leave the dry_run option checked (true).
4. Click the "Run workflow" button.

This will run the entire release process but will skip the npm publish and gh release create steps. You can inspect the workflow logs to ensure everything is working as expected.

It is crucial to test any changes to the packaging and publishing process locally before committing them. This ensures that the packages will be published correctly and that they will work as expected when installed by a user.

To validate your changes, you can perform a dry run of the publishing process. This will simulate the publishing process without actually publishing the packages to the npm registry.

npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME="thename" npm run publish:npm --dry-run

This command will do the following:

1. Build all the packages.
2. Run all the prepublish scripts.
3. Create the package tarballs that would be published to npm.
4. Print a summary of the packages that would be published.

You can then inspect the generated tarballs to ensure that they contain the correct files and that the package.json files have been updated correctly. The tarballs will be created in the root of each package's directory (e.g., packages/cli/google-gemini-cli-0.1.6.tgz).

By performing a dry run, you can be confident that your changes to the packaging process are correct and that the packages will be published successfully.

Release Deep Dive

The main goal of the release process is to take the source code from the packages/ directory, validate it, and publish the CLI package with its platform-native launchers (bin/llxprt) plus the TypeScript sources executed by Bun. No compilation step is required for the published package; the retired bundle/llxprt.js artifact is no longer produced.

Here are the key stages:

Stage 1: Pre-Release Sanity Checks and Versioning

• What happens: Before any files are moved, the process ensures the project is in a good state. This involves running tests, linting, and type-checking (bun run preflight). The version number in the root package.json and packages/cli/package.json is updated to the new release version.
• Why: This guarantees that only high-quality, working code is released. Versioning is the first step to signify a new release.

Stage 2: Validating the Source Code

• What happens: The TypeScript source code (.ts) is type-checked with tsc --noEmit. No JavaScript is emitted for the published package — the native launcher (packages/cli/bin/llxprt) resolves the package-local Bun at run time and Bun executes the TypeScript sources directly. Development builds may still produce local dist/ output for tooling, but the published package does not depend on it.
• Why: The published package ships TypeScript source, so correctness is enforced by type-checking and tests rather than a compilation step.

Stage 3: Preparing the Final Publishable Package

This is the stage where the CLI package is prepared for publishing.

1. The workspace package metadata is validated and transformed as needed:

   • What happens: release scripts ensure the package metadata, dependency ranges, bin, main, and files fields point at the native launcher (bin/llxprt) and the shipped TypeScript sources executed by Bun.
   • Why: The final package must not expose development-only dependencies while still containing the runtime assets needed by npm/npx/Homebrew users.

2. Runtime files are included from the package files allowlist:

   • What happens: packages/cli/package.json ships bin, src, and index.ts while excluding tests and snapshots.
   • Why: bin/llxprt is the POSIX-native launcher entry; it resolves the package-local Bun and execs the TypeScript source directly. On Windows, packages/cli/scripts/install-native-launchers.cjs (run via the CLI workspace postinstall) generates the .cmd / .ps1 launchers that invoke the same package-local Bun.

Stage 4: Publishing to NPM

• What happens: The npm publish command publishes the prepared CLI package.
• Why: Publishing from the package with an explicit files allowlist prevents test files and development-only configuration from being accidentally uploaded while preserving the runtime sources the Bun launcher needs.

Testing uses vitest, which is retained as the test runner.

Summary of File Flow

graph TD
    subgraph "Source Files"
        A["packages/core/src/*.ts<br/>packages/cli/src/*.ts"]
        B["packages/cli/package.json"]
        C["README.md<br/>LICENSE<br/>packages/cli/src/utils/*.sb"]
    end

    subgraph "Process"
        D["Typecheck (tsc --noEmit)"]
        E["Package source + launcher"]
        F["npm pack"]
        G["Publish"]
    end

    subgraph "Artifacts"
        H["packages/cli/bin/llxprt"]
        I["TypeScript source packages"]
        J["npm tarball"]
    end

    subgraph "Destination"
        K["NPM Registry"]
    end

    A --> D
    A --> E --> I
    B --> E --> H
    C --> F
    H --> F
    I --> F
    F --> J
    J --> G --> K

This process ensures that the final published artifact is a purpose-built, clean, and efficient representation of the project, rather than a direct copy of the development workspace.

NPM Workspaces

This project uses NPM Workspaces to manage the packages within this monorepo. This simplifies development by allowing us to manage dependencies and run scripts across multiple packages from the root of the project.

How it Works

The root package.json file defines the workspaces for this project:

{
  "workspaces": ["packages/*"]
}

This tells NPM that any folder inside the packages directory is a separate package that should be managed as part of the workspace.

Benefits of Workspaces

• Simplified Dependency Management: Running bun install from the root of the project will install all dependencies for all packages in the workspace and link them together. This means you don't need to run bun install in each package's directory.
• Automatic Linking: Packages within the workspace can depend on each other. When you run bun install, Bun will automatically create symlinks between the packages. This means that when you make changes to one package, the changes are immediately available to other packages that depend on it.
• Simplified Script Execution: You can run scripts in any package from the root of the project using Bun's --filter flag. For example, to run the build script in the cli package, you can run bun run --filter '@vybestack/llxprt-code' build.

Package-Manager Layout Support (issue #2603)

The installed llxprt command uses platform-native launchers that resolve the package-local Bun runtime directly. Supported package-manager layouts:

Fully Supported (POSIX + Windows)

• npm global (npm install -g @vybestack/llxprt-code): POSIX symlink to the shebang launcher; Windows .cmd/.ps1 generated by packages/cli/scripts/install-native-launchers.cjs.
• npm local (npm install @vybestack/llxprt-code): Same as global, bin link at node_modules/.bin/llxprt.
• npm exec / npx (npx @vybestack/llxprt-code): Temporary install invokes the same launcher.

POSIX-Only (No Windows Wrapper Generation)

• Bun install (bun install -g): Bun's lifecycle script handling differs from npm's. On POSIX, Bun creates a symlink to the shebang launcher which works correctly. On Windows, Bun does not reliably run npm-compatible lifecycle scripts, so the CLI workspace postinstall may not execute. Users on Windows should prefer npm install -g for the full native launcher experience.

Limitations

The packages/cli/scripts/install-native-launchers.cjs postinstall only generates Windows wrappers (it is a no-op on POSIX where the shebang symlink suffices). The wrappers are only written to bin-link directories that can be discovered at install time (npm_config_prefix for global installs with npm_config_global=true, node_modules/.bin for local installs via INIT_CWD). If a package-manager uses a non-standard bin-link location, the POSIX symlink still works, but the Windows wrappers may not be generated. In that case, the npm-generated cmd-shim would be used, which invokes the POSIX launcher's shebang — on Windows this falls back to sh.exe if available, or fails with an error directing the user to reinstall.