anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-21 17:56:33 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

[PR #6174] docs: document ~/.opencode as valid global config directory #11764

New Issue
Open
opened 2026-02-16 18:16:42 -05:00 by yindo · 0 comments
yindo commented 2026-02-16 18:16:42 -05:00
Owner
Copy Link
Copy Source

Original Pull Request: https://github.com/anomalyco/opencode/pull/6174

State: open
Merged: No

Problem Statement

What pain point in the dev workflow does this address?

Users who version control their OpenCode configurations in ~/.opencode/ (instead of ~/.config/opencode/) found that the documentation was inconsistent about which paths are valid for global configuration.

What was the previous state?

  • Skills docs mentioned only ~/.opencode/skill/ and incorrectly listed .claude/skills/ as supported
  • Other docs (agents, commands, modes, plugins, tools) mentioned only ~/.config/opencode/
  • Users were confused about which path to use

Why is this change needed now?

Issue #6171 reported this inconsistency. Users need clear documentation to properly organize their configurations.

Technical Changes

High-level approach:

Updated all configuration documentation to consistently document both ~/.config/opencode/ and ~/.opencode/ as valid global configuration directories.

Key components modified/added:

  • packages/web/src/content/docs/skills.mdx - Complete rewrite with table format, XDG note
  • packages/web/src/content/docs/agents.mdx - Added ~/.opencode/agent/
  • packages/web/src/content/docs/commands.mdx - Added ~/.opencode/command/
  • packages/web/src/content/docs/modes.mdx - Added ~/.opencode/mode/
  • packages/web/src/content/docs/plugins.mdx - Added ~/.opencode/plugin/
  • packages/web/src/content/docs/custom-tools.mdx - Added ~/.opencode/tool/
  • packages/web/src/content/docs/config.mdx - Updated agent/command references

Design decisions and rationale:

The code in packages/opencode/src/config/config.ts (lines 70-86) shows that BOTH paths are scanned:

const directories = [
  Global.Path.config,  // ~/.config/opencode (XDG)
  ...(await Array.fromAsync(
    Filesystem.up({
      targets: [".opencode"],  // Scans for .opencode directories
      start: Instance.directory,
      stop: Instance.worktree,
    }),
  )),
  ...(await Array.fromAsync(
    Filesystem.up({
      targets: [".opencode"],  // Also scans ~/.opencode
      start: Global.Path.home,
      stop: Global.Path.home,
    }),
  )),
]

And lines 108-112 confirm ALL features use this same directory list:

result.command = mergeDeep(result.command ?? {}, await loadCommand(dir))
result.agent = mergeDeep(result.agent, await loadAgent(dir))
result.agent = mergeDeep(result.agent, await loadMode(dir))
result.plugin.push(...(await loadPlugin(dir)))

Skills also use Config.directories() in packages/opencode/src/skill/skill.ts.

Alternatives considered:

Could have documented only ~/.config/opencode/ as the canonical path, but since ~/.opencode/ is actively supported in the code and some users prefer it for dotfiles management, documenting both is the correct approach.

Dependencies added/updated:

  • None

Impact

For Developers

New commands/workflows available:

No new commands - this is documentation only.

Changed behavior:

None - the code already supported both paths.

Breaking changes:

  • No breaking changes

For AI Agents

Can agents discover and use the new functionality?

  • Documented in skills.mdx and other docs
  • Commands are self-documenting
  • N/A for session management

How does this enhance agent capabilities?

N/A - documentation fix only.

Verification

Automated Tests

  • N/A - documentation only change

Manual Testing

  • Verified code paths in config.ts confirm both directories are scanned
  • Removed incorrect .claude/skills/ reference (not supported in code)

Manual testing steps performed:

  1. Reviewed packages/opencode/src/config/config.ts lines 70-112
  2. Reviewed packages/opencode/src/skill/skill.ts to confirm it uses Config.directories()
  3. Searched codebase for .claude/skills - confirmed it's NOT supported

Related Work

Related PRs/Issues:

Changelog Entry

Type: docs

Summary (1-2 lines):

Document that both ~/.config/opencode/ and ~/.opencode/ are valid global configuration directories for all features (agents, commands, modes, plugins, skills, tools).

Full entry:

- docs: document ~/.opencode as valid global config directory for all features
**Original Pull Request:** https://github.com/anomalyco/opencode/pull/6174 **State:** open **Merged:** No --- ## Problem Statement **What pain point in the dev workflow does this address?** Users who version control their OpenCode configurations in `~/.opencode/` (instead of `~/.config/opencode/`) found that the documentation was inconsistent about which paths are valid for global configuration. **What was the previous state?** - Skills docs mentioned only `~/.opencode/skill/` and incorrectly listed `.claude/skills/` as supported - Other docs (agents, commands, modes, plugins, tools) mentioned only `~/.config/opencode/` - Users were confused about which path to use **Why is this change needed now?** Issue #6171 reported this inconsistency. Users need clear documentation to properly organize their configurations. --- ## Technical Changes **High-level approach:** Updated all configuration documentation to consistently document both `~/.config/opencode/` and `~/.opencode/` as valid global configuration directories. **Key components modified/added:** - `packages/web/src/content/docs/skills.mdx` - Complete rewrite with table format, XDG note - `packages/web/src/content/docs/agents.mdx` - Added ~/.opencode/agent/ - `packages/web/src/content/docs/commands.mdx` - Added ~/.opencode/command/ - `packages/web/src/content/docs/modes.mdx` - Added ~/.opencode/mode/ - `packages/web/src/content/docs/plugins.mdx` - Added ~/.opencode/plugin/ - `packages/web/src/content/docs/custom-tools.mdx` - Added ~/.opencode/tool/ - `packages/web/src/content/docs/config.mdx` - Updated agent/command references **Design decisions and rationale:** The code in `packages/opencode/src/config/config.ts` (lines 70-86) shows that BOTH paths are scanned: ```typescript const directories = [ Global.Path.config, // ~/.config/opencode (XDG) ...(await Array.fromAsync( Filesystem.up({ targets: [".opencode"], // Scans for .opencode directories start: Instance.directory, stop: Instance.worktree, }), )), ...(await Array.fromAsync( Filesystem.up({ targets: [".opencode"], // Also scans ~/.opencode start: Global.Path.home, stop: Global.Path.home, }), )), ] ``` And lines 108-112 confirm ALL features use this same directory list: ```typescript result.command = mergeDeep(result.command ?? {}, await loadCommand(dir)) result.agent = mergeDeep(result.agent, await loadAgent(dir)) result.agent = mergeDeep(result.agent, await loadMode(dir)) result.plugin.push(...(await loadPlugin(dir))) ``` Skills also use `Config.directories()` in `packages/opencode/src/skill/skill.ts`. **Alternatives considered:** Could have documented only `~/.config/opencode/` as the canonical path, but since `~/.opencode/` is actively supported in the code and some users prefer it for dotfiles management, documenting both is the correct approach. **Dependencies added/updated:** - None --- ## Impact ### For Developers **New commands/workflows available:** No new commands - this is documentation only. **Changed behavior:** None - the code already supported both paths. **Breaking changes:** - [x] No breaking changes ### For AI Agents **Can agents discover and use the new functionality?** - [x] Documented in skills.mdx and other docs - [x] Commands are self-documenting - [x] N/A for session management **How does this enhance agent capabilities?** N/A - documentation fix only. --- ## Verification ### Automated Tests - [x] N/A - documentation only change ### Manual Testing - [x] Verified code paths in config.ts confirm both directories are scanned - [x] Removed incorrect `.claude/skills/` reference (not supported in code) **Manual testing steps performed:** 1. Reviewed `packages/opencode/src/config/config.ts` lines 70-112 2. Reviewed `packages/opencode/src/skill/skill.ts` to confirm it uses Config.directories() 3. Searched codebase for `.claude/skills` - confirmed it's NOT supported --- ## Related Work **Related PRs/Issues:** - Closes #6171 --- ## Changelog Entry **Type:** docs **Summary (1-2 lines):** Document that both `~/.config/opencode/` and `~/.opencode/` are valid global configuration directories for all features (agents, commands, modes, plugins, skills, tools). **Full entry:** ``` - docs: document ~/.opencode as valid global config directory for all features ```
yindo added the pull-request label 2026-02-16 18:16:42 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#11764
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?