Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): add hermes agent-docs target for astryx init (#3699)

Harjoth Khara10ebefa44d33
diff --git a/.changeset/cli-hermes-agent-target.md b/.changeset/cli-hermes-agent-target.md
new file mode 100644
index 0000000000..24ae74b6ca
--- /dev/null
+++ b/.changeset/cli-hermes-agent-target.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx init --features agents` now supports `--agent hermes`. The preset injects the component index into an existing `.hermes.md`/`HERMES.md` (Hermes Agent's top-priority project-context files) and otherwise creates root `AGENTS.md`, which Hermes loads from the project root — unlike the `.claude/CLAUDE.md` default. Additive only: existing `claude`/`cursor`/`codex`/`all`/auto-detect behavior is unchanged. (#2187)
+
+@harjothkhara
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjs
index 11cbfa3006..3deef40a64 100644
--- a/packages/cli/src/commands/agent-docs.mjs
+++ b/packages/cli/src/commands/agent-docs.mjs
@@ -9,11 +9,12 @@
* - Claude Code: CLAUDE.md (root) or .claude/CLAUDE.md
* - Cursor: .cursorrules
* - Codex/generic: AGENTS.md
+ * - Hermes Agent: .hermes.md or HERMES.md (existing), else AGENTS.md
*
* Auto-detect: discovers existing files and updates them in place.
* Default (no existing files): creates .claude/CLAUDE.md.
*
- * --agent <tool>: target a specific tool preset (claude, cursor, codex, all)
+ * --agent <tool>: target a specific tool preset (claude, cursor, codex, hermes, all)
* --agent-docs-path <path>: explicit file path(s)
*/
@@ -46,6 +47,7 @@ const AGENT_PRESETS = {
claude: [CLAUDE_MD, CLAUDE_DIR_MD],
cursor: ['.cursorrules', AGENTS_MD],
codex: [AGENTS_MD],
+ hermes: ['.hermes.md', 'HERMES.md', AGENTS_MD],
};
/**
@@ -64,7 +66,7 @@ export function discoverAgentDocs(targetDir) {
* Searches for existing files first, falls back to default creation path.
*
* @param {string} targetDir
- * @param {string} agent - Preset name: 'claude', 'cursor', 'codex', 'all'
+ * @param {string} agent - Preset name: 'claude', 'cursor', 'codex', 'hermes', 'all'
* @returns {{inject: string[], create: string[]}} Files to inject into vs create fresh
*/
export function resolveAgentPaths(targetDir, agent) {
@@ -386,7 +388,7 @@ export function removeAgentDocs(targetDir) {
* @param {object} [options]
* @param {boolean} [options.zh]
* @param {string} [options.lang]
- * @param {string} [options.agent] - Tool preset: 'claude', 'cursor', 'codex', 'all'
+ * @param {string} [options.agent] - Tool preset: 'claude', 'cursor', 'codex', 'hermes', 'all'
* @param {string[]} [options.paths] - Explicit paths (overrides agent/auto-detect)
* @param {boolean} [options.onlyReplace] - Only update files that already have Astryx markers (for upgrades)
* @returns {string[]} List of files written
@@ -468,14 +470,14 @@ export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onl
return written;
}
-const VALID_AGENTS = ['claude', 'cursor', 'codex', 'all'];
+const VALID_AGENTS = ['claude', 'cursor', 'codex', 'hermes', 'all'];
export function registerAgentDocs(program) {
program
.command('agent-docs')
.description('Install/update the component index for AI coding agents')
.option('--remove', 'Remove the design system section from all agent doc files')
- .option('--agent <tool>', 'Target tool: claude, cursor, codex, all')
+ .option('--agent <tool>', 'Target tool: claude, cursor, codex, hermes, all')
.option('--agent-docs-path <path...>', 'Explicit file path(s) to write to')
.action(options => {
const targetDir = process.cwd();
diff --git a/packages/cli/src/commands/agent-docs.test.mjs b/packages/cli/src/commands/agent-docs.test.mjs
index d989865516..bdd2c9124b 100644
--- a/packages/cli/src/commands/agent-docs.test.mjs
+++ b/packages/cli/src/commands/agent-docs.test.mjs
@@ -449,6 +449,17 @@ describe('installAgentDocs', () => {
expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);
});
+ it('respects --agent hermes preset: creates AGENTS.md', () => {
+ setupCorePackage(tmpDir);
+
+ const written = installAgentDocs(tmpDir, {agent: 'hermes'});
+
+ expect(written).toEqual(['AGENTS.md']);
+ const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+ expect(content).toContain('<!-- ASTRYX:START -->');
+ expect(fs.existsSync(path.join(tmpDir, '.claude'))).toBe(false);
+ });
+
it('respects explicit --paths', () => {
setupCorePackage(tmpDir);
@@ -548,4 +559,26 @@ describe('resolveAgentPaths', () => {
expect(result.create).toContain('AGENTS.md');
expect(result.create).toContain('.claude/CLAUDE.md');
});
+
+ it('hermes preset creates AGENTS.md when nothing exists', () => {
+ const result = resolveAgentPaths(tmpDir, 'hermes');
+ expect(result).toEqual({inject: [], create: ['AGENTS.md']});
+ });
+
+ it('hermes preset finds existing .hermes.md', () => {
+ fs.writeFileSync(path.join(tmpDir, '.hermes.md'), '');
+ const result = resolveAgentPaths(tmpDir, 'hermes');
+ expect(result).toEqual({inject: ['.hermes.md'], create: []});
+ });
+
+ it('hermes preset finds existing HERMES.md when no .hermes.md', () => {
+ fs.writeFileSync(path.join(tmpDir, 'HERMES.md'), '');
+ const result = resolveAgentPaths(tmpDir, 'hermes');
+ expect(result).toEqual({inject: ['HERMES.md'], create: []});
+ });
+
+ it('claude preset still creates .claude/CLAUDE.md when nothing exists (hermes is additive)', () => {
+ const result = resolveAgentPaths(tmpDir, 'claude');
+ expect(result).toEqual({inject: [], create: ['.claude/CLAUDE.md']});
+ });
});
diff --git a/packages/cli/src/commands/init.mjs b/packages/cli/src/commands/init.mjs
index a267b87337..8b5507fbba 100644
--- a/packages/cli/src/commands/init.mjs
+++ b/packages/cli/src/commands/init.mjs
@@ -198,7 +198,7 @@ export function registerInit(program) {
.option('--features <list>', 'Comma-separated features to install (agents, theme, template)')
.option('--all', 'Install all features, no prompts')
.option('--remove-agents', 'Remove AI agent docs from all agent doc files')
- .option('--agent <tool>', 'Target AI tool for agent docs: claude, cursor, codex, all')
+ .option('--agent <tool>', 'Target AI tool for agent docs: claude, cursor, codex, hermes, all')
.option('--agent-docs-path <path...>', 'Explicit file path(s) for agent docs')
.action(async (options) => {
const targetDir = process.cwd();