Built-in Commands

Agent Air provides a set of standard slash commands that cover common functionality needed in conversational agents. These commands handle operations like clearing history, managing sessions, switching themes, and exiting the application. They serve as both useful defaults and reference implementations for building custom commands.

The built-in commands demonstrate best practices for command implementation, including proper use of CommandResult variants, deferred actions through CommandContext, and accessing session information. You can include all defaults, select specific ones, or use them as templates for your own commands.

Available Commands

The framework provides nine built-in commands:

/help

The help command displays a list of all registered commands with their descriptions. It iterates through ctx.commands() and formats each command’s name and description into a readable list. This command is useful for discoverability, letting users see what commands are available without consulting documentation.

impl SlashCommand for HelpCommand {
    fn name(&self) -> &str { "help" }
    fn description(&self) -> &str { "Show available commands and usage" }

    fn execute(&self, _args: &str, ctx: &mut CommandContext) -> CommandResult {
        let mut help = String::from("Available commands:\n\n");
        for cmd in ctx.commands() {
            help.push_str(&format!("  /{} - {}\n", cmd.name(), cmd.description()));
        }
        CommandResult::Message(help)
    }
}

/clear

The clear command removes all messages from the conversation view, giving users a fresh start without losing session state. This uses the deferred action pattern where the command requests the clear operation through the context, and the App executes it after the command returns.

impl SlashCommand for ClearCommand {
    fn name(&self) -> &str { "clear" }
    fn description(&self) -> &str { "Clear the conversation history" }

    fn execute(&self, _args: &str, ctx: &mut CommandContext) -> CommandResult {
        ctx.clear_conversation();
        CommandResult::Handled
    }
}

The CommandResult::Handled indicates that the command has managed its own UI updates and the App should not display any additional message.

/compact

The compact command triggers context compaction to reduce token usage while preserving essential conversation context. This is useful when approaching token limits or when you want to condense a long conversation into a summary. The compaction is performed by the LLM controller using the configured compaction strategy.

impl SlashCommand for CompactCommand {
    fn name(&self) -> &str { "compact" }
    fn description(&self) -> &str { "Compact the conversation history" }

    fn execute(&self, _args: &str, ctx: &mut CommandContext) -> CommandResult {
        ctx.compact_conversation();
        CommandResult::Handled
    }
}

/themes

The themes command opens the theme picker overlay, allowing users to browse and select from available themes. The picker displays theme names and previews, and selecting a theme applies it immediately. This provides a visual way to customize the appearance without editing configuration files.

impl SlashCommand for ThemesCommand {
    fn name(&self) -> &str { "themes" }
    fn description(&self) -> &str { "Open theme picker to change colors" }

    fn execute(&self, _args: &str, ctx: &mut CommandContext) -> CommandResult {
        ctx.open_theme_picker();
        CommandResult::Handled
    }
}

/sessions

The sessions command opens the session picker overlay, enabling users to view existing sessions and switch between them. Each session maintains its own conversation history and context, so switching sessions lets users work on different topics without losing progress.

impl SlashCommand for SessionsCommand {
    fn name(&self) -> &str { "sessions" }
    fn description(&self) -> &str { "View and switch between sessions" }

    fn execute(&self, _args: &str, ctx: &mut CommandContext) -> CommandResult {
        ctx.open_session_picker();
        CommandResult::Handled
    }
}

/status

The status command displays current session information including the session ID, agent name, and version. This is useful for debugging and for users who want to confirm which session they’re working in, especially when managing multiple sessions.

impl SlashCommand for StatusCommand {
    fn name(&self) -> &str { "status" }
    fn description(&self) -> &str { "Show current session status" }

    fn execute(&self, _args: &str, ctx: &mut CommandContext) -> CommandResult {
        CommandResult::Message(format!(
            "Session: {}\nAgent: {} v{}",
            ctx.session_id(),
            ctx.agent_name(),
            ctx.version()
        ))
    }
}

/version

The version command shows the agent name and version number. This simple command is useful for support scenarios where users need to report which version they’re running, or for developers verifying deployments.

impl SlashCommand for VersionCommand {
    fn name(&self) -> &str { "version" }
    fn description(&self) -> &str { "Show application version" }

    fn execute(&self, _args: &str, ctx: &mut CommandContext) -> CommandResult {
        CommandResult::Message(format!("{} v{}", ctx.agent_name(), ctx.version()))
    }
}

/new-session

The new-session command creates a fresh LLM session with empty conversation history. This defers the session creation to the App, which handles the controller communication and session setup. Use this when you want to start a completely new conversation without the context of previous messages.

impl SlashCommand for NewSessionCommand {
    fn name(&self) -> &str { "new-session" }
    fn description(&self) -> &str { "Create a new LLM session" }

    fn execute(&self, _args: &str, ctx: &mut CommandContext) -> CommandResult {
        ctx.create_new_session();
        CommandResult::Handled
    }
}

/quit

The quit command exits the application by requesting a quit through the context and returning CommandResult::Quit. The combination ensures proper cleanup through exit handlers while signaling to the App that it should terminate.

impl SlashCommand for QuitCommand {
    fn name(&self) -> &str { "quit" }
    fn description(&self) -> &str { "Exit the application" }

    fn execute(&self, _args: &str, ctx: &mut CommandContext) -> CommandResult {
        ctx.request_quit();
        CommandResult::Quit
    }
}

Using Default Commands

The default_commands() function returns all built-in commands as a vector, useful when you need programmatic access to the defaults:

use agent_air::tui::commands::default_commands;

let commands = default_commands();

Using CommandRegistry::with_defaults() automatically includes all these commands and provides builder methods for customization:

use agent_air::tui::commands::CommandRegistry;

let commands = CommandRegistry::with_defaults().build();

Excluding Commands

To use defaults but remove specific commands, use the remove() method. This is useful when certain commands don’t make sense for your application, such as disabling session management in a single-session agent:

let commands = CommandRegistry::with_defaults()
    .remove("quit")        // Disable the quit command
    .remove("new-session") // Disable session creation
    .remove("sessions")    // Disable session switching
    .build();

Selective Inclusion

For minimal setups or when you need precise control, build a registry with only the commands you need:

use agent_air::tui::commands::{
    CommandRegistry, HelpCommand, ClearCommand, ThemesCommand, QuitCommand
};

let commands = CommandRegistry::new()
    .add(HelpCommand)
    .add(ClearCommand)
    .add(ThemesCommand)
    .add(QuitCommand)
    .build();

Command Structs

Each built-in command is implemented as a unit struct that implements SlashCommand:

• HelpCommand
• ClearCommand
• CompactCommand
• ThemesCommand
• SessionsCommand
• StatusCommand
• VersionCommand
• NewSessionCommand
• QuitCommand

These structs can be instantiated directly when building a custom command set, giving you the flexibility to include exactly the commands your application needs.