Install freecode on macOS or Windows

freecode is a coding agent that runs in your terminal. You describe a task, and it can read and edit your project files, explain code, and run commands. Sponsor cards help cover the cost, so you can start without a paid subscription or a model API key.

Free access has a daily usage limit. If you reach it, freecode tells you when access resets. Your code stays yours; see the privacy policy for how session data is processed.

1. Check your computer

The npm installer supports macOS on Apple silicon and Intel, and Windows on x64. Linux and Windows on ARM are not currently supported by this installer.

Install a current LTS version of Node.js, which includes npm. Then open Terminal on macOS, or PowerShell in Windows Terminal on Windows. Run these commands separately:

node --version
npm --version

Both should print a version number. If a command is not found, finish installing Node.js and open a new terminal window before continuing.

2. Install freecode

Run this command in your terminal. It installs the freecode-sh npm package and makes the freecode command available.

Wait for the installation to finish. Then check that the command works:

freecode --version

3. Open a project folder

Start with a new folder so the agent has a clear workspace. Run each line separately; these commands work in macOS Terminal and Windows PowerShell.

mkdir my-first-project
cd my-first-project
freecode

Follow the sign-in instructions shown by freecode. Keep the terminal open while completing any browser step. For an existing project, use cd to enter its folder before starting the agent.

4. Give it a small, specific task

For an empty folder, try a simple local website:

Create a single index.html file for a personal homepage. Include my name, a short introduction, and links to three projects. Use placeholder text where you need my details. Keep it self-contained, with no external libraries. Explain how I can open it in my browser.

Tell the agent what you expect to see, then check the files and open the result yourself. For a project with interactive behavior and a concrete test checklist, follow the reading-list tutorial.

If something goes wrong

“npm” or “freecode” is not found

Open a new terminal after installation. If npm works but freecode does not, check that your npm global executable directory is on your PATH. The npm folder documentation explains where global executables are installed.

The npm install reports a permissions error

Follow npm’s permissions guide to fix your Node installation or global directory. Avoid changing ownership of unrelated system folders.

The agent does not open normally

Use an interactive terminal. On Windows, try PowerShell in Windows Terminal instead of Git Bash. Run the diagnostic command and read the reported checks:

freecode doctor

If you still need help, visit the freecode community with your operating system, freecode version, and the error message. Remove credentials and private project details before sharing diagnostic output.