fix(opencode): align agent create command with doc paths

[volker48]

What does this PR do?

Fixes #12302 Aligns the CLI agent create command output path with the agents path referenced in the docs.

How did you verify your code works?

Ran all tests and ran the updated command as well.

[github-actions]

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

No duplicate PRs found

[kunzaatko]

I already pointed out at #14427

This is a mismatch with the docs but both of the directories .opencode/agent/ and .opencode/agents/ are included for the agent resolution so this should not interfere with finding the agent at runtime.

 

opencode/packages/opencode/src/config/config.ts

Lines 422 to 459 in b9f6b40

	async function loadAgent(dir: string) {
	const result: Record<string, Agent> = {}
	for (const item of await Glob.scan("{agent,agents}/**/*.md", {
	cwd: dir,
	absolute: true,
	dot: true,
	symlink: true,
	})) {
	const md = await ConfigMarkdown.parse(item).catch(async (err) => {
	const message = ConfigMarkdown.FrontmatterError.isInstance(err)
	? err.data.message
	: `Failed to parse agent ${item}`
	const { Session } = await import("@/session")
	Bus.publish(Session.Event.Error, { error: new NamedError.Unknown({ message }).toObject() })
	log.error("failed to load agent", { agent: item, err })
	return undefined
	})
	if (!md) continue
	const patterns = ["/.opencode/agent/", "/.opencode/agents/", "/agent/", "/agents/"]
	const file = rel(item, patterns) ?? path.basename(item)
	const agentName = trim(file)
	const config = {
	name: agentName,
	...md.data,
	prompt: md.content.trim(),
	}
	const parsed = Agent.safeParse(config)
	if (parsed.success) {
	result[config.name] = parsed.data
	continue
	}
	throw new InvalidError({ path: item, issues: parsed.error.issues }, { cause: parsed.error })
	}
	return result
	}

There are two possibilities to solve this:

1. Update the documentation to include both of the directories
2. Use only the one that is included in the documentation (which would be a harsh breaking change)

I lean towards the first one... This should be a documentation change instead of implementation change...

Or perhaps if the agent/ directory is to be deprecated, it should be soft deprecated first and this is the correct path to do that.

[volker48]

I already pointed out at #14427
@kunzaatko yeah sorry my MR was created long before 14427.

[scarnago]

+1 on fixing this, but I'd like to suggest a soft-deprecation approach with a migration path.

I independently hit this exact issue today while auditing my agent setup. The mismatch between opencode agent create → agent/ and the documented agents/ caused real fragmentation in my local config:

~/.config/opencode/
├── agent/ ← legacy, one-off agents created via CLI
└── agents/ ← canonical, manually maintained agents

This split is confusing for users who read the docs, configure agents manually in agents/, but then use opencode agent create for quick prototypes. End result: agents scattered across both directories.

I agree with @kunzaatko that an abrupt breaking change is risky. To move forward safely, I recommend:

1. Merge this PR to fix the CLI default → agents/
2. Add a runtime console warning when loading agents from agent/ (e.g. "Deprecation: agents in agent/ should be moved to agents/")
3. Keep Glob.scan("{agent,agents}/**/*.md") in config.ts for backwards compat during a deprecation window (e.g. 2-3 releases)
4. Update docs to mention agent/ as "legacy, will be deprecated"
   This way the CLI aligns with docs immediately, nobody breaks, and there's a clear path forward.
   Happy to test the migration path once this lands.

[rekram1-node]

Automated PR Cleanup

Thank you for contributing to opencode.

Due to the high volume of PRs from users and AI agents, we periodically close older PRs using automated criteria so maintainers can focus review time on the most active and community-supported contributions.

This PR was closed because it matched the following cleanup criteria:

• The PR was created more than 1 month ago
• The PR had fewer than 2 positive reactions
• Positive reactions are counted as thumbs-up, heart, celebration, or rocket reactions on the PR

PRs created within the last month are not affected by this cleanup.

If you believe this PR was closed incorrectly, or if you are still actively working on it, please leave a comment explaining why it should be reopened. A maintainer can review and reopen it if appropriate.

Thanks again for taking the time to contribute.