> ## 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.

# Advanced features

Power user capabilities and sophisticated workflows.

## Interactive Prompts and Asks

Maestro can pause execution and request your input through sophisticated interactive prompts.

### Ask Types

#### Text Input

Simple text prompts for clarification or decisions.

**Example**:

```
Maestro: "Should I use REST or GraphQL for the API?"
You: [Type response and submit]
Maestro: [Continues with your choice]
```

#### File Upload

Request specific files during execution.

**Example**:

```
Maestro: "Please upload the API specification document"
You: [Upload OpenAPI spec]
Maestro: [Implements based on uploaded spec]
```

#### Action Buttons

Multiple choice selections via buttons.

**Example**:

```
Maestro: "Which authentication approach?"
Buttons: [JWT] [OAuth 2.0] [Session-based]
You: [Click OAuth 2.0]
Maestro: [Implements OAuth flow]
```

#### Interactive Tables

Complex selections or configurations via tables.

**Examples**:

* **Credential management**: Toggle switches for activate/deactivate
* **File selection**: Checkboxes for PR file inclusion
* **Memory management**: Select turns to forget/compact
* **Configuration**: Edit values in structured table

**Advantages**:

* Visual clarity for complex options
* Bulk operations
* Clear state visualization
* Editable cells where appropriate

### Ask Behavior

**Persistence**:

* Asks survive browser refreshes
* State preserved on reconnection
* Resume from where you left off

**Multi-device**:

* Same ask shown on all your devices
* Answer on phone, continues on laptop
* Synchronized state across clients

**Notifications**:

* Push notifications for important asks (if enabled)
* Respond directly from notification
* Without opening full application

### Best Practices with Asks

**Provide clear responses**:

* Specific, not vague
* Complete information
* Follow requested format

**Don't abuse interaction**:

```
** Inefficient:
Multiple asks for simple information
"What's the database host?" → Answer
"What's the port?" → Answer
"What's the username?" → Answer

** Efficient:
"Database credentials: host=localhost, port=5432, user=admin, db=myapp"
```

**Set context upfront** to reduce asks:

```
"Implement user service. Database: PostgreSQL at localhost:5432. Auth: JWT. Tests: pytest. Follow patterns in existing services."

Fewer clarification asks needed.
```

## Advanced Memory Management

### Memory Compaction Strategies

#### Selective Compaction

```
/compact → Interactive UI

Choose what to compress:
- Debugging sessions → Compress heavily
- Implementation details → Moderate compression
- Architectural decisions → Preserve fully
- Test results → Compress

Result: Preserve important context, free capacity
```

#### Automatic Triggers

**When capacity reaches threshold**:

* System suggests compaction
* Shows projected savings
* You confirm or decline
* Preserves quality while managing size

### Memory Inspection

**Understanding memory composition**:

```
Click capacity bar → Detailed breakdown

View:
- Tokens per turn
- Memory by type (user requests, agent replies, tool results)
- File context contribution
- Tool schema overhead

Identify: What's consuming capacity
```

### Advanced Forget Patterns

**Strategic forgetting**:

```
Keep:
- Specifications and requirements
- Architectural decisions
- Validation results
- Key lessons learned

Remove:
- Failed attempts and dead ends
- Debugging iterations
- Exploratory analysis (after conclusion)
- Redundant explanations
```

**Pattern for long sessions**:

```
After major milestone:
1. /synopsis → Document session so far
2. /forget → Remove implementation details
3. Keep: Synopsis + current state
4. Continue: With fresh capacity
```

## Multi-Client and Multi-Device

### Synchronized Experience

**Same session, multiple devices**:

* Desktop computer
* Laptop
* Tablet
* Phone (if mobile app available)

**What's synchronized**:

* Complete dialog history
* File state and changes
* Tool execution results
* Interactive prompts
* Session settings

**Use cases**:

* Review session on phone during commute
* Start on desktop, continue on laptop
* Monitor long-running session from mobile
* Collaborate: multiple people viewing same session

### Collaborative Sessions

**Multiple people, one session** (with appropriate access):

```
Team Lead:
- Defines requirements and success criteria
- Reviews Maestro's proposals
- Makes architectural decisions

Developer:
- Monitors implementation progress
- Provides domain expertise when Maestro asks
- Reviews code changes

Both see identical state, can interact simultaneously
```

