About Sessions
A session is Maestro’s fundamental unit of work. It is an independent, persistent workspace that contains everything needed to accomplish your goals: dialog history, files, tools, and an execution environment.
Sessions are designed around a simple insight: real engineering work is not a single prompt-response cycle. It unfolds over hours, sometimes days, with research, implementation, validation, and iteration. Sessions provide the continuity that makes sustained work possible.
What a Session Contains
Memories are the dialog history — records of what you asked, what Maestro did, what tools returned, and what was validated. Memories can be selectively forgotten or compressed to manage capacity.
Files are your project’s source code and data. Every change creates a new iteration, so nothing is ever lost. You can view any historical version, compare iterations, or restore earlier states.
Tools are the capabilities Maestro uses to work: viewing and editing files, running code, searching the web, creating diagrams, managing source control. You set goals; Maestro selects and uses appropriate tools.
The Sandbox is an isolated Linux environment where code actually runs. Tests execute here. Benchmarks measure performance here. Web servers start and accept requests here. This is where claims become evidence.
Why Sessions Have Capacity Limits
Every session has a token-based capacity limit. This is not an arbitrary restriction — it serves a purpose.
When context grows too large, quality degrades. The model has to process more information per turn, which increases both cost and the likelihood of losing track of important details. A session stuffed with hundreds of file iterations and old debugging conversations becomes harder to work with, not easier.
Capacity management is part of the discipline of working with Maestro. The tools for managing it — /forget, /compact, /refresh, /hidefiles — are not workarounds for a limitation. They are instruments for maintaining a clean, focused workspace.
Session Lifecycle
Sessions can be paused and resumed across hours, days, or weeks. They checkpoint automatically, preserving complete state. You can start on a desktop, check progress on your phone, and resume on a laptop.
The sandbox environment is ephemeral by design. After extended inactivity, the sandbox terminates, but your files and session state are preserved. When you resume, a fresh sandbox starts and your files restore automatically. Packages you previously installed will need reinstalling — this is intentional isolation, not a bug.
About the Partnership Model
Success with Maestro requires understanding what each partner brings to the work.
Your Role: Strategic Direction and Quality Control
You define what needs to be built and to what standard. You make architectural decisions, set constraints, and establish success criteria. When Maestro proposes an approach, you evaluate it against your understanding of the problem. When Maestro claims completion, you demand evidence.
This role is not passive supervision. The most effective Maestro users are actively engaged: challenging assumptions, catching errors early, pushing back on shortcuts, and steering toward better solutions. Your domain knowledge, taste, and judgment are irreplaceable.
Maestro’s Role: Technical Execution
Maestro handles implementation: writing code, running tests, researching solutions, debugging failures, optimizing performance. It can sustain focus across thousands of lines of code, maintain consistency across files, and systematically validate its own work.
Maestro is powerful but not infallible. It can misunderstand requirements, choose suboptimal approaches, or make logical errors. It is, in the language of the prompting guide, “an over-confident, incredibly fast, and very literal developer.” Treat its output with healthy skepticism until validated.
Why This Division Works
This division reflects what humans and AI systems each do well. Humans excel at defining goals, evaluating quality, making strategic trade-offs, and bringing domain expertise. AI systems excel at sustained implementation, systematic validation, and tireless execution of well-defined work.
The partnership produces better results than either alone. Users who engage actively — challenging, correcting, demanding evidence — get dramatically better outcomes than those who passively accept output.
About Working at Different Scales
Maestro is optimized for substantial work, not trivial changes.
Small tasks (changing a button color, fixing a typo) are often faster in an IDE. Maestro’s overhead — planning, validation, sandbox execution — does not pay off for work that takes seconds by hand.
Medium tasks (implementing a feature, fixing a bug, adding test coverage) are Maestro’s sweet spot. The investment in planning and validation produces complete, tested implementations that would otherwise take hours.
Large tasks (building subsystems, migrating architectures, implementing from research papers) represent Maestro at its most powerful. Projects requiring coordination across thousands of lines, sustained context, and systematic validation benefit enormously from the session model.
Very large tasks often work better as multiple focused sessions rather than a single massive one. Parallel sessions for independent components, followed by an integration session, provides better capacity management and clearer focus.
About Context and Tokens
Understanding tokens helps you work effectively with Maestro.
A token is roughly three-quarters of a word. Everything in a session — your messages, Maestro’s responses, file contents, tool schemas — is measured in tokens. Session capacity is the total number of tokens the model can process per turn.
Token consumption comes from several sources: dialog history (memories), files currently in view, tool schemas, sandbox state, and system instructions. Of these, files and dialog history are the largest and most controllable.
This is why capacity management matters. When you run /refresh, you reduce file tokens by hiding old iterations. When you run /compact, you reduce memory tokens by summarizing old dialog. These are not cleanup tasks — they directly improve the quality and cost of every subsequent turn.
About Validation and Evidence
A defining principle of working with Maestro is evidence over assertion.
When Maestro says “the implementation is performant,” that is a claim. When Maestro shows you benchmark results comparing old and new implementations under identical conditions, that is evidence. The first is worth nothing; the second is worth everything.
This applies at every level. “Tests pass” means nothing without test output. “Performance improved” means nothing without before/after benchmarks. “The code handles edge cases” means nothing without tests that exercise those cases.
The sandbox exists precisely to make evidence possible. Code runs in a real environment. Tests produce real output. Benchmarks measure real performance. This is what separates Maestro from tools that generate code you then have to validate yourself.
About How Maestro Works Internally
Maestro is not a single model answering questions. It is an orchestration system that coordinates multiple specialized models, execution environments, and validation tools.
Multiple models handle different aspects of work. Research models gather information. Planning models design approaches. Implementation models write code. Verification models review quality. The orchestration layer routes tasks to appropriate models based on complexity.
The sandbox provides real execution. Code compiles and runs. Tests execute and produce results. Servers start and accept requests. This grounds Maestro’s work in reality rather than speculation.
Quality oversight systems flag issues before they become problems. Proposals are reviewed before application. Tests are run automatically. Performance claims are validated against benchmarks.
Tools are the mechanisms through which Maestro interacts with the world: file management, terminal access, web research, visualization, source control. You do not invoke tools directly — you set goals, and Maestro selects appropriate tools.
This architecture means Maestro can handle work that no single model could manage: sustained implementation across many files, systematic validation, research synthesis, and iterative refinement based on real execution results.
Further Reading
