---
title: Configuration overview
description: Where rippy looks for config files, how the tiers are merged, and where Claude Code settings fit in.
---

The easiest way to get started is with a [package](/getting-started/packages/) —
`rippy init` will walk you through picking one and drop a
`.rippy.toml` in your home directory. For full control, rippy loads
config from five tiers, merged in ascending priority:

1. **Built-in stdlib** — the safe allowlist + 100+ CLI handlers compiled
   into the binary. Always active.
2. **Package** — if your config has `package = "develop"` (or `"review"` /
   `"autopilot"`) in its `[settings]` block, the matching package TOML is
   loaded from the binary as a baseline. Custom packages from
   `~/.rippy/packages/<name>.toml` are also loadable the same way —
   see [Custom packages](/getting-started/packages/#custom-packages).
3. **Global config** — `~/.rippy/config.toml`. (Falls back to
   `~/.rippy/config` or `~/.dippy/config` in the legacy flat format for
   backward compatibility.)
4. **Project config** — a `.rippy.toml` file walked up from the current
   directory. (Falls back to `.rippy` or `.dippy` in the flat format.)
5. **Environment override** — the `RIPPY_CONFIG` env var (or
   `DIPPY_CONFIG`) can point at a config file explicitly.

Higher tiers override lower tiers. Within a tier, earlier rules take
precedence over later ones.

## Claude Code settings are a separate pre-analysis step

Independently of the tiers above, rippy checks
`~/.claude/settings.json` → `permissions.allow` / `permissions.deny` /
`permissions.ask` rules **before** running its own config evaluation.
That means Claude Code's own permission rules act as a fast-path filter
on top of rippy's config, not as another config tier. If a command is
already covered by a Claude Code `allow` or `deny` rule, rippy respects
that decision and skips its own analysis.

You do not need to duplicate Claude Code rules into `.rippy.toml`.

## Config format: prefer `.rippy.toml`

Write new configs as `.rippy.toml`. TOML is where new features land —
every command, redirect, MCP, and `after` rule is a `[[rules]]` table,
aliases go in `[[aliases]]`, settings go in `[settings]`, and
[structured matching](/configuration/rules/#structured-matching)
(`command` / `subcommand` / `flags` / `args-contain`) and
[conditional rules](/configuration/rules/#conditional-rules)
(`when` clauses that gate a rule on git branch, cwd, env, file
existence, or an external command) are TOML-only. The CLI reflects
this: `rippy init`, `rippy allow`, `rippy deny`, and `rippy ask` all
write to `.rippy.toml`.

```toml
[settings]
default = "ask"
package = "develop"

[[rules]]
action = "deny"
pattern = "git push --force"
message = "Use --force-with-lease instead"
```

The legacy **flat `.rippy` / `.dippy` format** (one rule per line, a
carry-over from [Dippy](https://github.com/ldayton/Dippy)) is still
loaded so existing configs keep working unchanged, but it doesn't
support structured matching and won't see new features. Run
`rippy migrate` to convert a flat file to `.rippy.toml` in one shot.

See [Rules](/configuration/rules/) for the full grammar and
[Examples](/configuration/examples/) for ready-to-copy starter configs.

## Project config trust

Project-level config files can weaken protections (imagine a cloned repo
with `allow rm -rf /` in its `.rippy`). rippy uses a trust model:

- **Untrusted by default** — unknown project configs are ignored until you
  run `rippy trust` in that directory.
- **Repo-level trust** — once you trust a repo, config changes pulled via
  `git` stay trusted.
- **Hash verification** — edits made outside git revoke trust automatically.
- **AI tools cannot self-trust** — rippy rejects attempts by its own hook
  callers to write to the trust database.

You can opt out globally with `trust-project-configs = true` in
`~/.rippy/config.toml`, but the safe default is to stay cautious.

## Where to go next

- [Packages](/getting-started/packages/) — the `review` / `develop` /
  `autopilot` profiles.
- [Rules](/configuration/rules/) — the rule grammar (`allow`, `deny`,
  `ask`, `redirect`, `mcp`, `alias`, `after`, `set`).
- [Patterns](/configuration/patterns/) — prefix, glob, and exact matching.
- [Examples](/configuration/examples/) — annotated starter configs.
