Configuration

Fred reads from three places: your shell environment, your home config, and the project you're in. None of it is required — defaults work on a fresh machine — but every knob is here when you need to pin a model in CI, add a project rule, or wire up an MCP server.

Home directory layout (~/.config/fred/)

After fred login runs once, your home config looks like this:

~/.config/fred/
├── credentials.json     # mode 0600 — auth state
├── preferences.json     # mode 0644 — model + UI prefs
└── rate-card.json       # cached pricing, refreshed from /api/pricing

credentials.json is written by fred login and read on every CLI invocation. Schema:

{
  "version": 1,
  "api_key": "sk-fred-…",        // empty if stored in keychain
  "email": "you@example.com",
  "base_url": "https://api.fredcode.net/v1",
  "fetched_at": "2026-04-30T17:22:11Z"
}

On macOS, if you installed with the [keychain] extra, the API key is mirrored into the system keychain and the api_key field stays empty. The keychain copy wins on read.

preferences.json is written by /model, /flash, /pro, and the once-per-account pro confirmation. Schema:

{
  "version": 1,
  "main_model": "deepseek-v4-flash",
  "editor_model": "deepseek-v4-flash",
  "weak_model": "deepseek-v4-flash",
  "subagent_main_model": null,
  "warned_about_architect": true,
  "preset": "flash",
  "telemetry_opted_out": false
}

rate-card.json is a runtime cache of the pricing JSON served by /api/pricing. Fred refreshes it on startup if it's missing or older than 24 hours. If the cache is more than 7 days old and the network refresh fails, you'll see a one-line staleness warning at session start — billing still works (pricing is computed server-side), but the local cost line may drift.

Environment variables

Every env var the CLI reads, grouped by purpose.

Auth.

Models.

API behavior.

Feature toggles.

Telemetry.

UI.

Prompt.

Project memory: AGENTS.md / CLAUDE.md

At startup, Fred looks for AGENTS.md in the current working directory (and falls back to CLAUDE.mdif it's missing). The contents are injected as a system-prompt addendum every turn, so it's the right place for repo conventions, sharp edges, and things every session should know without you having to repeat yourself.

Good things to put in there:

• House style — "use Drizzle, not raw SQL", "tabs not spaces".
• Sharp edges — "the worker can't import from src/, mirror with sync-pricing.ts".
• Where things live — a one-paragraph map of the package layout.
• What not to touch — "migrations 0001 and 0002 are already in prod".

If both AGENTS.md and CLAUDE.md are present, AGENTS.md wins. Pick one and stick with it.

Project rules: .fred/rules/*.md

Rules are Markdown files inside .fred/rules/ with optional YAML front-matter. They split into three categories based on how they attach:

• Always-on — no front-matter, or alwaysApply: true. Loaded every turn, like an extension of AGENTS.md.
• Glob-triggered — front-matter sets a glob pattern. Auto-attaches the moment a matching file shows up in the turn (read, edited, or grepped).
• Request-only — front-matter has a description but no glob and alwaysApply: false. The model sees the title and description in its tool list and pulls the rule in via the request_ruletool when it decides it's relevant.

Example front-matter:

---
description: Conventions for Drizzle migrations
glob: src/db/migrations/*.sql
alwaysApply: false
---

# Migration rules

- New migrations are numbered 0NNN_<slug>.sql.
- Never edit a migration that has run in prod — write a new one instead.
- ...

See project rules for the full schema and authoring tips.

Hooks and MCP: .fred/settings.json

Per-project hooks (commands the harness runs on lifecycle events) and MCP servers (extra tools Fred can call) both live in .fred/settings.json. Same file, two top-level keys:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "bash", "command": "./scripts/audit.sh" }
    ],
    "Stop": [
      { "command": "npm run lint --silent" }
    ]
  },
  "mcp": {
    "servers": {
      "linear": {
        "command": "npx",
        "args": ["-y", "@linear/mcp-server"],
        "env": { "LINEAR_API_KEY": "lin_api_…" }
      }
    }
  }
}

Hooks let you run lint, audit, or telemetry shell scripts at well-defined points in the loop. MCP gives Fred access to tools beyond the built-ins (issue trackers, databases, your own scripts). Both are loaded once per session — restart the REPL after editing the file.

Drill-down docs: hooks · MCP servers.

Permission rules

Permission rules — "always allow git status", "always deny rm -rf" — live in ~/.fred/settings.local.json. They're per-user, not per-project, because they encode trust decisions you've already made.

Edit them via slash command rather than by hand: /perms add bash "git status", /perms remove bash "git status", or just /permsto list. The in-prompt "Always allow this command?" option writes to the same file.

Full details on the gating model: permissions & yolo.