atuinsh/atuin · error

agent does not use JSON hooks

Error message

agent does not use JSON hooks

What it means

add_hook_entries edits the agent's JSON hooks configuration and is only valid for agents whose InstallKind is JsonHooks. If called for an agent using a different install kind (e.g. Extension), it bails since there is no JSON hooks structure to mutate.

Source

Thrown at crates/atuin/src/command/client/hook.rs:309

            eprintln!(
                "\nAtuin extension installed for {actor_name}. Extension: {}\n{reload_hint}",
                extension_path.display()
            );
        }
    }

    Ok(())
}

fn add_hook_entries(hooks: &mut Value, agent: &Agent) -> Result<()> {
    let InstallKind::JsonHooks {
        config_path: _,
        hook_command,
        matcher,
    } = agent.install_kind()
    else {
        bail!("agent does not use JSON hooks");
    };

    for event_type in HOOK_EVENT_TYPES {
        let event_hooks = hooks
            .as_object_mut()
            .ok_or_else(|| eyre::eyre!("hooks is not a JSON object"))?
            .entry(*event_type)
            .or_insert_with(|| Value::Array(Vec::new()));

        let arr = event_hooks
            .as_array_mut()
            .ok_or_else(|| eyre::eyre!("hooks.{event_type} is not an array"))?;

        let already_installed = arr.iter().any(|entry| {
            entry.get("hooks").and_then(Value::as_array).is_some_and(|hooks| {
                hooks
                    .iter()
                    .any(|hook| hook.get("command").and_then(Value::as_str) == Some(hook_command))

View on GitHub (pinned to c0c717ab04)

Solutions

1. Update atuin to the latest version where the agent's install kind is handled
2. Report a bug with the agent name if a current release still fails
3. Verify the agent name is spelled correctly and supported

match install(&agent) {
    Err(e) if e.to_string().contains("agent does not use JSON hooks") => {
        // fall back to the agent's extension-based install path or upgrade atuin
    }
    other => other?,
}

When it happens

Trigger: install() invokes add_hook_entries for an agent whose install_kind() is not InstallKind::JsonHooks; internal dispatch mismatch in the hook installation flow.

Common situations: A bug or new agent type added with an install kind not handled by the installer; users cannot normally trigger this directly — it surfaces during `atuin hook install <agent>`.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• `atuin hook {agent_name}` is not supported. Use `atuin hook
• {message}. Enable `daemon.autostart = true` or restart the d
• {reason}. Enable `daemon.autostart = true` or restart the da
• expected `atuin hook <agent>` or `atuin hook install <agent>
• hook action cannot be combined with a positional agent

AI-assisted analysis of atuinsh/atuin@c0c717ab04 (2026-09-12). Data as JSON: /api/errors/6ba559dcfcd38db3. Report an issue: GitHub.