Installation — free-code

Supported platforms

free-code runs on Linux and macOS.

Read this first — what the installer does (and doesn't) do
The install script sets up the command-line app (CLI). On macOS it also installs the desktop app. The VS Code / Cursor plugin is NOT installed by the script — it's a short, separate step you do by hand afterwards (see Install the VS Code / Cursor plugin below).

Platform	Installer script	What the script sets up	Editor plugin
Linux	`installation/install-free-code-linux.sh`	CLI + dependencies	Manual — see below
macOS	`installation/install-free-code-mac.command`	CLI + desktop app (FreeCodeMac)	Manual — see below

Both scripts live in the installation/ folder of the repository.

Linux — install the CLI

One script installs the free-code command-line app and everything it needs.

This installs the CLI only. Want to use free-code inside VS Code or Cursor? Do the quick plugin step after this.

Step 1 — Run the install script

bash /<path/to/repo>/installation/install-free-code-linux.sh

The script sets up everything you need to run free-code on Linux:

Step	What it installs
Node.js (LTS)	nvm + latest LTS; set as default
Dependencies	`npm install` at repo root
free-code CLI	`npm install -g ./packages/coding-agent`
agent-browser	`npm install -g agent-browser`
RAG (optional)	Python venv for the local knowledge-base server

Step 2 — Start free-code

Run the CLI in your terminal:

free-code

Step 3 — Configure your AI provider

You only need one provider to get started:

# Login (Claude, GitHub Copilot, Gemini, and others)
/login

# Or set an API key for your provider, e.g.
export ANTHROPIC_API_KEY=sk-...

# Iniciar sesión (Claude, GitHub Copilot, Gemini, y otros)
/login

# O configura una clave de API para tu proveedor, por ejemplo
export ANTHROPIC_API_KEY=sk-...

Tip
Add any export line to your ~/.bashrc or ~/.zshrc so it persists across terminal sessions.

Consejo
Agrega cualquier línea de export a tu ~/.bashrc o ~/.zshrc para que persista entre sesiones de terminal.

macOS — install the CLI & desktop app

One script installs everything: Homebrew, Node.js, dependencies, the CLI, and the native desktop app.

Before you start
Close VS Code, Cursor, or any other IDE before running the script.

This installs the CLI and the desktop app. The VS Code / Cursor plugin is a separate step — do the quick plugin step afterwards if you want it.

Step 1 — Run the install script

Option A — double-click in Finder:

open /<path/to/repo>/installation

Double-click install-free-code-mac.command in that folder.

Option B — from the terminal:

bash /<path/to/repo>/installation/install-free-code-mac.command

The script handles everything automatically:

Step	What it installs
Homebrew	Installs if not present
Colima	Container runtime (via Homebrew)
Node.js (LTS)	nvm + latest LTS; set as default
Dependencies	`npm install` at repo root
free-code CLI	`npm install -g ./packages/coding-agent`
agent-browser	`npm install -g agent-browser`
FreeCodeMac.app	Copies the `.app` bundle to `/Applications`

Step 2 — Start Free-Code

Open FreeCodeMac from /Applications, or run in the terminal:

free-code

Step 3 — Configure your AI provider

Set the API key for your chosen provider. You only need one to get started.

# Login (Claude, GitHub Copilot, Gemini, and others)
/login

# Google Vertex AI
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

# Iniciar sesión (Claude, GitHub Copilot, Gemini, y otros)
/login

# Google Vertex AI
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

Tip
Add the export line to your ~/.zshrc so it persists across terminal sessions.

Consejo
Agrega la línea de export a tu ~/.zshrc para que persista entre sesiones de terminal.

Install the VS Code / Cursor plugin

Optional. Adds a free-code chat panel inside your editor. Works the same on Linux and macOS.

No terminal needed. You install the plugin from inside VS Code or Cursor by clicking a few buttons. Follow the steps below exactly — you don't need any command line.

What you need first

VS Code or Cursor installed on your computer.
The free-code folder you downloaded (the same one where the install script lives). Inside it there is a plugin file at:
packages/vscode-free-code/vscode-free-code-0.66.1.vsix
A .vsix file is just the packaged plugin.

Step 1 — Open the Extensions panel

Open VS Code or Cursor. On the left side bar, click the Extensions icon (four little squares). Or press:

macOS: Cmd + Shift + X
Linux: Ctrl + Shift + X

Step 2 — Choose “Install from VSIX…”

At the top of the Extensions panel, find the small … (three dots) menu button and click it.
In the menu that opens, click Install from VSIX…

Step 3 — Pick the plugin file

A file picker opens. Go into the free-code folder, then into packages → vscode-free-code, and select:

vscode-free-code-0.66.1.vsix

Click Install. You'll see a small confirmation in the bottom-right corner.

Step 4 — Reload the editor

If a Reload button appears, click it. Otherwise just close and reopen VS Code / Cursor.

Step 5 — Open the free-code chat

Open the Command Palette (Cmd/Ctrl + Shift + P), type free-code, and choose the command to open the chat panel. Type / in the input to see all commands.

Prefer the terminal?
If you're comfortable with the command line, you can install it in one line from inside the free-code folder instead:

# VS Code
code --install-extension packages/vscode-free-code/vscode-free-code-0.66.1.vsix

# Cursor
cursor --install-extension packages/vscode-free-code/vscode-free-code-0.66.1.vsix

CLI only (any platform)

Node.js 20+ required. Works on macOS, Linux, and Windows.

1. Install Node.js 20+

# via nvm (recommended)
nvm install --lts
nvm use --lts

# vía nvm (recomendado)
nvm install --lts
nvm use --lts

2. Install the CLI

npm install -g ./packages/coding-agent

3. Verify

free-code --version

4. Start

free-code                              # interactive
free-code "Summarize this project"     # one-shot
cat README.md | free-code -p "Summarize"  # pipe input

free-code                              # interactivo
free-code "Summarize this project"     # de una sola vez
cat README.md | free-code -p "Summarize"  # entrada por tubería (pipe)

Code graph (optional)

Adds symbol indexing and call graph navigation to the agent.

# From the repository root
npm install -g ./packages/code-graph

# Desde la raíz del repositorio
npm install -g ./packages/code-graph

Once installed, the code_index, code_symbols, code_callers, and code_context tools become available automatically in every session.

First use
Open a project and run /codeGraph-index. The agent will index all .ts / .js files and store the result in .code-graph/ at the project root.

Primer uso
Abre un proyecto y ejecuta /codeGraph-index. El agente indexará todos los archivos .ts / .js y guardará el resultado en .code-graph/ en la raíz del proyecto.

Add .code-graph/ to your .gitignore — the index is regenerated on demand and does not need to be committed.

Code graph full documentation →

Supported platformsPlataformas soportadas

Linux — install the CLILinux — instalar la CLI

Step 1 — Run the install scriptPaso 1 — Ejecuta el script de instalación

Step 2 — Start free-codePaso 2 — Inicia free-code

Step 3 — Configure your AI providerPaso 3 — Configura tu proveedor de IA

macOS — install the CLI & desktop appmacOS — instalar la CLI y la app de escritorio

Step 1 — Run the install scriptPaso 1 — Ejecuta el script de instalación

Step 2 — Start Free-CodePaso 2 — Inicia Free-Code

Step 3 — Configure your AI providerPaso 3 — Configura tu proveedor de IA

Install the VS Code / Cursor pluginInstalar el plugin de VS Code / Cursor

What you need firstLo que necesitas primero

Step 1 — Open the Extensions panelPaso 1 — Abre el panel de Extensiones

Step 2 — Choose “Install from VSIX…”Paso 2 — Elige “Install from VSIX…”

Step 3 — Pick the plugin filePaso 3 — Elige el archivo del plugin

Step 4 — Reload the editorPaso 4 — Recarga el editor

Step 5 — Open the free-code chatPaso 5 — Abre el chat de free-code

CLI only (any platform)Solo la CLI (cualquier plataforma)

1. Install Node.js 20+1. Instala Node.js 20+

2. Install the CLI2. Instala la CLI

3. Verify3. Verifica

4. Start4. Inicia

Code graph (optional)Grafo de código (opcional)

Supported platforms

Linux — install the CLI

Step 1 — Run the install script

Step 2 — Start free-code

Step 3 — Configure your AI provider

macOS — install the CLI & desktop app

Step 1 — Run the install script

Step 2 — Start Free-Code

Step 3 — Configure your AI provider

Install the VS Code / Cursor plugin

What you need first

Step 1 — Open the Extensions panel

Step 2 — Choose “Install from VSIX…”

Step 3 — Pick the plugin file

Step 4 — Reload the editor

Step 5 — Open the free-code chat

CLI only (any platform)

1. Install Node.js 20+

2. Install the CLI

3. Verify

4. Start

Code graph (optional)