**Coordination**:

* One person's ask response continues session for all
* All see same tool execution
* Shared context and history
* Real-time updates

### Session Handoff

**Transferring session ownership**:

```
Developer A (Day 1):
- Implements core feature
- Uses /synopsis to document state
- Shares session with Developer B

Developer B (Day 2):
- Resumes session
- Reviews synopsis
- Continues implementation
- Full context preserved
```

## Advanced File Management

### File Iteration Strategies

**Comparing iterations**:

```
"Show me what changed between iteration 5 and 10 of auth.py"

Maestro uses Compute Diffs:
- Generates side-by-side diff
- Highlights additions/deletions
- Explains changes in context
```

**Selective restoration**:

```
"The authentication in iteration 7 was better. Restore auth.py to iteration 7 while keeping everything else at latest."

Preserves good work while recovering from wrong turn.
```

**Iteration archaeology**:

```
"Walk me through the evolution of auth.py showing key changes at iterations 0, 5, 10, 15."

Understanding decision history
```

### Bulk File Operations

**Pattern matching power**:

```
"Hide all test files except the ones I just created"

Pattern: **/*test*.py
Exclude: New test files created this session
Result: Old test iterations hidden, new ones visible
```

**Moving entire subsystems**:

```
"Reorganize code: move all auth-related files from src/ to src/auth/"

Maestro:
- Identifies auth files
- Moves with pattern preservation
- Updates imports across codebase
- Verifies code still works
```

## Advanced Sandbox Usage

### Custom Sandbox Configurations

**High-memory workloads**:

```
Create Sandbox(
    sandbox_name="data_processing",
    cpu_count=8,
    memory_gb=32
)

Use for:
- Large dataset processing
- Memory-intensive computations
- Parallel processing
```

**GPU workloads** (when available):

```
Create Sandbox(
    sandbox_name="ml_training",
    gpu_type="A100",
    gpu_count=2
)

Use for:
- Model training
- Large-scale inference
- GPU-accelerated computing
```

**Privileged containers**:

```
Create Sandbox(
    sandbox_name="docker_dev",
    privileged=True
)

Use for:
- Docker-based workflows
- Container image building
- Docker Compose orchestration
```

### SSH Remote Execution

**Connect to external systems**:

```
Create Sandbox(
    sandbox_name="prod_analysis",
    ssh_connection="admin@prod-server.com:22",
    ssh_private_key="credential://PROD_SSH_KEY"
)

Use for:
- Analyzing production systems
- Remote debugging
- Deployment operations
- Infrastructure inspection
```

## Advanced Tool Patterns

### Tool Chaining for Complex Analysis

**Example: Security audit**:

```
Goal: Comprehensive security audit

Tool chain:
1. Search Files → Find authentication code
2. Analyze Files → Extract security patterns
3. Perplexity Search → Research known vulnerabilities
4. Complex Reasoning → Assess overall security posture
5. PROPOSE_EDIT → Implement fixes
6. Execute Command → Run security scanners
7. Generate report

Each tool feeds next step
```

### Custom Tool Workflows

**Disable unnecessary tools**:

```
/tools → Disable design tools if pure backend session

Advantages:
- Reduced token usage
- Faster tool schema loading
- Focused capabilities
```

**Enable specialized tools**:

```
For machine learning session:
/tools → Ensure complex reasoning and coding tools enabled

Critical for:
- Algorithm design
- Optimization strategies
- Research synthesis
```

## Advanced Source Control

### Managing Multiple Feature Branches

**Working on several features**:

```
Session setup:
- Clone repo, branch main (baseline)
- Clone repo, branch feature/auth (WIP)
- Clone repo, branch feature/cache (WIP)

Work on auth:
- View files from feature/auth clone
- Make changes
- Test
- Update PR for feature/auth

Switch to cache:
- View files from feature/cache clone
- Make changes
- Test
- Update PR for feature/cache

No branch checkout needed - different clones
```

### Advanced PR Workflows

**Draft PRs for early feedback**:

```
Early implementation stage:
- Create PR with incomplete feature
- Mark as draft
- Request architectural feedback
- Continue implementation

Later:
- Update PR with completion
- Convert from draft to ready
- Request full review
```

