chore: add CLAUDE.md and AGENTS.md for AI coding assistants

[peppescg]

Summary

• Add CLAUDE.md with Claude Code-specific project guidance (build commands, architecture, conventions, testing patterns)
• Add AGENTS.md as a tool-agnostic equivalent for other AI assistants (Cursor, Copilot, Codex, etc.)
• Aligns with the pattern already established in stacklok/toolhive

What's included in both files:

• Project overview and essential commands
• Pre-commit requirements (lint + type-check)
• Electron three-process architecture overview
• Code conventions (kebab-case files, path aliases, named exports)
• Testing patterns (Vitest + Testing Library + MSW)
• Pointers to existing documentation

CLAUDE.md vs AGENTS.md

• CLAUDE.md is read automatically by Claude Code at conversation start — includes more detail on architecture and feature organization
• AGENTS.md follows the emerging multi-tool standard — slightly more concise, works with Cursor, Copilot, Codex, etc.

Test plan

• Verify CLAUDE.md is loaded by Claude Code in a new conversation
• Verify AGENTS.md is picked up by other AI assistants
• Review content for accuracy and completeness
• Ensure no sensitive information is included

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds repository guidance files for AI coding assistants to standardize how automated tools interact with the ToolHive Studio codebase (commands, architecture, conventions, and testing/mocking patterns).

Changes:

• Add CLAUDE.md with Claude Code-oriented repository guidance.
• Add AGENTS.md with tool-agnostic guidance for other assistants.
• Document project commands, Electron architecture, code conventions, and testing patterns.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
CLAUDE.md	Adds detailed Claude Code guidance including commands, architecture, conventions, and testing notes.
AGENTS.md	Adds concise, tool-agnostic assistant guidance covering the same key areas.

[JAORMX]

Thanks for putting this together! Having a CLAUDE.md here makes a lot of sense, especially since we already have one in the toolhive backend repo. There are a few things worth fixing before merging though.

Bug: wrong path for route-tree.gen.ts

Both files say renderer/src/routes/route-tree.gen.ts. The actual file lives at renderer/src/route-tree.gen.ts (one level up, not inside routes/). This is the kind of mistake that would actively send Claude in the wrong direction... which is the opposite of what we want from a corrections file.

CLAUDE.md is too long

So, the thing about CLAUDE.md is that it's a correction file, not documentation. It exists to fix what Claude gets wrong without it. Every line should earn its place by preventing a real mistake. Right now it's at 150 lines. Target should be around 60-100.

A lot of what's here is stuff Claude can figure out by reading package.json, the directory structure, and the existing docs:

• The "Feature Organization" directory tree... Claude can just ls for this.
• "IPC Communication" section... this is how every Electron app works. Claude knows.
• "External Services" section... derivable from package.json dependencies.
• "Database" section... discoverable from the code.
• "Key Documentation" section at the bottom... Claude can find docs/ on its own.

The highest-value sections are "Common Gotchas" and "Auto-Generated Code." Those are the things that will bite you without being told. The rest is padding that'll drift out of date and add noise.

AGENTS.md maintenance story

I get the intent (Cursor, Copilot, Codex compatibility), but maintaining two files with ~80% overlap is going to lead to drift. When someone updates one and forgets the other, they'll contradict each other. Worth considering whether AGENTS.md should just reference CLAUDE.md for shared content, or whether the overlap should be extracted somewhere common.

Also, AGENTS.md pins specific major versions ("React 19, TypeScript 6, Electron 41, and Vite 8") that will go stale the moment any of them bumps. CLAUDE.md wisely avoids this. AGENTS.md should do the same.

Nits

• The # CLAUDE.md and # AGENTS.md headings at the top of each file are unnecessary. Claude (and other tools) already know what file they're reading.
• The gotchas section is the highest-ROI part of a CLAUDE.md but it's buried at the bottom. Consider making it more prominent.
• lint-staged in package.json already enforces lint + format on commit via husky, so the "always run lint before committing" instruction is partially redundant with the hook setup. Worth noting that the hook exists so Claude doesn't manually re-run what the hook already does.

What's good

• Commands section is clean and correct. All scripts verified against package.json.
• The auto-generated code warnings are correct and high-value.
• Conventional commits mention is useful since CI enforces it.
• The .claude/skills/deep-links/ pointer is a nice touch.

Overall the bones are good... just needs the path fix, some pruning, and a think about the two-file maintenance story.

[peppescg]

Thanks for putting this together! Having a CLAUDE.md here makes a lot of sense, especially since we already have one in the toolhive backend repo. There are a few things worth fixing before merging though.

Bug: wrong path for route-tree.gen.ts

Both files say renderer/src/routes/route-tree.gen.ts. The actual file lives at renderer/src/route-tree.gen.ts (one level up, not inside routes/). This is the kind of mistake that would actively send Claude in the wrong direction... which is the opposite of what we want from a corrections file.

CLAUDE.md is too long

So, the thing about CLAUDE.md is that it's a correction file, not documentation. It exists to fix what Claude gets wrong without it. Every line should earn its place by preventing a real mistake. Right now it's at 150 lines. Target should be around 60-100.

A lot of what's here is stuff Claude can figure out by reading package.json, the directory structure, and the existing docs:

• The "Feature Organization" directory tree... Claude can just ls for this.
• "IPC Communication" section... this is how every Electron app works. Claude knows.
• "External Services" section... derivable from package.json dependencies.
• "Database" section... discoverable from the code.
• "Key Documentation" section at the bottom... Claude can find docs/ on its own.

The highest-value sections are "Common Gotchas" and "Auto-Generated Code." Those are the things that will bite you without being told. The rest is padding that'll drift out of date and add noise.

AGENTS.md maintenance story

I get the intent (Cursor, Copilot, Codex compatibility), but maintaining two files with ~80% overlap is going to lead to drift. When someone updates one and forgets the other, they'll contradict each other. Worth considering whether AGENTS.md should just reference CLAUDE.md for shared content, or whether the overlap should be extracted somewhere common.

Also, AGENTS.md pins specific major versions ("React 19, TypeScript 6, Electron 41, and Vite 8") that will go stale the moment any of them bumps. CLAUDE.md wisely avoids this. AGENTS.md should do the same.

Nits

• The # CLAUDE.md and # AGENTS.md headings at the top of each file are unnecessary. Claude (and other tools) already know what file they're reading.
• The gotchas section is the highest-ROI part of a CLAUDE.md but it's buried at the bottom. Consider making it more prominent.
• lint-staged in package.json already enforces lint + format on commit via husky, so the "always run lint before committing" instruction is partially redundant with the hook setup. Worth noting that the hook exists so Claude doesn't manually re-run what the hook already does.

What's good

• Commands section is clean and correct. All scripts verified against package.json.
• The auto-generated code warnings are correct and high-value.
• Conventional commits mention is useful since CI enforces it.
• The .claude/skills/deep-links/ pointer is a nice touch.

Overall the bones are good... just needs the path fix, some pruning, and a think about the two-file maintenance story.

Thanks for the review 🙌
I don't know why claude code referred to a wrong routes path 😆