feat: add top-level 'command' config for custom agent executables by carmandale · Pull Request #119 · subsy/ralph-tui

carmandale · 2026-01-17T04:00:49Z

Summary

Adds a top-level command config option that allows users to specify a custom executable for their agent, enabling use of wrapper tools like Claude Code Router (CCR).

Usage

agent = "claude"
command = "ccr code"

This uses the Claude agent plugin but routes requests through CCR, which can proxy to alternative AI providers like OpenRouter, DeepSeek, Ollama, or Gemini.

Changes

Added command field to StoredConfigSchema (zod validation)
Added command field to StoredConfig type
Updated config merging to include command from project config
Updated applyAgentOptions() to apply command override to agent config

Testing

bun run typecheck passes
bun run lint passes
bun run build passes

Notes

The existing per-agent command field in the [[agents]] array already worked:

[[agents]]
name = "claude-ccr"
plugin = "claude"
command = "ccr code"

This PR adds the shorthand version for simpler configs.

Closes #102

Summary by CodeRabbit

New Features
- Add top-level and project-level "command" option to configs; project-level values override global and are applied to agent configs when not set at agent level.
Documentation
- Added examples, precedence notes, security guidance and a CCR routing example across docs.
Tests
- Added tests for merging behaviour and validation, including rejection of unsafe shell metacharacters.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

vercel · 2026-01-17T04:00:53Z

@carmandale is attempting to deploy a commit to the plgeek Team on Vercel.

A member of the Team first needs to authorize it.

coderabbitai · 2026-01-17T04:01:00Z

Walkthrough

Adds a new top-level public command field to stored configuration, validates it against shell metacharacters, merges project/global command with project precedence, and maps top-level command into agent defaults when the agent config lacks a command.

Changes

Cohort / File(s)	Summary
Config types & schema `src/config/types.ts`, `src/config/schema.ts`	Added optional `command?: string` to `StoredConfig` with JSDoc and Zod validation; refinement rejects shell metacharacters and documents precedence and usage.
Config runtime logic `src/config/index.ts`	`mergeConfigs` now preserves project-level `command` into the merged config; `getDefaultAgentConfig` maps `storedConfig.command` into an agent's `command` when the agent has none.
Tests `src/config/index.test.ts`, `src/config/schema.test.ts`	Added tests for `command` merge precedence, shorthand mapping to agent config, and validation acceptance/rejection of various command strings.
Documentation `website/content/docs/configuration/config-file.mdx`, `website/content/docs/configuration/options.mdx`, `website/content/docs/plugins/agents/claude.mdx`, `website/content/docs/plugins/agents/opencode.mdx`, `website/content/docs/troubleshooting/common-issues.mdx`	Added docs and callouts describing the `command` option, examples (including CCR/CCR routing), precedence, warnings about shell metacharacters, and shorthand usage tips.

Sequence Diagram(s)

sequenceDiagram
  participant ProjectConfig as Project TOML
  participant GlobalConfig as Global TOML
  participant Merger as mergeConfigs
  participant AgentFactory as getDefaultAgentConfig
  participant Agent as AgentPluginConfig

  ProjectConfig->>Merger: provide project StoredConfig (may include command)
  GlobalConfig->>Merger: provide global StoredConfig (may include command)
  Merger->>Merger: merge configs (project.command overrides global.command)
  Merger->>AgentFactory: supply merged StoredConfig
  AgentFactory->>Agent: if Agent.command undefined and merged.command set → set Agent.command = merged.command

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through configs, keen and fleet,
Found a command path both safe and neat.
Project first, then global's tune,
Agents now follow—no more maroon,
Wrappers guide the executable beat.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarises the main change: adding a top-level 'command' config option for custom agent executables, which is the primary feature introduced across all modified files.
Linked Issues check	✅ Passed	The PR successfully implements the core requirement from issue `#102`: providing a top-level command config shorthand (e.g., command = "ccr code") to enable wrapper tools like Claude Code Router, whilst preserving existing per-agent command support.
Out of Scope Changes check	✅ Passed	All code changes are directly scoped to issue `#102`'s objectives: config schema/types, validation logic, config merging, tests, and documentation for the new command field. No unrelated changes detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

subsy · 2026-01-17T10:16:03Z

This is the simple approach we need - will look at this properly later and get it in before the 0.2.0 release, thanks @carmandale

Improves PR #119 with the following changes: - Rename 'command' field to 'executable' for clarity - Avoids confusion with existing 'agentCommand' (which selects the agent plugin) - The new 'executable' field specifies the binary/path to run - Add shell metacharacter validation (security) - Rejects executables containing: ; & | \` $ ( ) - Prevents command injection via config files - Users must use wrapper scripts for complex commands - Add comprehensive JSDoc documentation - Documents precedence: agent-specific > top-level > plugin default - Includes usage examples - Add unit tests - Schema validation tests for valid/invalid executable paths - Config merging tests for executable field precedence

subsy · 2026-01-17T16:59:43Z

@carmandale

Thanks for this feature! I've pushed some refinements to your branch:

