Introduction
In OSS development, "usability" and "maintainability" are often conflicting requirements. This article provides a detailed explanation of the UX design philosophy and implementation learned through Prompt Scheduler development for AI tools.
Disclaimer
The Prompt Scheduler introduced in this article is an open-source tool that I personally developed. I want to clearly state that this is an independent personal development project with no connection whatsoever to Anthropic's Claude or Claude Code.
Three Core Principles of UX Design
1. Minimizing Cognitive Load
Challenge: AI tools deal with complex concepts, leading to high cognitive load for users
Solution Approach:
# No need to remember complex configurations
npm run run # Simple and intuitive
npm run next # Clear meaning
npm run status # Easy status checking
Design Decisions:
- Command names unified with verbs (run, next, reset)
- Prioritize npm scripts over arguments
- Help available instantly with
npm run help
2. Progressive Complexity
Basic Level: npm scripts
npm run run # Most simple
npm run status # Status check
Intermediate Level: Basic options
tsx src/claude-schedule.ts run --stop-at 5pm
tsx src/claude-schedule.ts run --hours 3
Advanced Level: Full option combinations
tsx src/claude-schedule.ts run \
--prompt-file ~/custom/prompts.jsonl \
--mode sequential \
--ignore-approaching-limit \
--hours 6
3. Fault Tolerance
Humane Error Messages:
if (!existsSync(promptFile)) {
console.log(colors.error(`❌ Error: ${promptFile} not found`));
process.exit(1);
}
Providing Recovery Options:
npm run reset # Can always return to initial state
npm run status # Can understand current situation
One-liner Installation Implementation Philosophy
Technical Challenges
Traditional Problems:
# Too complex procedure
git clone https://github.com/prompt-scheduler/cli.git
cd cli
npm install
cp prompts/prompts.jsonl.sample prompts/prompts.jsonl
# Too many setup steps...
Solution:
# Complete with one-liner
curl -fsSL https://raw.githubusercontent.com/prompt-scheduler/cli/main/install.sh | bash
install.sh Design Philosophy
#!/bin/bash
# Error handling
set -e
# Clear progress display
echo "🚀 Installing Prompt Scheduler..."
# Dependency checking
check_requirements() {
# Check existence of Node.js, git, tmux
# Version requirement verification
}
# Existing installation detection and update
handle_existing_installation() {
if [ -d "$INSTALL_DIR" ]; then
echo "📦 Existing installation found, upgrading..."
# Preserve existing configurations
fi
}
UX Design Points:
- Progress Visualization: Emojis and clear messages
- Friendly Error Explanations: What's wrong and how to solve it
- Respect Existing Environment: Preserve configuration files
Command Line Design Aesthetics
Consistent Interface
# All unified with same pattern
tsx src/claude-schedule.ts [command] [options]
# Command section
run # Execute
next # Execute next
status # Status check
reset # Reset
help # Help
# Option section
--stop-at TIME
--hours NUMBER
--prompt-file PATH
--mode MODE
--ignore-approaching-limit
Intuitive Option Naming
# ❌ Hard to remember
--stop-time
--duration
--file
--execution-mode
# ✅ Intuitive
--stop-at 5pm
--hours 3
--prompt-file ~/my-prompts.jsonl
--mode sequential
Human Factors in Error Handling
Progressive Error Information
// Level 1: Problem summary
console.log(colors.error(`❌ Error: Invalid prompt index ${index}`));
// Level 2: Specific solutions
console.log(colors.info(`Available indices: 1-${prompts.length}`));
// Level 3: Reference information
console.log(colors.muted('Use "npm run status" to see all prompts'));
Preventive UX Design
// Validate parts users commonly make mistakes with
function validatePromptFile(file: string): void {
if (!existsSync(file)) {
console.log(colors.error(`❌ Prompt file not found: ${file}`));
console.log(colors.info('💡 Try creating it from the sample:'));
console.log(colors.accent(' cp prompts/prompts.jsonl.sample prompts/prompts.jsonl'));
process.exit(1);
}
}
Feedback System Design
Real-time Progress Display
// Visual feedback during execution
console.log(colors.primary(`🎯 Executing prompt ${i + 1}:`), colors.accent(prompt.prompt));
console.log(colors.success(`✅ Prompt ${i + 1} completed`));
console.log(colors.info(`⏳ Waiting ${prompt.default_wait}...`));
Situation Awareness Support
📊 PROMPT STATUS
📄 Using prompt file: prompts/prompts.jsonl
1. ✅ SENT Create responsive login form (2024-01-15 14:30:25)
2. ✅ SENT Add error handling (2024-01-15 14:45:10)
3. ⏳ PENDING Style with modern CSS (N/A)
4. ⏳ PENDING Add password strength indicator (N/A)
Color Palette and Typography
Information Hierarchy Visualization
const colors = {
primary: chalk.cyan, // Main actions
success: chalk.green, // Success state
warning: chalk.yellow, // Warnings
error: chalk.red, // Errors
info: chalk.blue, // Information
muted: chalk.gray, // Auxiliary information
accent: chalk.magenta, // Emphasis
highlight: chalk.bgCyan.black // Highlights
};
Information Density Optimization
# ❌ Information overload
[2024-01-15T14:30:25.123Z] INFO: Executing prompt number 1 of 8 total prompts: "Create a responsive login form with validation" (session: /tmp/tmux-1000/default, wait: 15m, mode: repeat)
# ✅ Appropriate information amount
🎯 Executing prompt 1: Create responsive login form
Configuration Management UX
Zero Configuration Principle
# Works immediately without configuration
npm run run
# Customize only when needed
tsx src/claude-schedule.ts run --prompt-file ~/my-prompts.jsonl
Progressive Configuration Complexity
{"prompt": "Simple task", "tmux_session": "/path/to/session", "sent": "false", "sent_timestamp": null, "default_wait": "5m"}
Minimal items only:
-
prompt: What to do -
tmux_session: Where to execute - Others are automatically managed
Minimizing Learning Cost Strategy
Discoverability
# Help always easily accessible
npm run help
tsx src/claude-schedule.ts help
# Status checking suggests next actions
npm run status
# → "Use 'npm run run' to execute pending prompts"
Mental Model Alignment
# Matches user expectations
npm run run # "Execute" → Execute everything
npm run next # "Next" → Execute just one
npm run status # "Status" → Current state
npm run reset # "Reset" → Return to initial state
Summary: Future of AI Tool UX
Important Design Principles:
- Minimize Cognitive Load - Reduce what needs to be remembered
- Progressive Complexity - Provide advanced features as needed
- Fault Tolerance - Easy recovery from errors
- Intuitive Interface - Match user expectations
- Immediate Feedback - Make clear what's happening
In AI tool development, hiding technical complexity from users and providing intuitive, easy-to-use interfaces determines tool success.
Toward Next-Generation AI Tools:
- More natural language command operations
- Context-aware automatic configuration
- Predictive error prevention