Configuration

Configuration — Title: Configuration

# Configuration

## `config.json`

Stores persistent configuration across runs: the API key saved via `/setkey`, the active provider/model, the list of `mcp_servers` (see [[MCP Integration]]), custom permissions, and so on. Read/written via `load_config()` / `save_config()`.

## `AGENTS.md` — per-project rules

`AGENTS.md`, placed in the project directory, declares conventions, build/test/lint commands, directory structure, and gotchas the agent needs to know when working in that project — essentially an additional system prompt scoped per project.

### Auto-generate with `/init`

/init

Process:
1. Scans the current directory structure (up to 3 levels deep).
2. Detects common config files: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`, `requirements.txt`, `setup.py`, `pom.xml`.
3. If `AGENTS.md` already exists, reads the first 2000 characters to improve it instead of blindly overwriting.
4. Calls the model to generate content covering: project overview, build/test/lint commands, key directory structure, code conventions, important setup notes.
5. Writes the result directly to `AGENTS.md` in the current directory.

### View active rules

/rules

Shows up to the first 1500 characters of the `AGENTS.md` currently applied by the agent. If no file exists, suggests running `/init`.

> Real example: this project's own `.fw_data/AGENTS.md` applies the **Simplicity First** principle, editing rules tied to the module map, the `# ##== NAME ==##` section marker pattern, and Termux environment notes (`--break-system-packages`, no `sudo`). See [[Architecture]] for details.

## Checkpoints

/checkpoint [label]

Saves the current progress state of the conversation (optionally labeled). The system also **automatically creates a checkpoint** when the user hits `Ctrl+C` mid-turn (`KeyboardInterrupt`), with a note saying "User interrupted agent turn; saved messages are intact." — ensuring no progress is lost on interruption.

## File cache

/cache debug # view cache details /cache off # disable cache /cache clear # clear the current cache

The cache avoids re-reading unchanged files repeatedly within a session, and supports provider-side prompt caching (stable cache key, delta injection — see `_build_cache_block` in `09_api_system.py`) to reduce token cost when context repeats across turns.

## Tokens & cost

/tokens

Shows current token usage and estimated cost. Sessions automatically **compact context** at around **~80k tokens**, which can also be triggered manually earlier with `/compact`.

## API key

/setkey # save or change the key (empty Enter to clear) /deletekey # remove the saved key entirely

Prefer the matching environment variable (see [[Providers]]) when running in a shared/CI environment; `/setkey` is better suited for personal use on your own machine/Termux.

➡️ Related: [[Permissions & Sandbox]] · [[Custom Commands]] · [[Slash Commands]]