Locations

Two scopes, one schema

User

~/.agentkit/config.yaml (or $AGENTKIT_HOME/config.yaml). Per-machine: keys, updates, adapters, telemetry…

Project

.agentkit/config.yaml in the repo. Deep-merges over user for this repo: coding_level, paths, hooks…

Field names are snake_case. Schema: https://releases.agentkit.best/schemas/config/v1.json — validate with ak config prefs validate.

CLI

View and edit

shell

# Dashboard / visual config
ak config

# Preferences (hook toggles, resolve effective config)
ak config prefs resolve
ak config prefs validate
ak config prefs set hooks.simplify-gate false --scope project
ak config prefs unset hooks.simplify-gate --scope project

# Beta channel only. Tiers: inherit, sonnet, opus, fable, haiku.
# The value is shape-checked, not locked to the catalog snapshot.
ak config prefs set agent_models.cursor.sonnet claude-sonnet-4-6

Setup-owned

Sections ak setup / lifecycle usually write

Keys the CLI setup model owns. “—” means omit/empty until setup writes them.

Path	Type	Default	Options	Meaning
keys.anthropic	string	—	—	Anthropic API key written by ak setup. User config only — never commit secrets in project config.
keys.openai	string	—	—	OpenAI API key written by ak setup. User config only.
provider.default	string	—	—	Default provider id (for example anthropic).
provider.model	string	—	—	Default text model id.
provider.image	string	—	—	Model used for image generation.
kit.default	string	—	—	Default kit (for example engineer) for install/setup.
telemetry.enabled	boolean	false*	—	Send anonymous usage telemetry. *setup fixtures often false; enable only if you opt in.
api.token	string	—	—	Bearer token for the local API/dashboard when binding beyond loopback. Do not commit.
adapters.enabled	string	—	claude-code, codex, cursor, grok, …	Comma-separated enabled adapter ids (e.g. claude-code,codex).
codex.api_key_env_var	string	—	—	Env var name Codex reads for the API key (e.g. OPENAI_API_KEY).
codex.default_model	string	—	—	Model written into the Codex config.
codex.provider	string	—	openai \| azure \| bedrock	Codex backend provider.
updates.enabled	boolean	—	—	Opt in to Desktop auto-update / paired updates.
updates.channel	string	—	stable \| beta	Binary update channel. Empty may fall back to binary defaults.
updates.registry_url	string	—	—	Override update metadata root (staging only).
updates.cli_path	string	—	—	Verified ak executable paired with Desktop auto-update.
backups.scope	string	full	full \| lean	Capture scope for user-home snapshots.
backups.keep_last	integer	20	—	Snapshots to retain. 0 disables pruning.

Preferences

Workflow / kit preferences (often project)

From the project template and schema v1. Safe to commit so teams share coding_level, paths, and hooks.

Path	Type	Default	Options	Meaning
coding_level	integer	-1	-1…5	-1 off · 0 eli5 · 1 junior · 2 mid · 3 senior · 4 tech-lead · 5 architect/god-mode. Controls explanation depth.
privacy_block	boolean	true	—	Privacy hook blocks reading sensitive files (.env, credentials, keys…).
paths.docs	string	docs	—	Docs directory (project-relative or absolute).
paths.plans	string	plans	—	Plans directory.
docs.max_loc	integer	800	100–5000	Suggested max LOC per documentation file.
locale.response_language	string\|null	null	—	User-facing response language (null = match user / English).
locale.thinking_language	string\|null	null	—	Internal reasoning language (null = English).
plan.naming_format	string	"{date}-{issue}-{slug}"	—	Plan directory name template. Tokens: {date}, {issue}, {slug}.
plan.date_format	string	YYMMDD-HHmm	—	Format for the {date} token.
plan.issue_prefix	string	GH-	—	Issue prefix (e.g. GH-, JIRA-).
plan.reports_dir	string	reports	—	Reports subdirectory inside a plan.
plan.resolution.order	string[]	["session","branch"]	session, branch, directory	Order of strategies to resolve the active plan.
plan.validation.mode	string	prompt	prompt \| auto \| strict \| none	When the plan validation interview runs.
plan.validation.min_questions	integer	3	—	Minimum validation questions.
plan.validation.max_questions	integer	8	—	Maximum validation questions.
hooks.<name>	boolean	absent = on	true \| false	Per-hook toggle by script basename. Missing key means the hook is enabled.
project.type	string	auto	auto \| library \| application \| monorepo \| cli \| api \| web \| mobile	Override project type detection.
gemini.model	string	gemini-3-flash-preview	gemini-2.5-flash \| gemini-2.5-pro \| …	Gemini CLI model when skills use Gemini.

Examples

Minimal samples

User (this machine)

config.yaml

# ~/.agentkit/config.yaml  (user scope)
telemetry:
  enabled: false
adapters:
  enabled: claude-code,codex
updates:
  enabled: false
  channel: stable
backups:
  scope: full
  keep_last: 20
coding_level: 2
privacy_block: true
locale:
  response_language: vi
  thinking_language: en

Project (committable)

.agentkit/config.yaml

# .agentkit/config.yaml  (project — safe to commit)
# yaml-language-server: $schema=https://releases.agentkit.best/schemas/config/v1.json
coding_level: 3
paths:
  docs: docs
  plans: plans
privacy_block: true
hooks:
  simplify-gate: false
plan:
  naming_format: "{date}-{slug}"
  validation:
    mode: prompt

AgentKit Configuration