Advanced Tutorial: SuperDuck.AI CLI with Vi/Vim

Introduction

The sd command line tool transforms your Vi/Vim editing experience by seamlessly integrating AI capabilities directly into your workflow. This tutorial explores how to leverage this powerful combination to enhance your productivity, improve your writing, and simplify complex editing tasks.

Installation and Setup

Before diving into usage examples, ensure you have the sd command line tool installed and properly configured:

# Installation may vary depending on your OS and distribution method

# Verify installation
sd --version

Core Syntax

The fundamental pattern for using sd with Vi/Vim is:

:[range]!sd '[instruction]'

Where:

• [range] specifies which lines to process
• ! is Vi/Vim's filter command
• sd is the command line tool
• [instruction] is your prompt to the AI

Essential Techniques

Processing the Entire File

:%!sd 'Improve this text'

This takes your entire buffer (%), sends it through the AI with the instruction "Improve this text", and replaces the content with the result.

Working with Specific Lines

:10,30!sd 'Summarize these paragraphs'

This processes only lines 10 through 30, replacing them with a summary.

Visual Mode Selection

For more precise control:

1. Press v to enter visual mode
2. Select the text you want to process
3. Press : (a colon will appear with '<,'>)
4. Complete the command: '<,'>!sd 'Rewrite in a professional tone'

Inserting Generated Content

To add new AI-generated content without replacing existing text:

:r !sd 'Write a function that calculates fibonacci numbers in Python'

This reads (r) the output of the AI command into your buffer at the current cursor position.

Advanced Workflow Techniques

Keyboard Mappings

Add these to your .vimrc for rapid AI assistance:

" Improve writing on current paragraph
nnoremap <leader>sd vip:!sd 'Improve this writing'<CR>

" Generate documentation for selected code
vnoremap <leader>doc :!sd 'Write documentation for this code'<CR>

" Fix spelling and grammar in selection
vnoremap <leader>fix :!sd 'Fix spelling and grammar'<CR>

" Explain selected code
vnoremap <leader>exp :!sd 'Explain what this code does in simple terms'<CR>

" Simplify complex text
vnoremap <leader>simp :!sd 'Simplify this text for clarity'<CR>

" Generate a test for selected function
vnoremap <leader>test :!sd 'Write unit tests for this function'<CR>

Command Mode Abbreviations

Create shorthand commands for frequently used operations:

" Add to .vimrc
command! -range=% Improve <line1>,<line2>!sd 'Improve this writing'
command! -range=% Summarize <line1>,<line2>!sd 'Summarize this text concisely'
command! -range=% Proofread <line1>,<line2>!sd 'Fix grammar, spelling, and style issues'
command! -range=% Simplify <line1>,<line2>!sd 'Simplify this content for clarity'

Usage:

:Improve
:5,20Summarize
:Proofread

AI-Powered Macros

Combine with Vi/Vim macros for complex transformations:

" First, create a macro that uses AI to process text
" Example: Record a macro to convert a comment into documentation
qq                          " Start recording to register q
vip                         " Select paragraph
:!sd 'Convert this comment to proper documentation'<CR>  " Process with AI
q                           " Stop recording

" Then use the macro on multiple parts of your file
:%g/\/\/ TODO:/normal @q   " Run the macro on every line containing "// TODO:"

Practical Use Cases

Advanced Prompt Engineering

The quality of results depends significantly on your prompting technique. Here are strategies for crafting effective AI prompts:

Combining with Other Unix Tools

The true power of the sd command comes from combining it with other Unix tools:

:r !grep -r "TODO" . | sd 'Generate a prioritized task list based on these TODOs'

:r !git log -p file.js | sd 'Summarize the evolution of this file'

:r !cat error.log | sd 'Analyze these errors and suggest solutions'

Troubleshooting

Debugging Tips

When AI processing doesn't work as expected:

:r !sd 'Debug why this code fails with error XYZ' < debug.log

Or capture the AI's reasoning process:

:r !sd 'Explain step by step why this algorithm is inefficient'

Real-world Workflow Examples

Documentation Writer

