Skip to main content
Get productive with Maestro in your first session.

​
Your First Session

​
1. Start with a Clear Goal

Maestro works best when you define clear objectives. Instead of: Bad: “Help me with my code” Try: Good: “Implement a Redis-based rate limiter that supports token bucket algorithm, handles distributed scenarios, and includes comprehensive tests with performance benchmarks”

​
2. Understand Session Structure

Every Maestro interaction happens within a session—an independent, resumable workspace containing:
  • Memories: Dialog history and learnings
  • Files: Your project’s complete file tree with full iteration history
  • Tools: Maestro’s capabilities for this session
  • Sandbox: Isolated execution environment
Sessions are checkpointed automatically and can be resumed across days or weeks.

​
3. Set Success Criteria

Help Maestro understand what “done” looks like:

​
4. Let Maestro Plan

Maestro will often create an implementation plan. Review it:
  • Does it understand the requirements correctly?
  • Are there architectural concerns to address?
  • Any constraints or edge cases to highlight?
This planning phase prevents costly mistakes later.

​
5. Watch Maestro Work

As Maestro executes, you’ll see:
  • Terminal streams: Real-time sandbox output
  • File changes: Code proposals and applications
  • Test results: Validation and benchmarks
  • Status updates: Current activity and progress

​
6. Validate and Push Back

When Maestro claims completion: Don’t accept: “The implementation is performing well” Demand: “Show me the benchmark results comparing this to the baseline using the same methodology” Core principle: Evidence, not confidence.

​
Example Session: Adding a Feature

Let’s walk through adding a caching layer to an existing API:

​
Initial Request

​
Maestro’s Response Pattern

  1. Understanding Phase
    • Clones repository
    • Reviews existing architecture
    • Identifies integration points
    • Asks clarifying questions if needed
  2. Planning Phase
    • Proposes caching strategy
    • Identifies files to modify
    • Outlines test approach
    • Estimates scope
  3. Implementation Phase
    • Creates cache middleware
    • Integrates with existing routes
    • Updates tests
    • Adds configuration
  4. Validation Phase
    • Runs existing test suite
    • Adds cache-specific tests
    • Benchmarks performance improvement
    • Verifies cache invalidation

​
Your Role During This

  • Review the plan: Challenge if anything seems off
  • Monitor progress: Watch terminal streams and file changes
  • Validate thoroughly: When Maestro says “done”, verify:
    • Do all tests actually pass?
    • Are the benchmarks real?
    • Does the code handle edge cases?
  • Push back: If validation is insufficient, demand more

​
Common First-Session Patterns

​
Pattern 1: Understanding Existing Code

​
Pattern 2: Implementing a New Feature

​
Pattern 3: Performance Optimization

​
Best Practices for Success

​
Clear Success Criteria

Define measurable outcomes:
  • “Performance should exceed baseline by 20%”
  • “All existing tests must continue passing”
  • “Implementation must handle 10,000 concurrent users”

​
Demand Evidence, Not Claims

Always ask for validation:
  • Bad: “The implementation is working”
  • Good: “Show me the test output proving it works”

​
Never Accept Shortcuts

Maintain quality standards:
  • Zero test failures tolerated
  • Every performance claim must be validated
  • All edge cases must be tested
  • Regressions are unacceptable

​
Use Existing Infrastructure

Don’t reinvent testing tools:
  • “Use the existing test suite structure”
  • “Run the benchmark scripts already in the codebase”
  • “Follow the established patterns”

​
Understanding Capacity

Sessions consume tokens based on:
  • Dialog history (memories)
  • Files you’re viewing
  • Tools available
  • Sandbox state
Watch the capacity indicator in the top right. If capacity gets tight:
  • Use /forget to remove old dialog
  • Use /hidefiles to reduce file context
  • Use /refresh to view only latest file versions
The system will warn you and suggest actions when needed.

​
What to Expect

​
First Session (Typically)

  • Learning Maestro’s capabilities
  • Understanding the partnership model
  • Getting comfortable with goal-driven delegation
  • Discovering how much autonomy is appropriate

​
After a Few Sessions

  • Tackling larger, more complex projects
  • Trusting Maestro with more significant work
  • Developing efficient communication patterns
  • Understanding when to intervene vs delegate

​
Experienced Users

  • Running multiple parallel sessions for different projects
  • Delegating entire features with minimal oversight
  • Leveraging advanced commands and workflows
  • Pushing Maestro to its capability limits

​
Next Steps

Now that you understand the basics:
  1. Core Concepts: Deep dive into sessions, memories, files, and tools
  2. Working with Maestro: Learn effective collaboration patterns
  3. Commands Reference: Master session control and utilities
  4. Tools Overview: Understand Maestro’s capabilities

​
Need Help?

  • Something unclear? Ask Maestro to explain
  • Hit a problem? Describe what went wrong
  • Want to try something? Just ask
Remember: Maestro is designed to help you succeed. Be clear, be specific, and demand high standards.