Configuration

Where settings live

Settings are flat KEY: "value" pairs in settings.json, in Friday's config directory:

Three ways to change them, all writing the same file:

• In a session: Settings (alt+s or /settings), Providers (alt+p), /key, /model.
• From the shell: friday settings.
• By hand: edit settings.json.

An environment variable with the same name always wins over the file, so a key exported in your shell is used even when the file holds another. The engine reads settings when a session opens; a change applies to the next session.

Choosing the engine

auto is accepted as "nothing set". Anything else is refused with a message.

Providers and keys

A provider is ready when its key (and, for some, its address) is set. Without an explicit choice, Friday uses the provider you used last (ARCHYMEDES_PROVIDER, remembered for you), else the first ready one in this order:

Each provider's settings share a prefix: the id in capitals with - as _ (openai-compatible → OPENAI_COMPATIBLE, free → FREE, so free mode's model is FREE_MODEL).

Free mode never pays. With --free or ARCHYMEDES_PROVIDER=free, only openrouter/free or a model ending in :free is accepted, for the main model, the small model and any role's model. A session that remembered free mode never falls through to a paid provider when the key is gone.

Models

Without a small model, the main model does everything. What runs on which:

Behaviour

Modes are chosen per session (--plan, --build, --auto, --defender, or shift+tab), not by a setting; a resumed session keeps its own.

Command rules

Rules you write once instead of answering the same approval every day. A rule names a command by its first words and says allow (run without asking), ask (always ask, even in auto mode or under a standing approval) or forbid (never run; the model is told your reason).

Two files are read, both optional: .archymedes/rules.json in the project, and rules.json in the config directory.

{
  "rules": [
    { "prefix": ["npm", ["test", "run"]], "decision": "allow" },
    { "prefix": ["git", "push"], "decision": "ask", "reason": "pushes are reviewed",
      "match": ["git push origin main"], "not_match": ["git pull"] },
    { "prefix": ["rm", ["-rf", "-fr"]], "decision": "forbid", "reason": "use trash-put instead" }
  ]
}

• prefix: the command's first words. An element that is a list matches any one of its words.
• decision: allow, ask or forbid.
• reason: shown to the model with a refusal, and to you with a question.
• match / not_match: examples checked when the rules load. A rule whose examples fail is left out, and a line at the start of the session names it and why.
• A compound command (a && b, a | b, a; b) is judged part by part: forbidden if any part is, asked if any part asks, allowed only if every part is allowed.
• In defender mode, allow rules still ask: every change there is looked at.

Your own sub-agent roles

A Markdown file per role, in .archymedes/agents/ in the project or agents/ in the config directory. A file with a built-in role's name replaces it. Full reference: Sub-agents → Writing a role.

---
name: migrations
description: writes and checks database migrations
tools: read_file, grep_files, write_file, edit_file, run_command
readonly: false
model: small
background: false
max-iterations: 20
max-tool-calls: 60
---
You write database migrations for this project. Every migration has a down step…

Project instructions

The first of these files found at the project root is given to the model with every request, as instructions from the people who work there: AGENTS.override.md, ARCHYMEDES.md, AGENTS.md, CLAUDE.md, .archymedesrules. Up to 20,000 characters are used. Sub-agents do not receive it; their brief says what they need.

The interface

Read by the friday binary itself, for what the screen looks like. Each is also a row of Settings (Appearance) unless marked as environment only.

Diagnostics

Every variable, in one table

Key bindings are changed in the Keys app (F7) and saved to keys.json in the config directory.