Commands

​

What Are Commands?

• Commands: You invoke them (via /command syntax)
• Tools: Maestro invokes them autonomously

​

Quick Reference

​

Planning Mode

​

/plan - Plan Mode

• Exploring different architectural approaches
• Understanding requirements before implementation
• Getting detailed plans without code changes
• Early-stage design discussions
• Clarifying ambiguous requirements

• Maestro asks questions to understand requirements
• Discusses strategies and provides examples
• No file proposals or code changes
• Can use read-only tools (View Files, Search, etc.)
• Detailed planning and reasoning

/plan

"How should we implement real-time notifications in our app?"

Maestro will:
- Ask clarifying questions about your requirements
- Discuss WebSockets vs Server-Sent Events vs polling
- Explore architectural trade-offs
- Provide detailed implementation plan
- NOT make any code changes

​

Session Management Commands

​

/forget - Selective Memory Removal

• Session capacity getting tight
• Old context no longer relevant
• Want to focus on current work

• Presents interactive UI showing memory breakdown
• Select specific turns or ranges to remove
• Preserves important context automatically
• Updates capacity immediately

/forget

[Interactive table shows memory usage by turn]
Select turns 5-15 to remove → Confirm → Capacity freed

• Keep strategic decisions and specifications
• Remove debugging sessions and false starts
• Preserve validation results and benchmarks

​

/compact - Memory Compression

• Long-running sessions with important history
• Want to preserve context but reduce token usage
• Before capacity limits force hard choices

• Analyzes memory segments
• Creates compressed summaries
• Preserves key decisions and learnings
• Replaces detailed history with high-level overview

• Important decisions and rationale
• Architectural choices
• Validation results
• Lessons learned

• Step-by-step implementation details
• Debugging iterations
• Exploratory dead ends

After 50 turns implementing a feature:
/compact

Preserves: "Chose Redis over Memcached because our workload needs persistence"
Compresses: Detailed back-and-forth during implementation

​

/synopsis - Session Overview

• End of major implementation
• Before pausing long session
• To document what was accomplished
• For knowledge transfer

• What was accomplished
• Key decisions made
• Technical approaches taken
• Lessons learned
• Current state and next steps

• Resuming work later
• Sharing with team members
• Documentation for posterity
• Understanding complex sessions

​

/settings - Session Settings

• Adjusting model selection
• Configuring sandbox persistence
• Managing session behavior

​

/skills - Skill Management

• Discovering available skills
• Enabling or disabling specific skills
• Learning about skill capabilities

​

File Management Commands

​

/hidefiles - Reduce File Context

• Too many file iterations consuming capacity
• Want to focus on specific versions
• Hiding experimental or WIP iterations

• Interactive table showing all file iterations
• Select iterations to hide
• Hidden files don’t count toward capacity
• Can be unhidden later if needed

File auth.py has 15 iterations from experimentation
Hide iterations 0-13, keep only 14 and 15
Capacity usage drops immediately

​

/refresh - Latest Iterations Only

• After extensive iteration on files
• Want clean, current view of codebase
• Before creating PR or checkpoint

• Hides all old iterations
• Shows only most recent version
• Dramatically reduces capacity usage
• Preserves iteration history (can still restore)

​

Download Commands

​

/download-all - Complete Export

• Backing up complete session
• Sharing entire project
• Migrating to local development

• All source code files
• Configuration files
• Documentation
• Test files
• Respects .gitignore patterns

• Build artifacts
• Dependencies (node_modules, venv, etc.)
• Temporary files
• Binary artifacts

​

/download-new - New and Modified Files

• Working with existing large project
• Only need to extract your changes
• Integrating changes into local repository

• Zip archive of new and changed files
• Preserves directory structure
• Extraction instructions provided

1. Clone existing large project
2. Implement new feature
3. /download-new
4. Extract zip at project root on local machine
5. Files slot into correct locations

​

/download-recent - Latest Activity

• Quick access to current work
• Sharing latest changes
• Spot-checking recent modifications

​

Source Control Commands

​

/clone - Clone Repository

• Clone private repositories (with GitHub authentication)
• Clone specific branches or commits
• Clone pull request URLs directly
• Multiple clones of same repo (for comparisons)

1. Choose private vs public repository
2. Select from your repositories or enter custom URL
3. Choose organization/account
4. Select branch or enter commit hash
5. Clone completes with summary

• Files immediately available in session
• Synced to sandbox automatically
• Clone records persist across memory clearing
• Maximum repository size: ~10GB

Clone same repository again to pull remote changes.

Maestro will:
- Detect changed files
- Create new iterations
- Inform you of changes
- Maintain iteration history

• Pull teammate’s recent commits
• Update to latest main branch
• Sync your PR branch with base

​

/create - Create Repository

• Repository name and description
• Public or private visibility
• GitIgnore and license templates
• Organization ownership
• Auto-clone (enabled by default)

1. Enter repository details
2. Select templates and settings
3. Choose organization or personal account
4. Confirm creation
5. Auto-clones to session (if enabled)

​

/pr - Pull Request

