---
id: 10059
title: 'Claude Code harness: auto-load AGENTS.md via .claude/CLAUDE.md + commit shared skills + gitignore worktrees'
state: CLOSED
labels:
  - enhancement
  - developer-experience
  - ai
assignees:
  - tobiu
createdAt: '2026-04-18T12:40:22Z'
updatedAt: '2026-04-18T15:19:35Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10059'
author: tobiu
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-18T13:19:24Z'
---
# Claude Code harness: auto-load AGENTS.md via .claude/CLAUDE.md + commit shared skills + gitignore worktrees

## Intent / The Why

Claude Code (Anthropic CLI) is being added as a first-class swarm node alongside Antigravity and Gemini CLI. Unlike Gemini CLI — which the repo wires via `.gemini/settings.json` to auto-load `AGENTS.md` — Claude Code has no configuration in this repo, so agents spawned in it boot with **no awareness of `AGENTS.md`**. This means the Pre-Commit Hard Gates (§3), Memory Core Protocol (§4), Visual Verification Protocol (§8), and Swarm Fat Ticket Protocol (§9) are all missing from the session-zero context.

Diagnostic test: open a Code tab in this repo and ask "what are your pre-commit gates?" — the agent searches the codebase with Glob/Grep instead of reciting Section 3 from context. That is the tell that `AGENTS.md` is not wired.

## The Architectural Reality