Security: Added validation that rejects shell metacharacters (;, &, |, `, $, (, )) in the executable path. This prevents potential command injection via config files. Users needing complex commands should use a wrapper script.

Docs & Tests: Added to docs on website, and added JSDoc documenting the precedence order (agent-specific > top-level > plugin default). Also added comprehensive unit tests for both validation and config merging.

Let me know if you have any questions!

PS - for future PRs it would be great if you could include tests and (if applicable) docs updates

codecov · 2026-01-17T17:02:05Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 46.72%. Comparing base (b3b1b9f) to head (10a653d).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #119      +/-   ##
==========================================
+ Coverage   45.61%   46.72%   +1.10%     
==========================================
  Files          58       58              
  Lines       13000    12947      -53     
==========================================
+ Hits         5930     6049     +119     
+ Misses       7070     6898     -172

Files with missing lines	Coverage Δ
src/config/index.ts	`67.57% <100.00%> (+28.51%)`	⬆️
src/config/schema.ts	`100.00% <100.00%> (ø)`
src/config/types.ts	`100.00% <ø> (ø)`

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…bsy#102) Users can now specify a custom command/executable for their agent: ```toml agent = "claude" command = "ccr code" ``` This enables use of wrapper tools like Claude Code Router (CCR) that proxy requests to alternative AI providers while using the Claude agent plugin. The 'command' field: - Added to StoredConfig schema and types - Merged from project config (project overrides global) - Applied to agent config via applyAgentOptions() - Only applied if not already set on the agent config Closes subsy#102

Improves PR subsy#119 with the following changes: - Rename 'command' field to 'executable' for clarity - Avoids confusion with existing 'agentCommand' (which selects the agent plugin) - The new 'executable' field specifies the binary/path to run - Add shell metacharacter validation (security) - Rejects executables containing: ; & | \` $ ( ) - Prevents command injection via config files - Users must use wrapper scripts for complex commands - Add comprehensive JSDoc documentation - Documents precedence: agent-specific > top-level > plugin default - Includes usage examples - Add unit tests - Schema validation tests for valid/invalid executable paths - Config merging tests for executable field precedence

- Add executable to Core Settings table in options.mdx - Add detailed Custom Executable section with CCR example - Document precedence order and security constraints - Add Alternative AI Provider example in config-file.mdx - Update complete example to show executable option

- Add executable tip to Claude plugin options section - Add executable tip to OpenCode plugin options section - Add executable config as solution in "Agent not found" troubleshooting

Reverts the rename from 'command' to 'executable' to maintain consistency with the existing agent-level 'command' field in [[agents]] array. Changes: - Rename 'executable' back to 'command' in schema, types, and config - Update all docs to use 'command' instead of 'executable' - Add buildConfig tests for command shorthand (improves coverage 38%->67%) - Test command precedence: agent-level > top-level > plugin default The top-level 'command' now matches the agent-level 'command', making the config more intuitive: they do the same thing at different levels.

vercel · 2026-01-17T17:37:26Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
ralph-tui	Ready	Preview, Comment	Jan 17, 2026 5:37pm

gbks121 · 2026-01-17T19:10:47Z

Thank you @subsy & @carmandale for getting my feature request in!
Cant wait to use ralph-tui with CCR :)

Improves PR subsy#119 with the following changes: - Rename 'command' field to 'executable' for clarity - Avoids confusion with existing 'agentCommand' (which selects the agent plugin) - The new 'executable' field specifies the binary/path to run - Add shell metacharacter validation (security) - Rejects executables containing: ; & | \` $ ( ) - Prevents command injection via config files - Users must use wrapper scripts for complex commands - Add comprehensive JSDoc documentation - Documents precedence: agent-specific > top-level > plugin default - Includes usage examples - Add unit tests - Schema validation tests for valid/invalid executable paths - Config merging tests for executable field precedence

…ent-command feat: add top-level 'command' config for custom agent executables

subsy force-pushed the feat/issue-102-custom-agent-command branch from 61cb1b0 to 580593f Compare January 17, 2026 16:57

carmandale and others added 5 commits January 17, 2026 17:34

docs: add executable references to plugin and troubleshooting pages

9193bb0

- Add executable tip to Claude plugin options section - Add executable tip to OpenCode plugin options section - Add executable config as solution in "Agent not found" troubleshooting

subsy force-pushed the feat/issue-102-custom-agent-command branch from 279f575 to 10a653d Compare January 17, 2026 17:34

vercel bot deployed to Preview January 17, 2026 17:37 View deployment

subsy merged commit 6d64a50 into subsy:main Jan 17, 2026
9 checks passed

This was referenced Jan 22, 2026

feat: add envExclude option to filter environment variables for agents #190

Merged

fix: pass command config to agent in create-prd and doctor commands #191

Merged

Centralize agent configuration resolution logic #229

Merged

sakaman pushed a commit to sakaman/ralph-tui that referenced this pull request Feb 15, 2026

Merge pull request subsy#119 from carmandale/feat/issue-102-custom-ag…

2ad2390

…ent-command feat: add top-level 'command' config for custom agent executables

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add top-level 'command' config for custom agent executables#119

feat: add top-level 'command' config for custom agent executables#119
subsy merged 5 commits intosubsy:mainfrom
carmandale:feat/issue-102-custom-agent-command

carmandale commented Jan 17, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

vercel bot commented Jan 17, 2026

Uh oh!

coderabbitai bot commented Jan 17, 2026 •

edited

Loading

Uh oh!

subsy commented Jan 17, 2026

Uh oh!

subsy commented Jan 17, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 17, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 17, 2026

Uh oh!

Uh oh!

gbks121 commented Jan 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

Conversation

carmandale commented Jan 17, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Usage

Changes

Testing

Notes

Summary by CodeRabbit

Uh oh!

vercel bot commented Jan 17, 2026

Uh oh!

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

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Poem

Uh oh!

subsy commented Jan 17, 2026

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

vercel bot commented Jan 17, 2026

Uh oh!

Uh oh!

gbks121 commented Jan 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

carmandale commented Jan 17, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Jan 17, 2026 •

edited

Loading

subsy commented Jan 17, 2026 •

edited

Loading

codecov bot commented Jan 17, 2026 •

edited

Loading