test-shell-command.md

Shell Command Implementation Test

CRITICAL DISCOVERY & FIX

The !cmd shell syntax was ALREADY IMPLEMENTED in kuuzuki but had a critical missing piece!

What Was Already Working ✅

1. Input Detection - !cmd syntax detected in editor.go:558
2. Shell Execution - ExecuteShellCommand message sent to app
3. Server Endpoint - /session/:id/shell endpoint exists
4. Real-time Streaming - Server streams output via updatePart()
5. TUI Streaming - EventListResponseEventMessagePartUpdated handled

What Was Missing ❌

Shell Output Display - No case "shell" in tool rendering logic!

Critical Fix Applied ✅

Added missing case "shell" in /packages/tui/internal/components/chat/message.go to properly render shell command output with:

• Real-time streaming output display
• Status indicators (Running/Completed/Error)
• Exit code display
• ANSI-stripped clean output
• Cursor indicator for active streaming

Code Examples

Shell Command Detection

// Check for !shell command
if strings.HasPrefix(value, "!") && len(value) > 1 {
    command := strings.TrimSpace(value[1:]) // Remove the ! prefix
    if command != "" {
        // Execute shell command
        cmds = append(cmds, util.CmdHandler(app.ExecuteShellCommand{
            SessionID: m.app.Session.ID,
            Command:   command,
        }))
        return m, tea.Batch(cmds...)
    }
}

Shell Execution Integration

case app.ExecuteShellCommand:
    a.showCompletionDialog = false
    // Execute shell command asynchronously
    cmds = append(cmds, func() tea.Msg {
        _, err := a.app.ExecuteShellCommand(context.Background(), msg.SessionID, msg.Command)
        if err != nil {
            return toast.NewErrorToast(fmt.Sprintf("Shell command failed: %v", err))
        }
        return nil
    })

Go SDK Shell Method

// Run a shell command
func (r *SessionService) Shell(ctx context.Context, id string, body SessionShellParams, opts ...option.RequestOption) (res *AssistantMessage, err error) {
    opts = append(r.Options[:], opts...)
    if id == "" {
        err = errors.New("missing required id parameter")
        return
    }
    path := fmt.Sprintf("session/%s/shell", id)
    err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
    return
}

Features Implemented

✅ Input Detection: Detects commands starting with ! in TUI editor ✅ Command Parsing: Strips ! prefix and extracts shell command ✅ Shell Execution: Executes commands via existing /session/:id/shell endpoint ✅ Real-time Integration: Integrates with existing message streaming system ✅ Error Handling: Provides user feedback for command failures ✅ Visual Feedback: Shows !cmd shell hint in editor status bar ✅ Async Execution: Commands execute asynchronously without blocking UI

Integration Points

1. Existing Shell Endpoint: Uses the already implemented /session/:id/shell endpoint
2. Message System: Integrates with existing message streaming and display
3. Error Handling: Uses existing toast notification system
4. UI Patterns: Follows existing TUI patterns and styling
5. SDK Consistency: Go SDK methods follow existing patterns

Testing

To test the implementation:

1. Start the TUI: kuuzuki tui
2. Type a shell command with ! prefix: !ls -la
3. Press Enter to execute
4. The command will be sent to the shell endpoint and output displayed in real-time
5. Error messages will appear as toast notifications if commands fail

Error Handling

• Invalid commands show error toasts
• Empty commands after ! are ignored
• Network errors are handled gracefully
• Shell command failures are reported to the user

Security Considerations

• Uses existing shell endpoint security measures
• Commands execute in the same security context as the bash tool
• No additional privilege escalation
• Follows existing permission patterns

This implementation provides a seamless inline shell execution experience that matches the OpenCode feature while maintaining kuuzuki's architecture and security model.