Configuration

Use /models for connections and model jobs, /mode for the active review posture, and /config for a guided settings conversation. This page explains where saved values come from and when they apply.

Four ways to configure

Source	Example	Use
CLI	kin --model MODEL_ID	Override one launch.
Environment	KIN_MODEL=MODEL_ID kin	Set a shell or service environment.
Settings file	model = "MODEL_ID"	Keep a persistent default.
Provider preset	kin --preset minimax	Select a curated connection and defaults.

Kin reads exported environment variables; it does not load .env files. See CLI flags, environment variables, and settings keys for exact options.

Precedence

For supported overrides, highest priority wins:

CLI > environment > project settings > global settings > preset > default

Provider and wire are resolved separately. Explicit Chat or Responses selects the OpenAI family; a bare custom base URL retains the Messages heuristic. Use an explicit wire for a custom server when its API is known.

Auto is the default after exact-workspace trust. Set global mode = "strict" for review-first launches. A project cannot set its own permission mode.

Global vs project files

File	Purpose
~/.kin/settings.toml	Personal defaults across workspaces.
<workdir>/.kin/settings.toml	Permitted project overrides, loaded after trust.
~/.kin/credentials.toml	Kin-managed secrets, written with mode 0600.
~/.kin/grants.toml	Workspace trust and Git-host grants, managed with /grants.

kin settings shows effective values, their sources, and lint such as unknown or mis-scoped keys. Keys entered through Kin go to the credential store; legacy secrets in settings migrate on the next settings write.

Global-only (sensitive) keys

A project cannot redirect credentials, trust itself, change launch authority, or choose session storage/privacy. Mis-scoped values are stripped with a warning. Global-only families include endpoints and keys, provider catalogs, mode, workspace/Git-host grants, shell_allowlist, session_dir, and no_save. Retired sandbox/SSH names remain inert compatibility data.

The settings reference lists exact scope. Use dedicated connection/trust controls for these families. /config can propose only the source-allowed model/sampling keys through a fresh reviewed diff; instructions cannot expand that list.

New sessions vs resume

Saved configuration supplies new-session defaults. Resume preserves the journal’s backend/model configuration unless you explicitly override it; do not assume editing the global file retargets a saved conversation. Use /model for a live switch and see resume behavior for reconstruction and provider changes.

Visible plans

Plans live under <workdir>/.kin/plans/ and survive dismissal or a mid-plan quit. The review shows the path. persist_plans is retired and has no effect. Add .kin/plans/ to .gitignore if plans should stay local; ignoring all of .kin/ would also hide any project skills/configuration you intend to share. See planning.

Per-directory instructions

After trust, Kin reads root AGENTS.md, falling back to CLAUDE.md, and user guidance under $XDG_CONFIG_HOME/kin/AGENTS.md (normally ~/.config/kin/AGENTS.md). Root changes apply at the next main-session turn; custom system prompts keep their own composition.

When a tool touches a subtree, Kin reads nested guidance down to that file’s directory or the named directory itself. AGENTS.md wins at each level; sorted .claude/rules/*.md follow. Links are pointers for explicit reads, not automatic includes.

Guidance arrives after the triggering result, so read the relevant subtree before editing. Shell/code path discovery is best-effort. Repeated touches share discovery state; applied compaction/pruning and history resets re-arm it. An already-delivered file is not watched, but can be read explicitly.

Regular guidance files have a 50 KiB input cap; the complete nested reminder has a 64 KiB UTF-8 cap. Truncation and withheld files are reported, and withheld files remain eligible later. Guidance grants no authority.

Commonly-needed environment variables

Variable	Purpose
KIN_TOKEN_BUDGET	Shared run leash over reported non-cached input and output.
KIN_MAX_TURNS	Model/tool rounds per user turn; 0 means unlimited.
KIN_HOME	Relocate Kin’s global state; project plans and other independently scoped paths keep their own locations.

Use the environment reference for cache controls and the complete path/override list.

File errors

Malformed settings produce a warning and fall back without that file. KIN_STRICT_SETTINGS=1 makes a managed launch fail instead. For connection examples, start with Connect a model.