Understanding the fundamentals of working with Maestro.Documentation Index
Fetch the complete documentation index at: https://docs.igent.ai/llms.txt
Use this file to discover all available pages before exploring further.
Sessions: Your Persistent Workspace
A session is Maestro’s fundamental unit of work—an independent, checkpointable, resumable artifact that contains everything needed to accomplish your goals.What’s in a Session?
Memories
Dialog history containing records of previous turns. Includes:- User requests and feedback
- Maestro’s responses and reasoning
- Tool execution results
- Validation outcomes
Files
Complete support for source code and data in enterprise-scale projects:- Full iteration history: Every change creates a new iteration; nothing is lost
- Pattern-based operations: Work with entire file sets using glob patterns
- Smart synchronization: Files sync between your session and sandbox automatically
- Rich metadata: Understand when files changed, who changed them, why
Tools
Comprehensive capabilities to:- Manage and interact with files
- Execute code in isolated sandboxes
- Gather information from the web
- Create visualizations and diagrams
- Integrate with external services
- Package and download deliverables
Sandbox
Isolated Ubuntu Linux environment where:- Code compiles and runs
- Tests execute
- Benchmarks measure performance
- Web servers start and accept requests
- Real validation happens
Session Lifecycle
Creating Sessions
- Fresh sessions start with empty memories and no files
- Cloned sessions can start from templates or existing projects
- Resumed sessions restore complete state from checkpoints
Automatic Checkpointing
Maestro automatically saves session state:- At regular time intervals (default: every 5 minutes)
- When storage reaches size thresholds (default: 10GB)
- When disk pressure is high (default: 85% capacity)
- When explicitly requested
Resuming Sessions
Sessions can be resumed:- After hours, days, or weeks
- Across different devices
- With full context restoration
- Including sandbox state where applicable
Session Capacity
Every session has a capacity limit based on token consumption: Token Sources:- Dialog history (memories)
- Files currently in view
- Tool schemas and documentation
- Sandbox state and environment
- System instructions
- Watch the capacity indicator in the top right
- Click for detailed breakdown
- Use commands to reduce consumption when needed
- Prevents context poisoning (too much irrelevant information)
- Maintains response quality
- Controls costs
- Keeps sessions focused
/forget: Remove old dialog selectively/compact: Summarize memories to free space/hidefiles: Reduce file context/refresh: View only latest file iterations
The Maestro Partnership Model
Success with Maestro requires understanding your complementary roles:User’s Role: Quality Controller & Strategic Guide
Set Direction- Define clear objectives and success criteria
- Establish quality standards and constraints
- Make architectural decisions
- Choose when to intervene vs delegate
- Challenge logical inconsistencies
- Demand evidence for claims
- Push back when standards aren’t met
- Never accept shortcuts on quality
- Review test results skeptically
- Verify benchmarks are meaningful
- Check edge case handling
- Ensure documentation is accurate
Maestro’s Role: Technical Implementation Partner
Execute Deeply- Handle thousands of lines of implementation
- Navigate complex codebases
- Integrate across multiple systems
- Maintain consistency and quality
- Test comprehensively
- Benchmark rigorously
- Document thoroughly
- Prove correctness
- Incorporate feedback immediately
- Course-correct when challenged
- Maintain context across long sessions
- Improve through iteration
The Dynamic That Works
Best Sessions Feature:- Active user oversight with immediate feedback
- Users who catch errors early prevent larger mistakes
- Professional criticism improves output quality
- Insistence on evidence leads to better solutions
- Partnership creates better results than either alone
- Accepting claims without evidence
- Skipping validation “to save time”
- Not reviewing test results
- Allowing shortcuts on quality standards
Working at Different Scales
Maestro is optimized for substantial tasks, not tiny changes:Small Tasks (Seconds to Minutes)
- Button color changes
- Simple config updates
- Trivial bug fixes
Medium Tasks (Minutes to Hours)
- Implementing single features
- Fixing specific bugs
- Adding test coverage
- Performance optimization
Large Tasks (Hours to Days)
- Building entire subsystems
- Migrating architectures
- Implementing complex algorithms
- Full-stack feature development
Very Large Tasks (Days to Weeks)
- Complete system implementations
- Major architectural refactors
- Building from research papers
- Multi-system integrations
Complex Feature Implementation Phases
For substantial features, follow this proven pattern:1. Discovery & Understanding
Goal: Deep comprehension of existing system Pattern: “Clone X and walk me through how subsystem Y works” Success Criteria: Maestro demonstrates understanding of architecture, constraints, and integration points Time Investment: Essential upfront work prevents later architectural mistakes2. Strategic Analysis
Goal: Identify highest-value implementation approach Pattern: “What are the 3 most valuable ways to extend this with Z?” Success Criteria: Clear rationale for chosen approach, understanding of alternatives Risk Mitigation: Prevents over-engineering or choosing wrong approach3. Specification-Driven Development
Goal: Complete technical specification before implementation Pattern: “Create a full spec for X, then implement it” Success Criteria: Comprehensive spec covering edge cases, performance targets, testing requirements Quality Gate: Implementation should follow spec, not evolve organically4. Implementation with Continuous Validation
Goal: Working implementation with proper integration Success Criteria: Code compiles, basic functionality works, no obvious regressions Early Warning: Watch for compilation issues, integration problems5. Professional Validation
Goal: Systematic testing and performance validation Pattern: “Validate your work systematically” Success Criteria: All tests pass, performance meets targets, no regressions User Vigilance Required: This is where oversight is most critical6. Comprehensive Integration
Goal: Complete test coverage, documentation updates, clean codebase Pattern: “Run ALL tests, update docs, clean up WIP code” Success Criteria: Production-ready code with full documentationSession Types for Different Use Cases
Exploratory Sessions
Purpose: Understand existing systems, evaluate approaches Characteristics:- Clone repositories and examine architectures
- Research alternatives and trade-offs
- Prototype different solutions
- No permanent changes
/clone, file viewing tools
Implementation Sessions
Purpose: Build and deliver working features Characteristics:- Clear specifications and success criteria
- Systematic implementation with validation
- Comprehensive testing
- Production-ready output
/pr for delivery
Analysis Sessions
Purpose: Deep investigation and problem-solving Characteristics:- Root cause analysis
- Performance profiling
- Competitive evaluation
- Research synthesis
Maintenance Sessions
Purpose: Updates, fixes, and improvements Characteristics:- Targeted changes to existing code
- Regression prevention
- Documentation updates
- Cleanup and refactoring
What Makes Sessions Successful
Clear Success Criteria
Best Practice: Define measurable outcomes upfront Examples:- “Performance should exceed baseline by 20%”
- “All existing tests must continue passing”
- “Implementation must be fully Redis-compatible”
- “Code coverage must be >90%“
Demand Evidence, Not Claims
Pattern: Always ask for validation Don’t Accept: “The implementation is performing well” Demand: “Show me benchmarks against the baseline using the same methodology” Don’t Accept: “All tests pass” Demand: “Show me the test output with coverage report”Never Accept Shortcuts
Quality Standards:- Zero test failures tolerated
- Every performance claim must be validated
- All edge cases must be tested
- Regressions are unacceptable
- Documentation must be accurate and complete
Use Existing Infrastructure
Principle: Don’t reinvent testing/benchmark tools Guidance:- “Use the existing test suite structure”
- “Run the benchmark scripts already in the codebase”
- “Follow the established patterns”
- “Integrate with CI/CD pipeline”
Communication Best Practices
Be Clear and Specific
Vague: “Make it faster” Specific: “Optimize the image processing pipeline. Current performance is 2 seconds per image. Target is <500ms. Profile first, then implement optimizations with before/after benchmarks.”Provide Context
Insufficient: “Add authentication” Sufficient: “Add JWT-based authentication to our Express API. We already use bcrypt for password hashing. Follow the pattern in our user-service repository. Must integrate with existing middleware chain.”Set Constraints Explicitly
Missing Constraints: “Implement caching” Clear Constraints: “Implement Redis caching. Must: use existing Redis connection pool, maintain sub-10ms cache hit latency, handle cache failures gracefully, provide cache metrics for monitoring.”Define Done Criteria
Incomplete: “Build a dashboard” Complete: “Build a dashboard showing system metrics. Requirements: React frontend, real-time WebSocket updates, responsive design, unit tests for components, integration tests for WebSocket connection. Done when: all tests pass, loads in <2s, handles 100 concurrent users.”Adaptive Working Styles
Maestro adjusts to your preferences:High-Oversight Style
- Frequent check-ins during implementation
- Incremental validation at each step
- Detailed explanations of decisions
- More opportunities to course-correct
Autonomous Style
- Establish comprehensive specifications upfront
- Let Maestro execute fully before validation
- Review complete implementation with all tests
- Efficient for experienced users
Hybrid Style
- Detailed planning phase with feedback
- Autonomous implementation
- Thorough validation and iteration
- Most common for complex features
Common Misconceptions
”Maestro is just fancy autocomplete”
Reality: Maestro plans, implements, validates, and iterates. It handles complete features, not suggestions.”I need to know exactly what I want before starting”
Reality: Maestro can help you explore options, understand trade-offs, and refine requirements.”Maestro will do everything perfectly on first try”
Reality: Iteration is normal. Challenge, provide feedback, and refine. The partnership creates better results.”More detail in my request is always better”
Reality: Clear goals and constraints matter. Implementation details can often be left to Maestro.”I should accept what Maestro produces to save time”
Reality: Validation and pushing back on quality improves outcomes. Never compromise standards for speed.Next Steps
Now that you understand sessions and the partnership model:- Working with Maestro: Advanced collaboration patterns
- Commands Reference: Master session control
- Tools Overview: Understand Maestro’s capabilities
- Sandbox Guide: Deep dive into execution environment