1. Select files to include in PR
2. Choose target repository and base branch
3. Provide PR title and description
4. Review changes (diff view)
5. Confirm and create/update

• Creates feature branch from base
• Commits selected files
• Pushes to remote
• Opens PR on GitHub

• Full synchronization with feature branch
• Deselected files revert to base branch state
• Updates PR with new changes
• Maintains PR discussion history

​

Secrets Management

​

/secrets - Secret Management

• View all registered secrets
• Activate secrets (expose as environment variables)
• Deactivate secrets (remove from environment)
• Per-session activation state

1. Table shows all secrets with active/inactive status
2. Toggle switches to activate/deactivate
3. Confirm changes
4. Secrets immediately available in sandbox terminals

• Active secrets → environment variables in sandbox
• Available to all terminal commands
• Sandboxed per session (isolation guaranteed)
• Never exposed in logs or outputs

Register AWS secrets in secrets manager (bottom-left menu)
Use /secrets to activate for this session
Now AWS CLI commands in sandbox use these secrets
Deactivate when done for security

• Register new secrets (API keys, tokens, etc.)
• OAuth linking (GitHub, GitLab, etc.)
• Edit or delete existing secrets
• View usage across sessions

​

Sandbox Management

​

/reset-sandbox - Force Reset

• Sandbox becomes unresponsive
• Processes hung and can’t be stopped
• Want clean environment
• Troubleshooting sandbox issues

• Confirmation prompt (prevent accidental reset)
• Sandbox completely terminated
• Fresh sandbox created on next command
• Files preserved (they’re in session, not just sandbox)

​

Utility Commands

​

/tools - Tool Management

• View all available tools by category
• Enable/disable specific tools
• See tool descriptions
• Control tool availability per session

• Want to see what tools Maestro has access to
• Need to disable expensive tools
• Want to focus Maestro on specific capabilities

​

Command Combinations and Workflows

​

Research → Implementation → Delivery

# Phase 1: Plan
/plan
"Discuss approach for implementing feature X"
[Maestro asks questions and proposes approach]

# Phase 2: Research
Clone repository and analyze current implementation
/clone github.com/org/repo

# Phase 3: Develop
[Work with Maestro to implement feature]

# Phase 4: Validate
[Comprehensive testing and benchmarking]

# Phase 5: Package
/download-new  # Get your changes
or
/pr  # Create pull request directly

​

Multi-Repository Workflows

# Clone main application
/clone github.com/org/main-app branch develop

# Clone shared library for reference
/clone github.com/org/shared-lib branch main

# Implement feature that uses shared library

# Create PR in main-app only
/pr  # Select main-app repository

​

Context Optimization Workflow

# After 30 turns of implementation
/refresh  # Show only latest file versions
/compact  # Compress old dialog
/hidefiles  # Selectively hide experimental iterations

# Result: Clean context for final validation

​

Best Practices

​

Command Timing

• /forget before capacity limits force it
• /secrets at session start if you’ll need them
• /download-new periodically for backup

• Manage memory before it becomes critical
• Organize files before context gets unwieldy

​

Combining Commands

# Clean slate for validation
/refresh + /compact → minimal context, latest state

# Pre-PR preparation
/refresh + run all tests → ensure clean state

# Session backup
/synopsis + /download-all → document + archive

​

When NOT to Use Commands

• Viewing specific files → Maestro’s View Files tool
• Running tests → Maestro’s Execute Command tool
• Creating diagrams → Maestro’s design tools

• Session-level operations
• Bulk utilities
• Interactive confirmations
• Resource management
• Behavior modification (steers)

​

Troubleshooting Common Issues

​

”Session capacity is full”

1. /refresh - Reset to latest file iterations
2. /compact - Compress old dialog
3. /forget - Remove unnecessary turns
4. /hidefiles - Hide specific iterations

​

”Can’t find my downloaded files”

• Downloads appear in browser’s download folder
• Zip files have timestamp in name
• Extract at project root for correct structure

​

”Secret not working in sandbox”

1. Secret registered in Secrets Manager
2. Used /secrets to activate for this session
3. Activated secrets show in terminal: echo $SECRET_NAME

​

”Clone failed for large repository”

• Clone smaller repositories
• Use shallow clones (—depth 1) if supported
• Request support for larger repositories

​

Advanced Usage

​

Planning then Implementation

Turn 1:
/plan
"How should we architect the caching layer?"
[Maestro asks questions and provides detailed analysis without implementing]

Turn 2:
"Implement the Redis caching approach we discussed"
[Maestro implements based on approved plan]

​

Command Shortcuts via Natural Language

"Clone github.com/org/repo branch develop"

Maestro recognizes intent and triggers clone command

​

Getting Help

​

Within Maestro

"What commands are available?"
"How do I manage secrets?"
"Explain the /compact command"

​

Reference Documentation

​

Next Steps

• Tools Overview: Understand Maestro’s autonomous capabilities
• Sandbox Guide: Deep dive into execution environment
• Source Control: Advanced GitHub workflows
• Session Strategies: Patterns for different project types