🤖 feat: add custom executable slash commands (.mux/commands/) #1523

ammar-agent · 2026-01-09T02:27:52Z

Summary

Adds support for custom slash commands that run executables in the workspace.

Features

Discovery: Executables at .mux/commands/<name> are discovered and appear in slash command autocomplete
Execution: /<name> [args...] runs the command with:
- First line tokens become argv
- Lines after the first become stdin
- Stdout streams in real-time via init events
- Stdout becomes the user message on success
Environment: Commands receive MUX_* env vars (project path, runtime, workspace name, workspace path)

Example

#!/bin/bash
# .mux/commands/refinement
echo "Refine this:"
cat

Then use with: /refinement\n<text to refine>

Implementation

Backend: SlashCommandService for discovery and execution with streaming
Frontend: Parser extended with rawInput for unknown commands
Frontend: ChatInput wired to execute custom commands and show autocomplete
Docs: New page at docs/hooks/slash-commands.mdx

Testing

All slash command parser and suggestion tests pass
Static checks pass
New functionality is exercised through manual testing

Generated with mux • Model: anthropic:claude-opus-4-5 • Thinking: high • Cost: $11.85

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8152aa515

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

src/node/services/slashCommandService.ts

src/browser/components/ChatInput/index.tsx

ammar-agent · 2026-01-09T02:58:15Z

@codex review

Addressed the P1 and P2 review comments:

P1: Now quoting command path before exec to handle spaces in workspace paths
P2: Removed .trim() from stdin processing to preserve whitespace

Also added:

