# How to Install CodebuffAI/freebuff Locally: Global CLI vs. Development Setup > Install CodebuffAI/freebuff locally! Learn to set up the global CLI with npm or build the TypeScript monorepo for development. Get started quickly. - Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff) - Tags: getting-started - Published: 2026-08-21 --- **Install the Freebuff CLI globally with `npm install -g freebuff` for immediate use, or clone the repository and run `bun install` followed by `bun up` to build the full TypeScript monorepo locally for development.** Freebuff is a **TypeScript monorepo** built with the Bun runtime that provides an agent-powered coding assistant through a terminal-based UI. Whether you want to install the published CLI or contribute to the open-source project, this guide covers the exact steps documented in the [`README.md`](https://github.com/CodebuffAI/freebuff/blob/main/README.md) and [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md) files. ## Global CLI Installation for End Users The simplest way to install CodebuffAI/freebuff locally is through the npm registry. This method installs the pre-built CLI globally on your system without requiring the full source code. Run the following command to install the CLI: ```bash npm install -g freebuff ``` Once installed, navigate to any project directory and launch the agent-powered assistant: ```bash cd freebuff ``` This approach installs the TUI (terminal user interface) built with OpenTUI and React, which is housed in the `cli/` directory of the repository. According to the [`README.md`](https://github.com/CodebuffAI/freebuff/blob/main/README.md) Quick Start section, this is the recommended path for users who want to use Freebuff without modifying its source code. ## Local Development Installation for Contributors Developers who want to modify agents, add tools, or extend the SDK must set up the full monorepo locally. The repository architecture splits functionality across several modules including `cli/`, `sdk/`, `common/`, `agents/`, `packages/agent-runtime/`, and `packages/code-map/`. ### Clone the Repository Start by cloning the GitHub repository and entering the project directory: ```bash git clone https://github.com/CodebuffAI/freebuff.git cd freebuff ``` ### Install Dependencies with Bun Because Freebuff is built specifically for the Bun runtime, you must use `bun` rather than `npm` or `yarn` to install dependencies: ```bash bun install ``` This command pulls in all workspace packages defined across the monorepo structure, as documented in the [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md) file under the Install dependencies section. ### Build and Link Workspace Packages After installation, build all packages and link them within the workspace using: ```bash bun up ``` The `bun up` command compiles the TypeScript sources and establishes internal dependencies between the `sdk/`, `common/`, and `packages/*` directories. This step is essential before running the CLI from source. ### Launch the Local CLI To run the TUI without publishing to npm, use the start-cli script: ```bash bun start-cli ``` As noted in the [`README.md`](https://github.com/CodebuffAI/freebuff/blob/main/README.md) section "Start the CLI separately," this command boots the React-based terminal interface using your local source changes rather than a globally installed package. ## Optional Development Tasks Once you have installed CodebuffAI/freebuff locally, several utility commands help validate your setup or prepare changes for submission. - **Run the test suite**: Execute `bun test` to run all unit and integration tests (see [`cli/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/cli/README.md) → Testing). - **Build the SDK**: Run `bun run build:sdk` to compile the `@codebuff/sdk` package distributed to npm. - **Build the binary**: Run `bun run build:freebuff` to create a standalone binary of the CLI. Some internal services, such as Docker-based development environments, require a `.env.local` file. However, according to the contributing guide, Docker and `.env.local` are only needed for the full suite of backend services; the CLI itself functions after completing the core installation steps above. ## Summary - **End users** should run `npm install -g freebuff` to install the CLI globally and invoke it with the `freebuff` command. - **Contributors** must clone the repository, run `bun install` to fetch dependencies, then `bun up` to build the monorepo workspace. - The `bun start-cli` command runs the local TUI without requiring global installation. - Testing (`bun test`) and building (`bun run build:sdk`) require the full local development setup. ## Frequently Asked Questions ### What is the difference between global and local installation of Freebuff? Global installation via `npm install -g freebuff` provides a ready-to-use CLI for end users who only want to run the agent assistant. Local installation requires cloning the repository and using Bun to install dependencies, which is necessary for developers who need to modify the `sdk/`, `agents/`, or `packages/agent-runtime/` source code. ### Do I need Docker to run Freebuff locally? No. While some internal services documented in [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md) require Docker and a `.env.local` file for the full backend suite, the CLI and core agent runtime work after running `bun install` and `bun up`. Docker is only necessary if you plan to run specific containerized development services. ### How do I run tests after installing Freebuff locally? After completing the local development installation, execute `bun test` from the repository root. This command runs the test suite defined across the monorepo workspaces and is documented in the [`cli/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/cli/README.md) file under the Testing section. ### Can I use npm or yarn instead of Bun to install Freebuff locally? No. Freebuff is built specifically for the Bun runtime, and the monorepo workspace configuration relies on Bun's package manager. You must use `bun install` rather than `npm install` or `yarn` when setting up the development environment locally, though end users can install the published CLI via `npm install -g freebuff`.