docs: document ~/.claude/CLAUDE.md compatibility behavior #8268

zeke · 2026-01-13T18:12:19Z

This PR documents Claude Code compatibility features in the Rules documentation.

Changes

Update intro to mention CLAUDE.md as alternative to AGENTS.md
Update Project section to mention CLAUDE.md support
Add "Claude Code Compatibility" section covering:
- Project-level CLAUDE.md
- Global ~/.claude/CLAUDE.md
- Cross-reference to Skills docs for ~/.claude/skills/
Document all three OPENCODE_DISABLE_CLAUDE_CODE* environment variables
Update Precedence section to list all local file types (AGENTS.md, CLAUDE.md, CONTEXT.md)

Testing locally

gh repo clone anomalyco/opencode
cd opencode
gh pr checkout 8268
# Review changes in packages/web/src/content/docs/rules.mdx

github-actions · 2026-01-13T18:12:55Z

The following comment was made by an LLM, it may be inaccurate:

No duplicate PRs found

rekram1-node · 2026-01-13T18:23:49Z

packages/web/src/content/docs/rules.mdx


+### Claude Code Compatibility
+
+For users migrating from or using both Claude Code and OpenCode, OpenCode also reads `~/.claude/CLAUDE.md`. This allows you to share instructions between both tools.


Only reads it if u don't have AGENTS.md (note)

Thanks! Updated to clarify these are fallbacks: d68ed5c

- Add CLAUDE.md as alternative to AGENTS.md in intro and Project sections - Add Claude Code Compatibility section with project/global rules and skills - Document all three OPENCODE_DISABLE_CLAUDE_CODE* environment variables - Update Precedence section to list all local file types and clarify behavior - Add cross-reference to Agent Skills docs for ~/.claude/skills/

AGENTS.md takes precedence over CLAUDE.md at both project and global levels.

rekram1-node · 2026-01-13T18:47:08Z

packages/web/src/content/docs/rules.mdx

 ### Project

-The ones we have seen above, where the `AGENTS.md` is placed in the project root, are project-specific rules. These only apply when you are working in this directory or its sub-directories.
+Place an `AGENTS.md` (or `CLAUDE.md`) in your project root for project-specific rules. These only apply when you are working in this directory or its sub-directories.


NIT: prefer not to say or CLAUDE.md everywhere, stick to AGENTS.md everywhere and then just document that CLAUDE.md is picked up as a fallback like u have

rekram1-node · 2026-01-13T18:47:11Z

packages/web/src/content/docs/rules.mdx

 ---

-You can provide custom instructions to opencode by creating an `AGENTS.md` file. This is similar to `CLAUDE.md` or Cursor's rules. It contains instructions that will be included in the LLM's context to customize its behavior for your specific project.
+You can provide custom instructions to opencode by creating an `AGENTS.md` file (or `CLAUDE.md` for Claude Code compatibility). This is similar to Cursor's rules. It contains instructions that will be included in the LLM's context to customize its behavior for your specific project.


NIT: prefer not to say or CLAUDE.md everywhere, stick to AGENTS.md everywhere and then just document that CLAUDE.md is picked up as a fallback like u have

Good call. Reverted intro and project sections to just reference AGENTS.md: 37356cc

Keep CLAUDE.md documentation in the Claude Code Compatibility section only.

rekram1-node · 2026-01-13T18:58:15Z

thx!

…8268)

