Configuration problems

Find the effective AgentKit preferences, validate both scopes, and remove only the override that caused the problem.

Use this page when a setting is ignored, behaves differently by project, or makes a hook fail.

Follow a safe configuration loop

Run commands from the affected project and inspect ak config prefs resolve before changing a value.
Run ak config prefs validate, then choose --scope user for every project or --scope project for only the current project.
Change one supported key with set or unset; do not replace the whole YAML file to fix one preference.
Resolve and validate again, then start a fresh runtime session and verify the original symptom.

Know which file wins

AgentKit preferences can come from two YAML files:

Scope	Path
User	`$AGENTKIT_HOME/config.yaml`, default `~/.agentkit/config.yaml`
Project	`<project>/.agentkit/config.yaml`

AgentKit deep-merges the files and the project value wins for the same key. The project scope is resolved from the current working directory, so run diagnostic commands from the same project as the affected runtime session.

ak config opens the local dashboard. It does not print effective preferences, and ak config status reports the dashboard process rather than configuration values.

Resolve the effective value

ak config prefs resolve
ak config prefs resolve --json

The output names the user and project sources and shows the merged preferences. If no preference is set, hooks use their built-in defaults. Exit 1 means a configuration file could not be read or parsed.

Validate before editing

ak config prefs validate
ak config prefs validate --file ./config.yaml

The first command validates whichever user and project files exist against the schema embedded in the installed CLI. No configuration files is a valid state. The second validates one named file. Exit 0 means there are no errors; exit 1 means invalid or unreadable configuration; invalid flags exit 2.

Warnings can identify an older spelling that still resolves. Errors identify a value that cannot be used as written. Fix the reported line and validate again before restarting the runtime.

Change one supported preference

Use the CLI instead of deleting or replacing a whole configuration file.

Disable a shipped hook soft-preference

ak config prefs set hooks.simplify-gate false --scope project
ak config prefs unset hooks.simplify-gate --scope project

This example changes one shipped hook preference. set accepts a supported hooks.<name> key and a boolean. unset removes only that override so the value falls back to the other scope or the built-in default. Choose --scope user or --scope project explicitly.

Opt out of the automatic journal step

ak config prefs set journal.auto false
ak config prefs unset journal.auto

set also accepts the exact key journal.auto with a boolean. Setting it to false suppresses the automatic /ak:journal step at the end of plan, cook, fix, ship, and bootstrap workflows without unregistering hooks or blocking an explicit /ak:journal. unset journal.auto removes the override so the value falls back to the other scope or the built-in default (true).

These commands back up and rewrite the selected config.yaml. An unsupported key, a non-boolean value, or a schema failure exits 1.

Recover safely

If a manual edit broke parsing, keep a copy of the file, repair only the lines reported by validate, and re-run both validate and resolve. If one preference override caused the problem, use unset for that key rather than deleting ~/.agentkit, .agentkit, ~/.claude, or ~/.codex.

The issue is resolved when validation exits 0, resolve shows the expected source and value, and a new runtime session behaves as expected.

On this page