Voge ZSH Plugin#

A powerful ZSH plugin that provides intelligent command transformation, file tagging, and conversation management for the Voge AI assistant.

Features#

• Smart Command Transformation: Convert :command syntax into voge executions
• Agent Selection: Tab completion for available agents using :agent_name
• File Tagging: Interactive file selection with @[filename] syntax
• Syntax Highlighting: Visual feedback for commands and tagged files
• Conversation Continuity: Automatic session management across commands
• Interactive Completion: Fuzzy finding for files and agents via built-in picker

Prerequisites#

Before using this plugin, ensure you have the following tools installed:

• fd - Fast file finder (alternative to find)
• voge - The Voge CLI tool

Installation of Prerequisites#

# macOS (using Homebrew)
brew install fd

# Ubuntu/Debian
sudo apt install fd-find

# Arch Linux
sudo pacman -S fd

Usage#

Starting a Conversation#

Begin any command with : followed by your prompt:

: Get the current time

This automatically starts a new conversation with the default Voge agent.

Using Specific Agents#

Specify an agent by name after the colon:

:sage How does caching work in this system?
:muse Create a deployment strategy for my app

Tab Completion: Type : followed by partial agent name and press TAB for interactive selection.

File Tagging#

Tag files in your commands using the @[filename] syntax:

: Review this code @[src/main.rs]
: Explain the configuration in @[config.yaml]

Interactive Selection: Type @ and press TAB to search and select files interactively using fuzzy finder.

Conversation Continuity#

Commands within the same session maintain context:

# First command
: My project uses React and TypeScript

# Second command (remembers previous context)
: How can I optimize the build process?

The plugin automatically manages conversation IDs to maintain context across related commands.

Command Naming#

Shell commands should follow the Object-Action format.

Examples:

• :provider-login
• :sync-status

For backward compatibility, :login remains available as an alias for :provider-login.

Session Management#

Starting New Sessions#

Clear the current conversation context and start fresh:

:new
# or use the alias
:n

This will:

• Clear the current conversation ID
• Show the banner with helpful information
• Reset the session state
• Display a confirmation message with timestamp

System Information#

View system and project information:

:info
# or use the alias
:i

This displays:

• System information

• Project details

• Current configuration

• Current configuration

Switching Conversations#

Browse and switch between conversations interactively:

:conversation
# or use the alias
:c

This will display an interactive list of all conversations with preview, allowing you to select and switch.

Switch to a specific conversation by ID:

:conversation <conversation_id>

Toggle between current and previous conversation (like cd -):

:conversation -
# or
:c -

The plugin remembers your previous conversation, allowing you to quickly toggle back and forth. This works just like cd - in your shell, and also works with :new - when you start a new conversation, you can toggle back to your previous one.

If there's no previous conversation tracked (e.g., first time using the plugin), :c - will show the conversation list popup, allowing you to select a conversation.

This is useful when:

• You need to temporarily check another conversation and come back
• You're comparing or referencing information between two conversations
• You want to quickly switch context between related tasks
• You started a new conversation but want to reference the previous one

Cloning Conversations#

Create a copy of an existing conversation with interactive selection:

:clone

This will:

• Display an interactive list of all conversations with preview
• Allow you to select a conversation to clone
• Create a new conversation with the same content
• Automatically switch to the cloned conversation
• Show the cloned conversation content and details

You can also clone a specific conversation by providing its ID:

:clone <conversation_id>

This is useful when you want to:

• Create a backup before making significant changes
• Start a new conversation branch from an existing context
• Experiment with different approaches while preserving the original

Session Status#

The plugin automatically displays session information including:

• Conversation ID when starting new sessions
• Active agent information
• New session confirmations with timestamps

Syntax Highlighting#

The plugin provides visual feedback through syntax highlighting:

• Tagged Files (@[filename]): Displayed in green bold
• Agent Commands (:agent): Agent names in yellow bold
• Command Text: Remaining text in white bold

Configuration#

Customize the plugin behavior by setting these variables before loading the plugin:

# Custom voge binary location
export VOGE_BIN="/path/to/custom/voge"

Available Configuration Variables#

• VOGE_BIN: Path to the voge executable (default: voge)
• VOGE_EDITOR: Editor command to use for :edit command (default: $EDITOR or nano)
• VOGE_SYNC_ENABLED: Enable/disable automatic workspace sync (default: true)
• VOGE_MAX_COMMIT_DIFF: Maximum diff size for commit message generation in bytes (default: 100000)
• VOGE_SKIP_INTERACTIVE: Skip interactive prompts (internal use)
• VOGE_CURRENCY_SYMBOL: Currency symbol for cost display in ZSH theme (default: "$")
• VOGE_CURRENCY_CONVERSION_RATE: Conversion rate for currency display (default: 1.0)
• NERD_FONT: Enable Nerd Font icons in ZSH theme (default: auto-detected, set to "1" or "true" to enable, "0" or "false" to disable)
• USE_NERD_FONT: Alternative variable for enabling Nerd Font icons (same behavior as NERD_FONT)
• Internal pattern matching for conversation syntax (:)
• New session command keyword: :new or :n

Codebase Indexing#

Sync your codebase for semantic search:

:sync

This will index the current directory for semantic code search.

Environment Diagnostics#

Run comprehensive environment diagnostics to check your Voge setup:

:doctor

This will check:

• ZSH version and terminal information
• Voge installation and version
• Plugin and theme loading status
• Completions availability
• Dependencies (fd, bat)
• ZSH plugins (autosuggestions, syntax-highlighting)
• Editor configuration and PATH setup
• Nerd Font support for icons

.voge Directory#

The plugin creates a .voge directory in your current working directory (similar to .git) for temporary files:

• VOGE_EDITMSG.md: Temporary file used when opening an external editor with :edit

Advanced Features#

Command History#

All transformed commands are properly saved to ZSH history, allowing you to:

• Navigate command history with arrow keys
• Search previous voge commands with Ctrl+R
• Reuse complex commands with file tags

Keyboard Shortcuts#

• Tab: Interactive completion for files (@) and agents (:)
• Enter: Transform and execute :commands
• Ctrl+C: Interrupt running voge commands

Examples#

Basic Usage#

: What's the weather like?
:sage Explain the MVC pattern
:planner Help me structure this project

With File Tagging#

: Review this implementation @[src/auth.rs]
: Debug the issue in @[logs/error.log] @[config/app.yml]

Session Flow#

: I'm working on a Rust web API
: What are the best practices for error handling?
: Show me an example with @[src/errors.rs]
:info
:new
: New conversation starts here

Codebase Indexing#

# Sync current directory for semantic search
:sync