Exit code 2 handling (show output but don't send to model)
Progressive examples in docs (static msg, args, stdin)
UI integration tests covering suggestions, execution, exit codes
Unit tests for custom command suggestions

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ccbeaea806

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

src/node/services/slashCommandService.ts

src/browser/components/ChatInput/index.tsx

ammar-agent · 2026-01-09T03:13:56Z

@codex review

Addressed additional review comments:

P2: Now accumulating raw stdout bytes to preserve blank lines (LineBuffer drops empty lines for streaming display, but the final output preserves them)
P3: Now restoring input when command produces no output (consistent with other error paths)

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 04ddac9a3d

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

src/node/services/slashCommandService.ts

ammar-agent · 2026-01-09T03:19:11Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 11cc4f1b8e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

src/node/services/slashCommandService.ts

Adds support for custom slash commands that run executables in the workspace. ## Features - **Discovery**: Executables at `.mux/commands/<name>` are discovered and appear in slash command autocomplete. - **Execution**: `/<name> [args...]` runs the command with: - First line tokens become argv - Lines after the first become stdin - Stdout streams in real-time via init events - Stdout becomes the user message on success - **Environment**: Commands receive MUX_* env vars (project path, runtime, workspace name, workspace path). ## Implementation - Backend: SlashCommandService for discovery and execution with streaming - Frontend: Parser extended with rawInput for unknown commands - Frontend: ChatInput wired to execute custom commands and show autocomplete - Docs: New page at docs/hooks/slash-commands.mdx ## Example ```bash #!/bin/bash # .mux/commands/refinement echo "Refine this:" cat ``` Then use with: `/refinement\n<text to refine>`

- Quote command path before exec to handle spaces in workspace paths (P1) - Preserve stdin whitespace - don't trim multiline input (P2) - Add exit code 2 handling: show output but don't send to model - Update docs with progressive examples (static msg, args, stdin) - Add comprehensive UI integration tests for custom slash commands - Add unit tests for custom command suggestions

- Remove UI integration tests that were timing out in CI - Add backend integration tests for slash command functionality: - Command discovery (list) - Command execution (run) - Exit code handling (0, 2, others) - Argument and stdin passing

- P2: Preserve blank lines in command stdout by accumulating raw bytes instead of using LineBuffer (which drops empty lines) - P3: Restore input when command produces no output (consistent error handling)

…tion

Static files are read verbatim (no execution required): - .mux/commands/<name>.txt - .mux/commands/<name>.md This is simpler than writing an executable script for static prompts. Static files are preferred over executables with the same base name (.txt checked first, then .md, then bare executable).

- Add 'custom' badge to distinguish custom commands from built-in ones - Add 'Add custom commands' docs link in autocomplete footer - Add isCustom property to SlashSuggestion type - Add slashCommands mock support for storybook - Create App.slashCommands.stories.tsx with: - BuiltInCommands: shows standard slash commands - WithCustomCommands: shows custom commands with badge - FilteredCommands: shows filtering behavior

Reduces duplication between static file and executable command paths by: - Adding withCommandLifecycle() to handle init-start/end lifecycle and error handling - Adding emitOutput() helper for streaming lines - Both runStaticFile() and runExecutable() now use these helpers Net reduction: ~50 lines (~15% less code)

- Badge now appears before command name to reduce visual scanning - Custom command text uses plan-mode-light color for visual distinction

- Drop .txt support, only .md files for static commands - Parse YAML frontmatter from .md files for description field - Parse magic comment '# mux: <description>' from executables - API returns skippedInvalidNames to help users debug invalid command names - Badge now appears after command name for consistent vertical alignment - Descriptions shown in autocomplete suggestions New shared utility: src/node/utils/markdown.ts (simple frontmatter parsing)

- Frontmatter field changed from 'description' to 'usage' - Executable comment changed from '# mux: ...' to '# usage: ...' - Updated all docs examples to show usage comments - Pattern is case-insensitive for flexibility The 'usage:' pattern is more conventional and self-documenting.

Replace generic /context example with /todo - finds TODO/FIXME comments and asks the model to help address them. More practical demonstration of dynamic content.

Adds a deterministic streaming test that uses file-based synchronization to prove output accumulates progressively during slash command execution. The test creates an executable command that signals via temp files between steps, allowing the test to verify streaming works without timing-based flakiness.

When switching between storybook stories, the MemoryRouter was not re-reading initialEntries from localStorage because it wasn't being remounted. This caused custom slash commands to not appear because the router stayed on the previous story's workspace. Adding key={storyId} forces AppLoader (and its child MemoryRouter) to remount when the story changes, ensuring the router reads the correct workspace selection from localStorage.

mintlify bot deployed to staging - docs January 9, 2026 02:28 View deployment

chatgpt-codex-connector bot reviewed Jan 9, 2026

View reviewed changes

src/node/services/slashCommandService.ts Outdated Show resolved Hide resolved

src/browser/components/ChatInput/index.tsx Outdated Show resolved Hide resolved

ammar-agent added the docs Improvements or additions to documentation label Jan 9, 2026

mintlify bot deployed to staging - docs January 9, 2026 02:58 View deployment

chatgpt-codex-connector bot reviewed Jan 9, 2026

View reviewed changes

src/node/services/slashCommandService.ts Outdated Show resolved Hide resolved

src/browser/components/ChatInput/index.tsx Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Jan 9, 2026

View reviewed changes

src/node/services/slashCommandService.ts Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Jan 9, 2026

View reviewed changes

src/node/services/slashCommandService.ts Outdated Show resolved Hide resolved

ammar-agent force-pushed the slash-commands-891j branch from 11cc4f1 to 825fabf Compare January 9, 2026 06:03

mintlify bot deployed to staging - docs January 9, 2026 06:04 View deployment

ammar-agent added 8 commits January 14, 2026 17:59

fix: address additional Codex review comments

4c0b1da

- P2: Preserve blank lines in command stdout by accumulating raw bytes instead of using LineBuffer (which drops empty lines) - P3: Restore input when command produces no output (consistent error handling)

fix: use separate TextDecoder per stream to avoid cross-stream corrup…

aca34c5

…tion

fix: cap and flush slash command stdout

f566585

tests: add UI smoke test for custom slash commands

11a13e8

fix: run custom slash commands via cwd-relative paths

2941d90

ammar-agent force-pushed the slash-commands-891j branch from 0eb1c76 to 2941d90 Compare January 14, 2026 23:59

mintlify bot deployed to staging - docs January 15, 2026 00:00 View deployment

mintlify bot deployed to staging - docs January 15, 2026 00:08 View deployment

ammar-agent force-pushed the slash-commands-891j branch from 7fdb7f8 to 13e6ee3 Compare January 15, 2026 00:10

mintlify bot deployed to staging - docs January 15, 2026 00:10 View deployment

ammar-agent force-pushed the slash-commands-891j branch from 13e6ee3 to a684aae Compare January 15, 2026 00:11

mintlify bot deployed to staging - docs January 15, 2026 00:11 View deployment

ammar-agent force-pushed the slash-commands-891j branch from a684aae to ab2bb5d Compare January 15, 2026 00:17

mintlify bot deployed to staging - docs January 15, 2026 00:18 View deployment

ammar-agent force-pushed the slash-commands-891j branch from 23be909 to 66b2949 Compare January 15, 2026 00:29

ammar-agent added 4 commits January 14, 2026 18:40

feat: move custom badge to left and use distinct text color

d45b612

- Badge now appears before command name to reduce visual scanning - Custom command text uses plan-mode-light color for visual distinction

mintlify bot deployed to staging - docs January 15, 2026 00:59 View deployment

mintlify bot deployed to staging - docs January 15, 2026 01:01 View deployment

docs: improve executable command example

bf0777d

Replace generic /context example with /todo - finds TODO/FIXME comments and asks the model to help address them. More practical demonstration of dynamic content.

ammar-agent force-pushed the slash-commands-891j branch from 6083c12 to bf0777d Compare January 15, 2026 01:01

mintlify bot deployed to staging - docs January 15, 2026 01:04 View deployment

ammar-agent added 2 commits January 14, 2026 19:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

🤖 feat: add custom executable slash commands (.mux/commands/) #1523

🤖 feat: add custom executable slash commands (.mux/commands/) #1523

Uh oh!

ammar-agent commented Jan 9, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

Uh oh!

ammar-agent commented Jan 9, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

Uh oh!

ammar-agent commented Jan 9, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

ammar-agent commented Jan 9, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

🤖 feat: add custom executable slash commands (.mux/commands/) #1523

Are you sure you want to change the base?

🤖 feat: add custom executable slash commands (.mux/commands/) #1523

Uh oh!

Conversation

ammar-agent commented Jan 9, 2026

Summary

Features

Example

Implementation

Testing

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

ammar-agent commented Jan 9, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

ammar-agent commented Jan 9, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

ammar-agent commented Jan 9, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant