Skip to content

[Feature]: Ship the Claude status hooks as a plugin instead of writing to ~/.claude/settings.json #15496

Description

@moltar

Problem or use case

I keep ~/.claude/settings.json in git and manage it as code. On this machine the file is a symlink into my dotfiles repo.

Orca writes 11 managed hook entries into that file at startup. It does not ask, and it does not report what it did. I found it as a diff in my dotfiles repo that I did not make.

I want the status feature. The sidebar states are useful and I plan to keep them. I do not want Orca to own a file that I author and version.

The entries also carry absolute paths such as /home/<user>/.orca/agent-hooks/claude-hook.sh. Those paths are wrong on my other machines. #13442 made them ${HOME}-relative in 1.4.183, which helps, but the file is still mine and Orca still writes to it.

Two issues closed without solving this. #6879 asked for settings.local.json and was closed as wontfix, because Claude Code reads user-level hooks only from settings.json. #11564 asked for a way to stop Orca from writing to the file and has no answer. Both accepted the same premise: that an edit to settings.json is the only option. That premise is out of date.

Proposed solution

Ship the status hooks as a Claude Code plugin. Do not write to settings.json at all.

A plugin directory at ~/.claude/skills/orca-status/ loads on the next session. It needs no install step and no settings.json entry. Personal scope loads without a trust prompt. See "Skills-directory plugins" in the plugins reference.

The plugin holds the hooks in hooks/hooks.json. The format is the same object that Orca writes today, so the 11 events move across unchanged:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/claude-hook.sh" }
        ]
      }
    ]
  }
}

${CLAUDE_PLUGIN_ROOT} resolves to the plugin directory. The absolute path leaves the config, so the portability problem goes away by construction instead of by the ${HOME} substitution in #13442.

This also answers the objection recorded in #6879. The hooks must work no matter how Claude starts: from the Orca picker, from a manual claude, from a script or alias, or on session resume. A skills-directory plugin loads in all of these, because Claude Code finds it from the directory and not from a launch flag.

Orca already works this way for other agents:

  • Hermes gets a plugin named orca-status (src/main/hermes/hermes-managed-plugin-source.ts).
  • OpenCode gets a config overlay directory.
  • Pi and OMP get Orca-managed extension files (src/relay/plugin-overlay.ts).

Claude Code is the one integration that edits a file the user writes.

For a session-scoped test, claude --plugin-dir <dir> loads a plugin for one session. Orca builds the launch command for its own panes, so that path is available today without a config write.

Alternatives or additional context

Read the session transcripts instead. Claude Code writes JSONL session files under ~/.claude/projects/, and Orca already reads them. src/main/native-chat/session-file-resolver.ts resolves them, and the Stop handler already opens transcript_path to get the last assistant message. A watcher on those files gives turn boundaries and tool calls with no config write at all. I think the plugin is better. A watcher must poll the files, and no event reports PermissionRequest. The "waiting on you" state gets weaker as a result. I mention this option because it needs nothing from Claude Code.

HTTP hooks (#12925) do not solve this. type: "http" removes the shell script, but the entries still live in my settings.json.

Migration: install the plugin on upgrade, then remove the managed entries from settings.json. Orca has removeManagedHooks already and knows which entries are its own.

Environment: Orca 1.4.180, Linux arm64 AppImage.

Activity

  1. added theissue type on Sep 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions