Get started with freecode: web, desktop, and terminal

freecode is a free AI coding agent for web, desktop, and terminal. You describe a task, and it can read and edit 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.

Choose where to start

• Web: open freecode.sh, describe a project, and choose Start coding. Follow the sign-in prompts when asked. Use Connect GitHub if you want to select an existing repository; review the requested repository permissions before connecting.
• Desktop preview: the downloads page has builds for Apple silicon Macs and Windows x64. These are preview releases for limited testing, with manual installation and updates.
• Terminal: follow the steps below to work in a local project folder. You do not need the desktop app.

1. Check your computer

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

Install version 22.18 or later 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.

freecode login
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. Check that the installed command can start:

freecode --version

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

Update or uninstall the npm command

To update an npm installation, run npm install -g freecode-sh again, then run freecode login. Your project folders are preserved; conversations from older installations are not imported. If an older command still opens, check your PATH and remove it using its original installer.

To remove the npm command, run npm uninstall -g freecode-sh. See the downloads page for standalone terminal and desktop installation instructions.