Reference

Reference pages are complete and boring by design. If a guide explains why, the reference tells you exactly what — every flag, every key, every method signature, checked against the code rather than remembered.

If you are new here, read this page first. It answers the question that sends most people in circles: which file does this setting go in? FreeCode has three configuration surfaces and they are not interchangeable.

The three surfaces

The split is not arbitrary:

• config.json is machine-written state. It holds a secret (your API key) and a cursor (the model you last picked). You can edit it, but the app rewrites it, so it is a poor place for policy you want to keep.
• settings.json is hand-written policy. It has no secrets, so the project copy is meant to be committed and travel with the repository — the permission rules and hooks your team agreed on.
• Environment variables are overrides. They exist for the two cases a file handles badly: one-off debugging (FREECODE_DEBUG=1 freecode …) and CI, where there is no home directory worth persisting to.

Precedence, in one line: environment beats file, and for the two settings files, project beats user — but see the settings page, because each of the three settings sections merges its two scopes by its own rule.

What else lives in ~/.freecode/

Not configuration, but you will meet these directories when debugging or backing up. Everything FreeCode persists is under one root:

freecode uninstall keeps this directory and takes only builds/; the entire directory — your sessions and your memory included — goes only with --purge. See CLI commands.

The pages

For the reasoning behind any of it, the internals section is the companion: IPC protocol, lifecycle hooks, permission engine, memory.