[Feature]: Orca Context Awareness into Worktree #31020

Problem or use case

[Feature]: Orca Context Awareness into Worktree

Summary

Orca runs many agents side by side, each in its own worktree. Each agent reads its own set of instruction files: AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules/*.mdc, SKILL.md, plus global files under ~/.claude, ~/.codex, ~/.agents and so on.

Today nothing in Orca shows:

1. Which instructions each agent actually loads in a given worktree.
2. Where those instructions duplicate or contradict each other, across files, tools and global/worktree scope.
3. What changed in that context over time, especially global files that live outside Git.

I'd like Orca to add a lightweight context awareness layer that covers these three points.

Problem

Instruction files drift. People copy a rule into five tool-specific files, and months later one file says pnpm and another says npm. Agents don't throw an error when this happens. They quietly pick one rule or split the difference, so the agent behaves slightly wrong and the cause is very hard to trace.

Orca makes this more likely in three ways:

• Many agent types per repo. Claude Code, Codex, Gemini, Cursor and others each discover different files and resolve precedence differently.
• Many worktrees. The same repo can have different local instruction files per worktree.
• Global context is invisible. A skill added to ~/.claude/skills/ or a global AGENTS.md changes every agent's behavior, with no commit and no record.

A realistic scenario:

Today the only way to debug this is to diff files by hand from memory. The question I'd like Orca to answer is:

"What changed in this agent's context since Monday that might explain this?"

Prior art: ruleherd

ruleherd (write-up) already covers the static part of this problem well. It is MIT-licensed, has zero dependencies, and runs with npx ruleherd. It reads every instruction file in a repo, including global configs such as ~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md, ~/.agents/rules/ and Cursor global rules. It reports:

• CONFLICT: contradictions between files (npm vs pnpm, tabs vs spaces, never vs always)
• DUPLICATE: blocks pasted across files
• STALE: rules that reference versions the repo no longer uses
• DEAD REF / DEAD CMD / DEAD GLOB: missing files, missing npm scripts, and Cursor rules whose globs match nothing, so the rule silently never loads
• BLOAT: very large files that load into every prompt

It also gives a score out of 100 and has a strict mode that fails CI.

Its author is clear about the limits: contradiction detection is heuristic (keyword pairs and never/always polarity), and a clean grade means "no detectable drift", not that the rules are good. A commenter on the write-up points out a gap: the most harmful drift is often an omission. A rule gets added to one file after an incident and never copied to the others. Near-duplicate blocks where one copy has an extra line are a cheap way to detect that.

Other tools in the same space: ctxlint (shows which files each tool loads), WhichRules (per-agent effective rules), aiscope (scope-aware conflicts) and agent-rule-conflicts (SARIF output).

What none of them do is track context over time or tie a change to an agent's behavior. Orca is well placed to fill that gap because it already knows which agent runs in which worktree, and when.

Proposal

I'd suggest building this in phases, with temporal tracking as the foundation and the analysis as a module that can be swapped out.

Phase 1: Context panel per worktree (static)

• For each worktree and agent, list the instruction files that agent will load: global, project and worktree, in precedence order.
• Flag shadowed or never-loaded files. Example: a rule glob that matches nothing.
• Run conflict and duplicate checks. One option is to shell out to npx ruleherd and render its report, which avoids reimplementing the linter. The other is to build equivalent checks natively.
• Show a badge on the worktree when conflicts exist.

Phase 2: Context change log

• Watch the known global and worktree context locations.
• Append events to a local JSONL log with timestamp, scope (global/project/worktree), path, content_hash and previous_hash.
• Show a context timeline per worktree: what changed, when, and in which scope.
• Run periodic reconciliation by hashing files, so changes made while Orca was closed are detected. Mark these as "detected later" rather than giving them a fake timestamp.

Example event:

{
  "event_id": "evt_0042",
  "timestamp": "2026-10-20T04:30:00Z",
  "event": "file_modified",
  "scope": "global",
  "path": "~/.claude/skills/frontend-design/SKILL.md",
  "content_hash": "sha256:…",
  "previous_hash": "sha256:…"
}

Phase 3: Relationship scores and change attribution

• Keep three separate scores per file pair: proximity (how related), conflict (how contradictory) and redundancy (how duplicated). High similarity is not the same as conflict.
• Detect near-duplicates with divergence to catch the omission case described above.
• Add an "What changed since…" query, available in the UI and through the Orca CLI so agents can call it. It returns the context changes since a given time or run, their scope, and any conflicts they introduced.
• Label results as possible contributors, not causes. A file changing before a behavior change is a correlation, not proof.

Why this belongs in Orca

• Orca already owns the worktree × agent matrix, so it is the one place that can answer "what does this agent in this worktree actually see?"
• Global context is shared by every agent Orca launches. A single bad global edit can affect a whole fleet, and today nothing reports it.
• It fits Orca's local-first design. Phases 1–2 are deterministic, need no AI calls, and send no data off the machine.

Non-goals

• Replacing Git or versioning repo files that are already committed.
• Rewriting or "fixing" users' instruction files automatically. Phase 1 should report problems; any auto-fix should be opt-in.
• Claiming causation for agent behavior.

Open questions

• Should Orca embed an existing linter such as ruleherd, or implement its own checks?
• How should Orca model each agent's loading and precedence rules as those agents change over time?
• Where should the log live: per repo (for example .orca/context-log.jsonl) or in Orca's app data? Should it be optional for privacy?

Further reading

A longer design write-up of this concept is available here: (link to spec page)

Summary

Orca runs many agents side by side, each in its own worktree. Each agent reads its own set of instruction files: AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules/*.mdc, SKILL.md, plus global files under ~/.claude, ~/.codex, ~/.agents and so on.

Today nothing in Orca shows:

1. Which instructions each agent actually loads in a given worktree.
2. Where those instructions duplicate or contradict each other, across files, tools and global/worktree scope.
3. What changed in that context over time, especially global files that live outside Git.

I'd like Orca to add a lightweight context awareness layer that covers these three points.

Problem

Instruction files drift. People copy a rule into five tool-specific files, and months later one file says pnpm and another says npm. Agents don't throw an error when this happens. They quietly pick one rule or split the difference, so the agent behaves slightly wrong and the cause is very hard to trace.

Orca makes this more likely in three ways:

• Many agent types per repo. Claude Code, Codex, Gemini, Cursor and others each discover different files and resolve precedence differently.
• Many worktrees. The same repo can have different local instruction files per worktree.
• Global context is invisible. A skill added to ~/.claude/skills/ or a global AGENTS.md changes every agent's behavior, with no commit and no record.

A realistic scenario:

Today the only way to debug this is to diff files by hand from memory. The question I'd like Orca to answer is:

"What changed in this agent's context since Monday that might explain this?"

Prior art: ruleherd

ruleherd ([write-up](https://dev.to/princejain756/your-claudemd-and-agentsmd-disagree-and-you-dont-know-it-5f23)) already covers the static part of this problem well. It is MIT-licensed, has zero dependencies, and runs with npx ruleherd. It reads every instruction file in a repo, including global configs such as ~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md, ~/.agents/rules/ and Cursor global rules. It reports:

• CONFLICT: contradictions between files (npm vs pnpm, tabs vs spaces, never vs always)
• DUPLICATE: blocks pasted across files
• STALE: rules that reference versions the repo no longer uses
• DEAD REF / DEAD CMD / DEAD GLOB: missing files, missing npm scripts, and Cursor rules whose globs match nothing, so the rule silently never loads
• BLOAT: very large files that load into every prompt

It also gives a score out of 100 and has a strict mode that fails CI.

Its author is clear about the limits: contradiction detection is heuristic (keyword pairs and never/always polarity), and a clean grade means "no detectable drift", not that the rules are good. A commenter on the write-up points out a gap: the most harmful drift is often an omission. A rule gets added to one file after an incident and never copied to the others. Near-duplicate blocks where one copy has an extra line are a cheap way to detect that.

Other tools in the same space: [ctxlint](https://github.com/tqakdev/ctxlint) (shows which files each tool loads), [WhichRules](https://github.com/z35068037/whichrules) (per-agent effective rules), [aiscope](https://docs.rs/crate/aiscope/0.1.0/source/BLOG.md) (scope-aware conflicts) and [agent-rule-conflicts](https://github.com/al1re3a/agent-rule-conflicts) (SARIF output).

What none of them do is track context over time or tie a change to an agent's behavior. Orca is well placed to fill that gap because it already knows which agent runs in which worktree, and when.

Proposal

I'd suggest building this in phases, with temporal tracking as the foundation and the analysis as a module that can be swapped out.

Phase 1: Context panel per worktree (static)

• For each worktree and agent, list the instruction files that agent will load: global, project and worktree, in precedence order.
• Flag shadowed or never-loaded files. Example: a rule glob that matches nothing.
• Run conflict and duplicate checks. One option is to shell out to npx ruleherd and render its report, which avoids reimplementing the linter. The other is to build equivalent checks natively.
• Show a badge on the worktree when conflicts exist.

Phase 2: Context change log

• Watch the known global and worktree context locations.
• Append events to a local JSONL log with timestamp, scope (global/project/worktree), path, content_hash and previous_hash.
• Show a context timeline per worktree: what changed, when, and in which scope.
• Run periodic reconciliation by hashing files, so changes made while Orca was closed are detected. Mark these as "detected later" rather than giving them a fake timestamp.

Example event:

{
  "event_id": "evt_0042",
  "timestamp": "2026-10-20T04:30:00Z",
  "event": "file_modified",
  "scope": "global",
  "path": "~/.claude/skills/frontend-design/SKILL.md",
  "content_hash": "sha256:…",
  "previous_hash": "sha256:…"
}

Phase 3: Relationship scores and change attribution

• Keep three separate scores per file pair: proximity (how related), conflict (how contradictory) and redundancy (how duplicated). High similarity is not the same as conflict.
• Detect near-duplicates with divergence to catch the omission case described above.
• Add an "What changed since…" query, available in the UI and through the Orca CLI so agents can call it. It returns the context changes since a given time or run, their scope, and any conflicts they introduced.
• Label results as possible contributors, not causes. A file changing before a behavior change is a correlation, not proof.

Why this belongs in Orca

• Orca already owns the worktree × agent matrix, so it is the one place that can answer "what does this agent in this worktree actually see?"
• Global context is shared by every agent Orca launches. A single bad global edit can affect a whole fleet, and today nothing reports it.
• It fits Orca's local-first design. Phases 1–2 are deterministic, need no AI calls, and send no data off the machine.

Non-goals

• Replacing Git or versioning repo files that are already committed.
• Rewriting or "fixing" users' instruction files automatically. Phase 1 should report problems; any auto-fix should be opt-in.
• Claiming causation for agent behavior.

Open questions

• Should Orca embed an existing linter such as ruleherd, or implement its own checks?
• How should Orca model each agent's loading and precedence rules as those agents change over time?
• Where should the log live: per repo (for example .orca/context-log.jsonl) or in Orca's app data? Should it be optional for privacy?

Further reading

A longer design write-up of this concept is available here: (link to spec page)

Proposed solution

This is a most likely idea that could benefit visually into the UI by having like a score of a worktree, if the worktree has too much bloat from contexts or not. :)

Alternatives or additional context

No response