* sync * sync * Update Nix flake.lock and x86_64-linux hash * Update aarch64-darwin hash * fix(TUI): make tui work when OPENCODE_SERVER_PASSWORD is set (anomalyco#8179) * chore: generate * wip: black * docs: Update plan mode restrictions (anomalyco#8290) * docs: add 302ai provider (anomalyco#8142) * fix: add missing metadata() and ask() defintions to ToolContext type (anomalyco#8269) * fix(tui): track all timeouts in Footer to prevent memory leak (anomalyco#8255) * fix: deduplicate file refs in sent prompts (anomalyco#8303) * chore: generate * wip: black * wip: black * release: v1.1.17 * add fullscreen view to permission prompt * chore: generate * fix(desktop): correct health check endpoint URL to /global/health (anomalyco#8231) * feat(desktop): Adding Provider Icons (anomalyco#8215) * chore: generate * console: reduce desktop download cache ttl to 5 minutes * fix(github): add persist-credentials: false to workflow templates (anomalyco#8202) * release: v1.1.18 * fix(desktop): Revert provider icon on select model dialog (anomalyco#8245) * feat: add Undertale and Deltarune built-in themes (anomalyco#8240) * chore: generate * feat(desktop): Ask Question Tool Support (anomalyco#8232) * fix(mcp): close existing client before reassignment to prevent leaks (anomalyco#8253) * fix(state): delete key from recordsByKey on instance disposal (anomalyco#8252) * docs: document ~/.claude/CLAUDE.md compatibility behavior (anomalyco#8268) * feat: Add GitLab Duo Agentic Chat Provider Support (anomalyco#7333) Co-authored-by: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Co-authored-by: Aiden Cline <aidenpcline@gmail.com> * fix(cli): mcp auth duplicate radio button icon (anomalyco#8273) * Update Nix flake.lock and x86_64-linux hash * Update aarch64-darwin hash * tweak: ensure external dir and bash tool invocations render workdir details * tweak: external dir permission rendering in tui * add family to gpt 5.2 codex in codex plugin * fix(prompt-input): handle Shift+Enter before IME check to prevent stuck state (anomalyco#8275) * feat: add plan mode with enter/exit tools (anomalyco#8281) * chore: generate * test: fix plan agent test path from .opencode/plan/* to .opencode/plans/* * remove plan * fix: update User-Agent string to latest Chrome version in webfetch (anomalyco#8284) * fix: Add Plugin Mocks to Provider Tests (anomalyco#8276) * chore: generate * tweak: prompt for explore agent better * do not allow agent to ask custom-less questions * release: v1.1.19 * fix(TUI): make tui work when OPENCODE_SERVER_PASSWORD is set (anomalyco#8179) * chore: generate * docs: Update plan mode restrictions (anomalyco#8290) * docs: add 302ai provider (anomalyco#8142) * fix: add missing metadata() and ask() defintions to ToolContext type (anomalyco#8269) * fix(tui): track all timeouts in Footer to prevent memory leak (anomalyco#8255) * fix: deduplicate file refs in sent prompts (anomalyco#8303) * chore: generate * chore: generate * Update Nix flake.lock and x86_64-linux hash * Update aarch64-darwin hash * fix(session): skip duplicate system prompt for Codex OAuth sessions (anomalyco#8357) Co-authored-by: Claude <noreply@anthropic.com> * feat: show connected providers in /connect dialog (anomalyco#8351) * fix(opencode): fix docker image after sst rename in tips (anomalyco#8376) * chore: generate * ignore: update download stats 2026-01-14 * docs(prd): mark codex token refresh PR task as complete - PR created at #298 - Fix includes: write token refresh to openai provider ID, fallback to legacy codex entry - Tests pass (744 pass, 1 skip, 0 fail) * test(auth): verify backwards compatibility for OAuth metadata fields - Add test confirming minimal OAuth results (without optional email, name, plan, orgName fields) persist correctly in auth storage - All new metadata fields are optional in plugin types and auth schema - Provider auth handler uses conditional checks before setting optional fields - Verify 745 pass, 1 skip, 0 fail * chore(prd): mark extractUserInfo tasks as complete The extractUserInfo function is already implemented in codex.ts:92-105. It parses id_token, extracts email, name, and accountId from claims, and returns a UserInfo object. All tests pass. * chore(prd): mark OAuth callback integration tasks as complete OAuth callback already calls extractUserInfo(tokens) after token exchange and includes email, name, accountId in the success payload. * fix(app): file listing (anomalyco#8309) * chore(prd): mark normalizePlanType tasks as complete normalizePlanType function maps plan values to standardized tiers (free, plus, pro, team, enterprise, unknown) and handles case variations. * feat(server): add GET /auth/info/:providerID endpoint for account metadata - Added endpoint in server.ts that returns auth metadata (authenticated, type, email, plan, accountId) - Returns 404 with authenticated: false if provider not found - Generated openapi.json with new endpoint definition - Regenerated SDK with auth.info method and types (AuthInfoData, AuthInfoResponses) - Updated prd.json to mark SDK generation tasks as complete - Tests pass: 745 pass, 1 skip, 0 fail * chore(prd): mark PR merge and SDK tasks as complete - Marked "Merge PR before starting Phase 1" as complete (PR #298 already merged) - Updated verification steps for auth.info endpoint implementation * chore(prd): mark legacy codex cleanup task as complete - Verified migration copies codex to openai, Auth.remove('codex') available for manual cleanup - Removal is intentionally manual to prevent data loss if migration fails * chore: mark session complete * chore(prd): mark background task implementation as complete - Verified fetchChatGPTUserInfo background task at codex.ts:606-632 - Task spawns via 'void updatePlan().catch(() => {})' - non-blocking - Updates auth metadata via auth.set when plan/orgName retrieved - OAuth success returns immediately regardless of background task result * chore(prd): mark manifest.ts creation as complete - Verified manifest.ts exists with InstalledSkill and SkillManifest interfaces - Implements loadManifest, saveManifest, getInstalled, addInstalled, removeInstalled - Used by skill installer to track installed skills and their metadata * chore(prd): mark skill index and installer files as complete - Verified skill/index.ts exists with SkillIndex interface and caching logic - Implements loadIndex (cache with TTL), buildIndex (fetch and write), search (fuzzysort) - Verified skill/installer.ts exists with installSkill and uninstallSkill functions - Copies skill files to SKILLS_DIR and updates manifest with installed metadata * fix plan mode when not in git worktree * chore(prd): mark github fetcher as complete - Verified skill/fetcher/github.ts exists with 200 lines implementing git and tarball fetching - fetchRegistry() entry point with hasGit() check and tarball fallback - scanSkills() walks directories matching SKILL.md globs with minimatch - parseSkillFile() extracts YAML frontmatter for skill metadata * chore(prd): mark clawdhub and url fetchers as complete - Verified skill/fetcher/clawdhub.ts exists with stub fetchRegistry returning [] - Verified skill/fetcher/url.ts exists with stub fetchRegistry returning [] - Both are TODO stubs awaiting API contract confirmation and implementation * fix(ui): layout-bottom icons (anomalyco#8330) * fix(desktop): "load more" button behavior in desktop sidebar (anomalyco#8430) * chore: generate * release: v1.1.20 * sync: record last synced tag v1.1.20 * fix: suppress TS2589 type recursion error in server route chain --------- Co-authored-by: Frank <frank@anoma.ly> Co-authored-by: Github Action <action@github.com> Co-authored-by: Leonidas <77194479+LeonMueller-OneAndOnly@users.noreply.github.com> Co-authored-by: Eduard Voiculescu <eduardvoiculescu95@gmail.com> Co-authored-by: ⌞L⌝ <151412975+mthezi@users.noreply.github.com> Co-authored-by: Daniel M Brasil <danielmbrasil@protonmail.com> Co-authored-by: Daniel Sauer <81422812+sauerdaniel@users.noreply.github.com> Co-authored-by: Felix Sanchez <felix.sanchez.dev@gmail.com> Co-authored-by: opencode <opencode@sst.dev> Co-authored-by: Dax Raad <d@ironbay.co> Co-authored-by: usvimal <usvimal@gmail.com> Co-authored-by: Daniel Polito <danielbpolito@gmail.com> Co-authored-by: Brendan Allan <git@brendonovich.dev> Co-authored-by: cmdr-chara <legend.alkalex07@gmail.com> Co-authored-by: Zeke Sikelianos <zeke@sikelianos.com> Co-authored-by: Vladimir Glafirov <vglafirov@gitlab.com> Co-authored-by: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Co-authored-by: Aiden Cline <aidenpcline@gmail.com> Co-authored-by: Dillon Mulroy <dillon.mulroy@gmail.com> Co-authored-by: Joe Harrison <22684038+josephbharrison@users.noreply.github.com> Co-authored-by: Dax <mail@thdxr.com> Co-authored-by: Alan <alan.thiec@gmail.com> Co-authored-by: zerone0x <hi@trine.dev> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Akshar Patel <123344143+AksharP5@users.noreply.github.com> Co-authored-by: Goni Zahavy <goni1993@gmail.com> Co-authored-by: Filip <34747899+neriousy@users.noreply.github.com> Co-authored-by: Andrew Jazbec <andrew@jazbec.io> Co-authored-by: Shane Bishop <71288697+shanebishop1@users.noreply.github.com>

docs: fix typos on the providers page

9384197

rekram1-node reviewed Jan 13, 2026

View reviewed changes

zeke force-pushed the docs-claude-compat branch from 033e17f to 2d52fdd Compare January 13, 2026 18:33

docs: clarify Claude Code files are fallbacks, not additive

d68ed5c

AGENTS.md takes precedence over CLAUDE.md at both project and global levels.

rekram1-node reviewed Jan 13, 2026

View reviewed changes

docs: simplify intro/project sections to only mention AGENTS.md

37356cc

Keep CLAUDE.md documentation in the Claude Code Compatibility section only.

rekram1-node merged commit 5947fe7 into anomalyco:dev Jan 13, 2026
4 checks passed

dl-alexandre pushed a commit to dl-alexandre/opencode that referenced this pull request Jan 13, 2026

docs: document ~/.claude/CLAUDE.md compatibility behavior (anomalyco#…

8ef7703

…8268)

fwang pushed a commit that referenced this pull request Jan 14, 2026

docs: document ~/.claude/CLAUDE.md compatibility behavior (#8268)

a184714

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: document ~/.claude/CLAUDE.md compatibility behavior #8268

docs: document ~/.claude/CLAUDE.md compatibility behavior #8268

zeke commented Jan 13, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 13, 2026

Uh oh!

rekram1-node Jan 13, 2026

Uh oh!

zeke Jan 13, 2026

Uh oh!

rekram1-node Jan 13, 2026

Uh oh!

rekram1-node Jan 13, 2026

Uh oh!

zeke Jan 13, 2026

Uh oh!

Uh oh!

rekram1-node commented Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		### Claude Code Compatibility

		For users migrating from or using both Claude Code and OpenCode, OpenCode also reads `~/.claude/CLAUDE.md`. This allows you to share instructions between both tools.

docs: document ~/.claude/CLAUDE.md compatibility behavior #8268

docs: document ~/.claude/CLAUDE.md compatibility behavior #8268

Conversation

zeke commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Testing locally

Uh oh!

github-actions bot commented Jan 13, 2026

Uh oh!

rekram1-node Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

zeke Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

rekram1-node Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

rekram1-node Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

zeke Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rekram1-node commented Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zeke commented Jan 13, 2026 •

edited

Loading