**Stacked PR management**:

```
Base: main

Create PR #1 (feature/foundation → main):
- Core infrastructure

Create PR #2 (feature/api → feature/foundation):
- API layer depending on foundation

Create PR #3 (feature/ui → feature/api):
- UI depending on API

Review and merge order: #1, #2, #3
Each PR independently reviewable against its base
```

## Chaos Testing

### Purpose

Test system resilience under failure conditions.

**What chaos testing does**:

* Injects random failures into sandbox
* Simulates network issues, crashes, resource exhaustion
* Validates error handling and recovery
* Identifies resilience gaps

### Using Chaos Testing

```
/chaos

Maestro starts chaos testing:
- Duration: 5 minutes (default)
- Failure injection ongoing
- Your code runs under stress
- System monitors behavior

Report generated showing:
- Failures injected
- System responses
- Recovery patterns
- Issues discovered
```

### Interpreting Results

**Good resilience**:

* Graceful degradation
* Proper error handling
* Automatic recovery
* No data corruption

**Issues to address**:

* Crashes on specific failures
* Resource leaks
* Timeout handling gaps
* State corruption

### When to Use Chaos Testing

**Before production**:

* Validate fault tolerance
* Test error handling
* Verify graceful degradation

**During development**:

* Ensure robust implementation
* Catch edge cases early
* Build confidence in reliability

**Caution**: Experimental feature. Can disrupt normal sandbox operations. Use intentionally.

## Advanced Validation Patterns

### Multi-Level Testing

**Comprehensive validation**:

```
Level 1: Unit tests
"Run unit tests. Verify all pass with >90% coverage."

Level 2: Integration tests
"Run integration tests. Verify service interactions."

Level 3: End-to-end tests
"Run E2E tests in sandbox. Verify full user flows."

Level 4: Performance tests
"Benchmark under realistic load. Show metrics."

Level 5: Security tests
"Run static analysis and dependency scanning. Report issues."

Only after all levels pass: "Feature is complete"
```

### Baseline-Driven Development

**Establish baseline before changes**:

```
Before optimization:
1. Capture current performance metrics
2. Document baseline behavior
3. Create reproducible test harness

After optimization:
4. Run same tests
5. Compare to baseline
6. Prove improvement with data

Advantage: Objective measurement, no guesswork
```

## Session Recovery and Continuity

### Resuming After Long Pause

**After days/weeks**:

```
Session resumed → Maestro restores state

First request:
"/synopsis to remind me where we left off"

Maestro provides:
- What was accomplished
- Current state
- Next logical steps

Then continue with context
```

### Cross-Session Knowledge Transfer

**Pattern**:

```
Session 1:
- Implements and validates feature
- Uses /synopsis at end
- Downloads synopsis markdown

Session 2 (days later, new session):
- Upload synopsis from Session 1
- "Read this synopsis and continue the work"

Maestro:
- Understands prior context
- Picks up where Session 1 left off
- Maintains continuity
```

## Power User Shortcuts

### Rapid Iteration

**Hotkey combinations**:

```
After implementation burst:
/refresh + /compact → Clean context for validation

Before PR:
/refresh + run all tests → Ensure clean state

Session end:
/synopsis + /download-changed → Document + preserve work
```

### Template Workflows

**Save custom instruction sets**:

```
Custom instruction: "For all API implementations:
- Use FastAPI framework
- PostgreSQL for persistence
- Redis for caching
- Pytest with >90% coverage
- Async/await patterns
- Pydantic for validation"

Applies to all requests in session
Consistent patterns automatically
```

### Efficient Communication

**Shorthand for experienced users**:

```
Instead of:
"Please implement the authentication system with JWT tokens, including login and logout endpoints, token refresh functionality, and comprehensive tests for all scenarios."

Try:
"Auth system: JWT, refresh, standard endpoints, full tests"

With established patterns, Maestro infers details
```

## Next Steps

Master advanced features:

* **[Integrations & Credentials](getting-started/integrations-secrets)**: External service integration
* **[Troubleshooting](../reference/troubleshooting)**: Common issues and solutions
* **[FAQ](../reference/faq)**: Frequently asked questions
* **[Best Practices](../reference/best-practices)**: Production-ready patterns