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

# Commands

Master Maestro's command system for powerful session control.

## What Are Commands?

Commands are user-initiated actions that control session behavior, manage resources, and access utilities. They complement Maestro's autonomous tool use.

**Commands vs Tools**:

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

You can also request command functionality through natural language (e.g., "clone the repository" triggers clone command flow).

## Quick Reference

| Command            | Type   | Description                                                            |
| ------------------ | ------ | ---------------------------------------------------------------------- |
| `/plan`            | Mode   | Explore approaches and ask clarifying questions without making changes |
| `/forget`          | Action | Remove old dialog from memory                                          |
| `/compact`         | Action | Compress memory by summarizing                                         |
| `/refresh`         | Action | Refresh files to show latest iterations only                           |
| `/hidefiles`       | Action | Hide file iterations from context                                      |
| `/tools`           | Action | Manage available tools for this session                                |
| `/synopsis`        | Action | Request session overview from Maestro                                  |
| `/secrets`         | Action | Manage secrets and environment variables                               |
| `/reset-sandbox`   | Action | Force reset of the sandbox environment                                 |
| `/settings`        | Action | Adjust session settings                                                |
| `/skills`          | Action | Manage and configure skills                                            |
| `/clone`           | Action | Clone a GitHub repository                                              |
| `/create`          | Action | Create a new GitHub repository                                         |
| `/pr`              | Action | Create or update a pull request                                        |
| `/download-all`    | Action | Download all session files                                             |
| `/download-new`    | Action | Download only new or modified files                                    |
| `/download-recent` | Action | Download 5 most recently edited files                                  |

## Planning Mode

### `/plan` - Plan Mode

Explore implementation strategies and ask clarifying questions without making code changes.

**When to use**:

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

**Behavior**:

* 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

**Example**:

```
/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
```

**Key principle**: Plan mode is for thinking and asking questions only. Implementation happens after you approve the plan.

## Session Management Commands

### `/forget` - Selective Memory Removal

Remove old dialog to free capacity and improve focus.

**When to use**:

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

**How it works**:

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

**Example flow**:

```
/forget

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

**Best practices**:

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

### `/compact` - Memory Compression

Summarize old memories to preserve key information while reducing tokens.

**When to use**:

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

**How it works**:

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

**What's preserved**:

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

**What's compressed**:

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

**Example scenario**:

```
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

Request Maestro create a comprehensive session overview.

**When to use**:

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

**Output**:
Detailed markdown document covering:

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

**Useful for**:

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

### `/settings` - Session Settings

Configure session-level settings and preferences.

**When to use**:

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

### `/skills` - Skill Management

View and configure available skills for your session.

**When to use**:

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

## File Management Commands

### `/hidefiles` - Reduce File Context

Hide specific file iterations from Maestro's view.

**When to use**:

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

**How it works**:

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

**Example**:

```
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

Reset file view to show only the latest iteration of each file.

**When to use**:

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

**Effect**:

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

**Best practice**: Use before major validation phases to ensure Maestro sees clean current state.

## Download Commands

### `/download-all` - Complete Export

Download all session files as a zip archive.

**When to use**:

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

**What's included**:

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

**What's excluded**:

* Build artifacts
* Dependencies (node\_modules, venv, etc.)
* Temporary files
* Binary artifacts

### `/download-new` - New and Modified Files

Download only files that have been created or modified.

**When to use**:

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

**Output**:

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

**Typical workflow**:

```
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

Download the 5 most recently modified files individually.

**When to use**:

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

**Output**: Individual file downloads (not zipped)

## Source Control Commands

### `/clone` - Clone Repository

Clone a GitHub repository into your session.

**Capabilities**:

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

**Interactive flow**:

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

**Key features**:

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

**Overwrite clones**:

```
Clone same repository again to pull remote changes.

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

**Use cases for overwrite**:

* Pull teammate's recent commits
* Update to latest main branch
* Sync your PR branch with base

### `/create` - Create Repository

Create a new GitHub repository.

**Configuration options**:

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

**Interactive flow**:

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)

**Auto-clone advantage**: Immediately start working in the new repository.

### `/pr` - Pull Request

Create or update a GitHub pull request.

**Workflow**:

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

**Creating new PR**:

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

**Updating existing PR**:

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

**Important**: Maestro's workspace is separate from git. Changes only pushed when you use `/pr`.

## Secrets Management

### `/secrets` - Secret Management

Manage which secrets are active in your session.

**Capabilities**:

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

**Interactive flow**:

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

**How it works**:

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

**Example use case**:

```
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
```

**Secrets Manager** (Bottom-Left Menu):

* 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

Forcibly reset the sandbox if stuck or unresponsive.

**When to use**:

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

**What happens**:

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

**Caution**: Running processes lost. Only use when necessary.

## Utility Commands

### `/tools` - Tool Management

Display and manage available tools for the session.

**Capabilities**:

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

**When to use**:

* 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

**Use commands proactively**:

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

**Don't wait for problems**:

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

### Combining Commands

**Effective combinations**:

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

**Let Maestro use tools instead** for:

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

**Commands are for**:

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

## Troubleshooting Common Issues

### "Session capacity is full"

**Solution sequence**:

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"

**Check**:

* 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"

**Verify**:

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"

**Current limit**: \~10GB per repository

**Workarounds**:

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

## Advanced Usage

### Planning then Implementation

**Plan first, implement second**:

```
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

Instead of `/clone`:

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

Maestro recognizes intent and triggers clone command
```

**Advantage**: More conversational, less syntax to remember

**Tradeoff**: May require confirmation step

## Getting Help

### Within Maestro

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

### Reference Documentation

This page provides complete command documentation.

Bookmark for quick reference.

## Next Steps

With command mastery, explore:

* **[Tools Overview](getting-started/tools)**: Understand Maestro's autonomous capabilities
* **[Sandbox Guide](getting-started/sandbox)**: Deep dive into execution environment
* **[Source Control](getting-started/source-control)**: Advanced GitHub workflows
* **[Session Strategies](getting-started/session-strategies)**: Patterns for different project types