Summary
When configuring an agent with command and args fields in ~/.acpx/config.json:
{
"agents": {
"cursor": {
"command": "/home/logan/.local/bin/agent",
"args": ["acp"]
}
}
}
The args array is silently ignored. Only the command field is read. This causes the spawned agent to run without the intended arguments, leading to protocol initialization failures.
Root Cause
In src/config.ts, parseAgents() only reads raw.command and discards raw.args:
function parseAgents(value: unknown, sourcePath: string): Record<string, string> | undefined {
...
for (const [name, raw] of Object.entries(value)) {
...
const command = raw.command;
// raw.args is never read!
parsed[normalizeAgentName(name)] = command.trim();
}
}
The config schema accepts {command, args} but the runtime code ignores args.
Impact
- Custom agent commands that require arguments (e.g., Cursor CLI with
agent acp) silently fail
- The agent process starts but without the correct subcommand, causing ACP protocol initialization to hang
- The schema shows
args as supported in acpx config show, but the field has no effect
Expected Behavior
parseAgents() should merge command and args into the final command string, e.g.:
const fullCommand = raw.args && raw.args.length > 0
? `${raw.command.trim()} ${raw.args.join(" ")}`
: raw.command.trim();
parsed[normalizeAgentName(name)] = fullCommand;
Workaround
Put the full command (including args) in the command field as a single string:
{
"agents": {
"cursor": {
"command": "/home/logan/.local/bin/agent acp"
}
}
}
Environment
- acpx version: 0.3.1, 0.4.0, latest main
- OS: Linux (WSL2)
- Node.js: v22.22.0
Summary
When configuring an agent with
commandandargsfields in~/.acpx/config.json:{ "agents": { "cursor": { "command": "/home/logan/.local/bin/agent", "args": ["acp"] } } }The
argsarray is silently ignored. Only thecommandfield is read. This causes the spawned agent to run without the intended arguments, leading to protocol initialization failures.Root Cause
In
src/config.ts,parseAgents()only readsraw.commandand discardsraw.args:The config schema accepts
{command, args}but the runtime code ignoresargs.Impact
agent acp) silently failargsas supported inacpx config show, but the field has no effectExpected Behavior
parseAgents()should mergecommandandargsinto the final command string, e.g.:Workaround
Put the full command (including args) in the
commandfield as a single string:{ "agents": { "cursor": { "command": "/home/logan/.local/bin/agent acp" } } }Environment