atuinsh/atuin · error

hook action cannot be combined with a positional agent

Error message

hook action cannot be combined with a positional agent

What it means

The hook command's run() rejects combinations where both an action (like install) and a positional agent are supplied. The two forms are mutually exclusive: either `install <agent>` or a bare `<agent>`. Supplying both is ambiguous, so it bails with this message.

Source

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

    #[command(subcommand)]
    action: Option<Action>,

    /// Which agent's hook format to parse (e.g., "claude-code")
    #[arg(value_name = "AGENT", hide = true)]
    agent: Option<String>,
}

impl Cmd {
    #[instrument(level = "trace", skip_all, err)]
    pub async fn run(self, settings: &Settings) -> Result<()> {
        match (self.action, self.agent) {
            (Some(Action::Install { agent }), None) => install(&agent),
            (None, Some(agent)) => handle(&agent, settings).await,
            (None, None) => {
                bail!("expected `atuin hook <agent>` or `atuin hook install <agent>`");
            }
            (Some(_), Some(_)) => {
                bail!("hook action cannot be combined with a positional agent");
            }
        }
    }
}

fn id_file_path(tool_use_id: &str) -> PathBuf {
    std::env::temp_dir().join(format!("atuin-hook-{tool_use_id}"))
}

async fn handle(agent_name: &str, settings: &Settings) -> Result<()> {
    let agent = Agent::from_name(agent_name)?;

    if let InstallKind::Extension { reload_hint, .. } = agent.install_kind() {
        bail!(
            "`atuin hook {agent_name}` is not supported. Use `atuin hook install {agent_name}`. \
             {reload_hint}"
        );
    }

View on GitHub (pinned to c0c717ab04)

Solutions

1. Use only one form: `atuin hook install claude` or `atuin hook claude`
2. Remove the extra positional argument
3. Check `atuin hook --help` for the accepted syntax

Example fix

// before
atuin hook install claude codex
// after
atuin hook install claude

# exactly one form
if [[ $# -gt 2 || ($1 == "install" && $# -gt 2) ]]; then
  echo "usage: atuin hook <agent> | atuin hook install <agent>"; exit 2
fi

When it happens

Trigger: Running something like `atuin hook install claude extra-position` — i.e. clap parses both Some(Action::Install) and Some(agent).

Common situations: Misreading the CLI grammar and passing an agent both as the install subcommand argument and as a free positional; scripts concatenating arguments incorrectly.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• expected `atuin hook <agent>` or `atuin hook install <agent>
• `atuin hook {agent_name}` is not supported. Use `atuin hook
• Failed to read from input
• authentication canceled
• You are not logged in

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