# In a single command, generate a full README from a codebase
:r !find . -name "*.js" | xargs cat | sd 'Generate a comprehensive README.md for this JavaScript project'

Code Reviewer

# Get AI review of your changes before committing
:r !git diff | sd 'Review these changes and suggest improvements'

Learning Assistant

# Learn new concepts while editing
:r !sd 'Explain the concept of recursion with examples in the context of this code'

Integration with Project-specific Knowledge

Create aliases for project-specific operations:

function ai-docs() {
    cat $1 | sd "Generate documentation following our team's style guide: 
                 - Use markdown
                 - Include examples
                 - Link to related modules"
}

# In vim
:r !ai-docs CurrentFile.js

Best Practices

• Save before transforming: Use :w before applying AI operations on large sections.
• Use version control: Commit before significant AI-driven changes.
• Review all changes: AI can make subtle modifications that might change functionality.
• Start with small sections: Build confidence before processing entire files.
• Build a prompt library: Keep a collection of effective prompts for reuse.
• Chain transformations: Apply multiple focused AI operations rather than one complex transformation.

Extended Configuration

Creating Your Own "e" Command

You can create a customized AI editing assistant called "e" (short for "editor", pronounced "echo") that has its own personality and behavior tailored to your specific needs. This creates a more focused tool that complements your vi/vim editing workflow.

Step 1: Create the Command

First, create a symbolic link from the existing "sd" command to your new "e" command:

# Create the symbolic link
ln -s $(which sd) ~/bin/e

# Make sure ~/bin is in your PATH
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc  # or .zshrc for Zsh users
source ~/.bashrc  # Apply the changes

Step 2: Configure Your Editor's Personality

Next, customize how your editor behaves by setting environment variables in your shell configuration file:

# Add these lines to your .bashrc or .zshrc file
export E_SYSTEM_PROMPT="You are an editor specialized in improving technical writing.
Your goals are to:
1. Make text clearer and more concise
2. Maintain the author's original voice and meaning
3. Fix grammatical issues without changing style
4. Suggest structural improvements when appropriate
5. Format code snippets for readability"

# Choose which AI model to use
export E_MODEL="gpt-4"  # or another model of your choice

Step 3: Use Your Custom Editor

Now you can use your specialized editor in vi/vim with the same familiar syntax:

:%!e 'Make this paragraph more engaging'
:10,20!e 'Simplify this explanation'
:'<,'>!e 'Convert this to bullet points'

Personality Ideas for Different Editing Needs

You can create different editor personalities for various tasks:

• Technical Editor: "You are a technical editor who specializes in making complex concepts accessible without sacrificing accuracy."
• Code Reviewer: "You are a code reviewer focused on readability, performance, and security. Suggest improvements without rewriting functional code."
• Academic Editor: "You are an academic editor who helps strengthen arguments and improve clarity while maintaining scholarly tone."
• Marketing Copy Editor: "You are a marketing editor who makes text more compelling and persuasive while keeping it authentic."

The beauty of this approach is that your "e" command becomes an intuitive extension of your editing environment, blending naturally with vi/vim's philosophy of specialized, composable tools. Each time you invoke it, you're working with an assistant that understands your preferences and editing style.

Creating a .airc File

For project-specific AI behavior, create a .airc file:

# .airc example
style_guide_path=./docs/style_guide.md
code_standards_path=./docs/code_standards.md
default_language=javascript
default_api_model=gpt-4
tone=professional

Then in your .vimrc:

function! AIWithProjectContext(prompt)
    let l:context = system('cat .airc')
    return system('sd "Project context: ' . l:context . '\n\nTask: ' . a:prompt . '"')
endfunction

command! -range -nargs=1 AIProject <line1>,<line2>call AIWithProjectContext(<q-args>)

Conclusion

Integrating the sd command line tool with Vi/Vim transforms your editor into an intelligent assistant that understands context, follows instructions, and helps you work more efficiently. By building AI operations into your editing workflow, you can automate routine tasks, improve your writing, refactor code more effectively, and focus on more creative aspects of your work.

As you become more comfortable with these techniques, you'll develop your own patterns and shortcuts tailored to your specific needs and projects.