Per the Claude Code memory documentation ([code.claude.com/docs/en/memory.md](https://code.claude.com/docs/en/memory.md)):

- Both `./CLAUDE.md` and `./.claude/CLAUDE.md` are auto-loaded at session start, with **identical precedence**. Either works.
- Nested subdirectory `CLAUDE.md` files are loaded on-demand (when Claude reads files in the subdirectory), not at boot.
- Precedence order (low→high): managed policy → `~/.claude/CLAUDE.md` → project `CLAUDE.md`/`.claude/CLAUDE.md` → `CLAUDE.local.md` → on-demand subdirectory files.

Claude Code also natively injects model identity (name, model ID, family, knowledge cutoff) into every session's system prompt — so agents know they are e.g. `claude-opus-4-7[1m]` without external scaffolding. This is relevant for correctly populating the `model` field when calling Memory Core `add_memory`.

Separately, Claude Code uses git worktrees for isolated agent branches, landing them under `.claude/worktrees/<name>/`. These checkouts are per-branch, ephemeral, and must not be tracked in the parent repo — otherwise `git status` on the main checkout shows every worktree as nested untracked files.

The repo already has an un-committed `.claude/skills/` directory in the main working tree containing symlinks to `../../.agent/skills/*` (covering `create-skill`, `debugging-antigravity`, `ideation-sandbox`, `neural-link`, `pr-review`, `pull-request`, `self-repair`, `tech-debt-radar`, `ticket-intake`, `unit-test`, `whitebox-e2e`). These should be committed so Claude Code's skill discovery picks up the same swarm skills Gemini CLI sees via `.agent/skills/`.

## Scope (Single Atomic Commit — Standard Request, not Epic)

Three changes, one PR, one commit:

1. **`.claude/CLAUDE.md` → `../AGENTS.md`** (symlink). Placed inside `.claude/` rather than repo root — keeps root uncluttered and documented-equivalent per Claude Code docs. `AGENTS.md` is ~22KB, so every Claude Code session pays ~22KB of cache overhead per turn in exchange for the gates being always-present.

2. **`.gitignore` addition: `.claude/worktrees/`** — prevents Claude Code's per-agent worktree checkouts from polluting git status in the main checkout.

3. **Commit `.claude/skills/*` symlinks to `../../.agent/skills/*`** — promotes the ten existing local symlinks to tracked repo assets so Claude Code has feature parity with Gemini CLI's skill library.

## Avoided Gold Standards / Traps

- **Rejected: place CLAUDE.md at repo root.** Tidier inside `.claude/`; identical auto-load behavior per the docs. Root already has `AGENTS.md` + `AGENTS_STARTUP.md` — adding a root-level CLAUDE.md would mislead contributors into thinking it's a separate document.
- **Rejected: copy `AGENTS.md` content into a standalone CLAUDE.md.** Creates drift. Symlink guarantees single source of truth.
- **Rejected: the `@AGENTS.md` import directive** (Claude Code's memory-file include syntax). Valid, but adds indirection without benefit when content is literally identical. Reserve for future if Claude-specific additions become necessary.
- **Rejected: commit `.claude/worktrees/`.** Tracking transient per-agent local state would pollute git history with branch ephemera.
- **Rejected: duplicate skill files into `.claude/skills/`.** Symlinks preserve a single source under `.agent/skills/`, keeping Claude and Gemini skill libraries in lock-step.
- **Rejected: adding a user-level `~/.claude/CLAUDE.md` for model self-identification.** Claude Code injects model identity (name, ID, family, knowledge cutoff) into every session's system prompt natively. The Gemini.md-style workaround used for Antigravity/Gemini CLI is unnecessary here and would add contributor-experience friction with no benefit.

## Verification

After merge to `dev`, open a fresh Code tab in a cloned checkout and ask: *"what are your pre-commit gates?"* — expected: Section 3 recital with no codebase search. Cross-check via Windows contributor: symlinks in git survive git clone on Windows as symlinks when `core.symlinks=true`; otherwise they appear as text files containing the target path (acceptable fallback since content is still AGENTS.md).

## Follow-ups (Out of Scope Here — Referenced for Graph Connectivity)

- Optimize `AGENTS.md` / `AGENTS_STARTUP.md` startup-cache footprint (~47KB combined per session).
- Optimize MCP tool descriptions for token economy.
- Optimize turn-based Memory Core memory serialization overhead.

These exist as separate known concerns and are not addressed by this ticket.

---

Origin Session ID: f018be49-cbf9-4f99-9119-2510fc5bb8d8

## Timeline

- 2026-04-18T12:40:24Z @tobiu added the `enhancement` label
- 2026-04-18T12:40:24Z @tobiu added the `developer-experience` label
- 2026-04-18T12:40:24Z @tobiu added the `ai` label
- 2026-04-18T13:05:36Z @tobiu referenced in commit `ef84b11` - "feat(claude): wire Claude Code harness (#10059)

- Add .claude/CLAUDE.md -> ../AGENTS.md symlink for session-zero
  auto-load of the Pre-Commit Hard Gates, Memory Core Protocol,
  Visual Verification Protocol, and Swarm Fat Ticket Protocol
- Add .claude/skills/ symlinks to ../../.agent/skills/* for feature
  parity with Gemini CLI's skill discovery
- Gitignore .claude/worktrees/ so per-agent worktree checkouts
  don't pollute git status in the main checkout"
- 2026-04-18T13:06:14Z @tobiu cross-referenced by PR #10060
- 2026-04-18T13:19:25Z @tobiu referenced in commit `0aa368b` - "feat(claude): wire Claude Code harness (#10059) (#10060)

- Add .claude/CLAUDE.md -> ../AGENTS.md symlink for session-zero
  auto-load of the Pre-Commit Hard Gates, Memory Core Protocol,
  Visual Verification Protocol, and Swarm Fat Ticket Protocol
- Add .claude/skills/ symlinks to ../../.agent/skills/* for feature
  parity with Gemini CLI's skill discovery
- Gitignore .claude/worktrees/ so per-agent worktree checkouts
  don't pollute git status in the main checkout"
- 2026-04-18T13:19:25Z @tobiu closed this issue
- 2026-04-18T14:22:18Z @tobiu cross-referenced by #10061
- 2026-04-18T14:35:54Z @tobiu cross-referenced by PR #10062
- 2026-04-18T14:57:24Z @tobiu cross-referenced by #10063
- 2026-04-18T15:19:35Z @tobiu assigned to @tobiu

