Prerequisites for Running Freebuff: Complete Setup Guide

To run Freebuff, you need the Bun runtime (for all development tasks), npm with Node.js (for global CLI installation), Docker (for local development with databases and browsers), Git (for repository cloning), and a configured .env.local file for environment variables.

Freebuff is a TypeScript monorepo developed by CodebuffAI that provides CLI tooling for AI-assisted coding workflows. Understanding the prerequisites for running Freebuff ensures you can build the SDK, execute the full test suite, and deploy the CLI without encountering environment-related failures. This guide references specific files from the repository to provide authoritative setup instructions.

Core Runtime Dependencies

Bun (Required)

Bun serves as the primary JavaScript/TypeScript runtime and package manager for Freebuff. All build scripts, test commands, and development workflows depend exclusively on Bun rather than Node.js.

According to the README.md (lines 21-30), the repository uses Bun for every critical operation:

• bun install – Installs monorepo dependencies
• bun up – Updates packages
• bun test – Executes the test suite across packages
• bun start-cli – Launches the interactive CLI from source

Install Bun using the official installer:

curl https://bun.sh/install | bash

npm and Node.js (Required for Global Installation)

While Bun handles development, npm remains necessary for global CLI distribution. The README.md (lines 24-27) documents the global installation method:

npm install -g freebuff

This command installs the compiled binary to your system path, allowing you to invoke freebuff from any directory. Node.js must be present on your system to support npm operations, even if Bun executes the runtime code.

Local Development Infrastructure

Docker (Optional but Recommended)

Docker is required for full local development according to CONTRIBUTING.md (lines 81-83). The CI pipeline and local test suites spin up external services including databases and browser environments that depend on containerization.

The file scripts/ci/bun-test-failures.ts executes bun test across packages with Docker-dependent service orchestration. Without Docker, you cannot run integration tests that validate database connectivity or browser automation features.

Start Docker Desktop (or your system daemon) before executing:

bun test

Environment Configuration (.env.local)

A minimal .env.local file supplies placeholder values for environment variables consumed by the SDK and test suites. As documented in docs/testing.md (lines 9-15), CI expects this file to exist before running any test commands.

The repository includes templates within packages/*/bunfig.toml that preload sdk/test/setup-env.ts. Create your local environment file:

touch .env.local

Populate it with placeholder values required by the specific packages you intend to build, typically including API keys and database connection strings for testing.

System Requirements

Git

Git is mandatory for repository cloning and for agents that execute Bash scripts within the Freebuff ecosystem. The WINDOWS.md guide (lines 19-26) explicitly mentions installing Git for Windows to ensure proper Bash support on Windows environments.

Clone the repository:

git clone https://github.com/CodebuffAI/freebuff.git
cd freebuff

Operating System Support

Freebuff supports Linux and macOS natively. For Windows development, the repository provides specific instructions in WINDOWS.md for running via Git Bash or Windows Subsystem for Linux (WSL). Native Windows CMD or PowerShell without WSL is not recommended due to Bash script dependencies throughout the build pipeline.

Step-by-Step Installation

Follow these steps to satisfy all prerequisites and run Freebuff from source:

1. Install Node.js (includes npm):

   # Verify installation
   
   node --version
   npm --version

2. Install Bun:

   curl https://bun.sh/install | bash

3. Clone and navigate to the repository:

   git clone https://github.com/CodebuffAI/freebuff.git
   cd freebuff

4. Install dependencies:

   bun install

5. Configure environment (create empty placeholder):

   touch .env.local

6. Build the SDK (required before CLI usage):

   bun run build:sdk

7. Build the Freebuff binary (optional, for packaged CLI):

   bun run build:freebuff

8. Run the CLI:

   # From source
   
   bun start-cli
   
   # Or install globally
   
   npm install -g freebuff
   freebuff

Summary

• Bun is the mandatory runtime for development, testing, and building the TypeScript monorepo.
• npm/Node.js enables global installation of the freebuff CLI binary.
• Docker is required for running the complete test suite and developing features that depend on external services like databases.
• .env.local must exist in the repository root to satisfy CI and development environment requirements.
• Git is required for repository operations and Bash script execution across all platforms.
• Windows users must use Git Bash or WSL due to Bash dependencies in build scripts.

Frequently Asked Questions

Can I run Freebuff without Docker?

You can build the SDK and run basic CLI commands without Docker, but you cannot execute the full test suite. According to CONTRIBUTING.md, local development requires Docker for services that CI spins up, including database containers and browser environments. Without Docker, bun test will fail on integration tests.

Is Bun strictly required, or can I use Node.js?

Bun is strictly required for development workflows. While npm installs the global CLI package, all repository scripts in package.json and build processes invoke bun commands. Node.js alone cannot execute the monorepo's build pipeline or test suite.

What environment variables need to be in .env.local?

The specific variables depend on which packages you are building. The docs/testing.md file indicates that .env.local supplies values for the SDK and test suites, typically including API endpoints and service credentials. The repository includes templates in packages/*/bunfig.toml that reference sdk/test/setup-env.ts for automatic loading.

How do I install Freebuff on Windows?

Windows development requires Git for Windows (providing Bash support) or WSL. The WINDOWS.md file provides explicit instructions for Git Bash setup, Docker configuration, and proxy handling. Do not attempt to build using native Windows CMD, as the build scripts rely on Bash commands throughout the pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}