Repository navigation
Description
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