Configuration

What lives in ~/.loop, the settings worth knowing, per-project config, and adding a model the catalog doesn't have.

Where things live

~/.loop/
├── auth.json          # provider tokens, custom gateways, bot tokens (mode 600)
├── settings.json      # defaultModel, thinkingLevel, hooks, mcpServers, toggles
├── models.json        # user-added models / catalog overrides
├── catalog.json       # model catalog cache
├── agent.db           # SQLite: session trees, cost ledger, memory, reminders, tasks
├── agents/*.md        # custom agents (and built-in prompt overrides)
├── extensions/        # installed JS extensions
└── agent/
    ├── prompts/*.md   # custom slash commands
    ├── skills/*.md    # auto-registered skills
    ├── themes/*.json  # custom themes
    └── memory/        # per-project durable facts

All config files are plain JSON. Unknown keys are preserved, so editing one key won't disturb the rest.

Per-project config

<repo>/.loop/ holds project settings, hooks, skills, and MCP servers, and overrides the global ones. It's gated by project trust: the first time you open a repo that ships hooks or skills, loop asks before executing anything.

The last model you picked in a folder is remembered per project.

AGENTS.md and CLAUDE.md in a repo load automatically as workspace context. /init writes one by reading the codebase.

Settings worth knowing

/settings toggles these live; they're top-level keys in settings.json.

permissions takes rules over tool calls:

{
    "permissions": {
        "deny": ["Bash(rm -rf *)", "Read(secrets/**)"]
    }
}

Trusted projects can add their own under the same key in <repo>/.loop/settings.json. /permissions manages them from the TUI.

Changing settings by hand needs a hard reload (/reload) to take effect.

Adding a model

If a model isn't in the catalog — a brand-new release, an OpenRouter :free variant, a private deployment — add it via /model → + add model…, or by hand in ~/.loop/models.json:

{
    "openrouter/nex-agi/nex-n2-pro:free": {
        "id": "openrouter/nex-agi/nex-n2-pro:free",
        "provider": "openrouter",
        "name": "Nex AGI: Nex-N2-Pro (free)",
        "contextWindow": 262144,
        "maxOutput": 262144,
        "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
        "reasoning": true,
        "modalities": ["text", "image"],
        "available": true
    }
}

Keys are full provider/model-id ids. Entries merge over the built-in catalog, so the same file also overrides pricing or context windows of models loop already knows.

cost is per million tokens and defaults to 0 — set it if you want cost tracking to bill the model. The id isn't validated up front; a wrong one simply errors on the first request.

The catalog itself refreshes from models.dev hourly, so new public models usually just appear without you doing anything.

Themes

dark and light are built in. Drop pi-mono-format JSON themes into ~/.loop/agent/themes/ and pick one via /settings → theme — it applies live.

Each UI mode keeps its own theme: loop mode uses the theme key, other modes use uiThemes (e.g. { "noir": "day" }).

Environment variables