Getting Started with AIA¶

This guide will walk you through your first steps with AIA, from basic usage to creating your first prompts and workflows.

Prerequisites¶

Before starting, make sure you have:

Installed AIA
Set up your API keys (see Installation)
Created your prompts directory (~/.prompts)

Your First AIA Command¶

Let's start with the simplest possible usage:

aia --chat

This opens an interactive chat session. Type your question and press Enter:

You: Hello, what can you help me with?
AI: Hello! I'm an AI assistant that can help you with a wide variety of tasks...

Type exit or press Ctrl+C to end the chat.

Basic Usage Patterns¶

1. Direct Questions¶

Ask questions directly without creating prompt files:

# Simple question
aia --chat "What's the capital of France?"

# Technical question
aia --chat "Explain how HTTP works"

2. Using Different Models¶

Specify which AI model to use:

# Use GPT-4
aia --model gpt-4 --chat

# Use Claude
aia --model claude-3-sonnet --chat

# See all available models
aia --available_models

3. Adjusting AI Behavior¶

Control the AI's response style:

# More creative responses
aia --temperature 1.2 --chat

# More focused responses  
aia --temperature 0.3 --chat

# Shorter responses
aia --terse --chat

# Limit response length
aia --max_tokens 100 --chat

Creating Your First Prompt¶

Instead of typing questions each time, you can create reusable prompt files.

1. Create a Simple Prompt¶

# Create your first prompt file
echo "Explain this code and suggest improvements:" > ~/.prompts/code_review.txt

2. Use the Prompt¶

# Run the prompt (you'll be asked for the code to review)
aia code_review

# Or provide a context file
aia code_review my_script.py

3. Create a More Complex Prompt¶

cat > ~/.prompts/blog_writer.txt << 'EOF'
Write a professional blog post about the following topic:

Topic: <%= topic %>
Target audience: <%= audience %>
Word count: <%= word_count %>

Please include:
- An engaging introduction
- Well-structured main points
- A compelling conclusion
- SEO-friendly headings
EOF

Use it with parameters:

aia blog_writer --topic "AI productivity tools" --audience "developers" --word_count 800

Understanding Prompts with Context¶

AIA can include context from files:

1. Review Code Files¶

# Review a specific file
aia code_review src/main.rb

# Review multiple files
aia code_review src/*.rb

2. Analyze Documents¶

# Analyze a document
echo "Summarize this document and extract key points:" > ~/.prompts/summarize.txt
aia summarize report.pdf

3. Process Data Files¶

# Create a data analysis prompt
echo "Analyze this data and provide insights:" > ~/.prompts/analyze_data.txt
aia analyze_data data.csv

Using Directives¶

Prompts can include special directives for dynamic behavior:

1. Configuration Directives¶

cat > ~/.prompts/creative_writing.txt << 'EOF'
//config temperature 1.3
//config max_tokens 2000
//config model gpt-4

Write a creative short story about:
<%= topic %>

Make it engaging and unique!
EOF

2. File Inclusion Directives¶

cat > ~/.prompts/project_analysis.txt << 'EOF'
Analyze this project structure and provide recommendations:

//include README.md
//include package.json
//include src/

Focus on architecture, dependencies, and best practices.
EOF

3. Shell Command Directives¶

cat > ~/.prompts/system_status.txt << 'EOF'
Here's my current system status:

CPU Usage:
//shell top -l 1 -n 10 | head -20

Disk Usage:  
//shell df -h

Memory Usage:
//shell free -h

Please analyze this and suggest optimizations.
EOF

Working with Roles¶

Roles help set context for the AI:

1. Create a Role File¶

mkdir -p ~/.prompts/roles
cat > ~/.prompts/roles/code_expert.txt << 'EOF'
You are an expert software developer with 15+ years of experience.
You specialize in clean code, best practices, and modern development patterns.
Always provide specific, actionable advice with code examples.
EOF

2. Use the Role¶

aia --role code_expert code_review my_app.rb

Fuzzy Search (with fzf)¶

If you have fzf installed, you can use fuzzy search:

# Search for prompts interactively
aia --fuzzy

# This opens a searchable list of all your prompts

Saving Output¶

Save AI responses to files:

# Save to a file
aia --out_file response.md my_prompt

# Append to an existing file
aia --out_file response.md --append my_prompt

# Format with Markdown
aia --out_file response.md --markdown my_prompt

Chat Mode Features¶

1. Persistent Chat¶

# Start a chat that remembers context
aia --chat

Within chat: - Your conversation history is maintained - You can reference previous messages - Type /help for chat commands - Type /save filename.md to save the conversation

2. Chat with Initial Prompt¶

# Start chat with a specific role/prompt
aia --chat --role code_expert
aia --chat system_architect

3. Multi-turn Conversations¶

You: Explain REST APIs
AI: [Detailed explanation of REST APIs...]

You: Now give me a Python example
AI: [Python code example using the previous REST context...]

You: How would you test this?
AI: [Testing strategies specific to the Python example...]

Common Workflows¶

1. Code Review Workflow¶

# Set up the workflow
echo "Review this code for bugs, style, and improvements:" > ~/.prompts/code_review.txt

# Use it regularly
aia code_review src/new_feature.py
aia --model claude-3-sonnet code_review complex_algorithm.rb

2. Documentation Workflow¶

# Create documentation prompt
cat > ~/.prompts/document_code.txt << 'EOF'
Generate comprehensive documentation for this code:

//include <%= file %>

Include:
- Purpose and functionality
- Parameters and return values
- Usage examples
- Edge cases and considerations
EOF

# Use it
aia document_code --file src/api.py

3. Learning Workflow¶

# Create learning prompt
cat > ~/.prompts/explain_concept.txt << 'EOF' 
//config temperature 0.7
//role teacher

Explain the concept of "<%= concept %>" in simple terms.

Include:
- Definition and core principles
- Real-world examples
- Common use cases
- Key benefits and drawbacks
- Related concepts

Adjust the explanation for a <%= level %> level understanding.
EOF

# Use it for learning
aia explain_concept --concept "microservices" --level "beginner"
aia explain_concept --concept "machine learning" --level "intermediate"

Best Practices¶

1. Organize Your Prompts¶

# Create a logical directory structure
mkdir -p ~/.prompts/{development,writing,analysis,personal}

# Categorize prompts
mv ~/.prompts/code_review.txt ~/.prompts/development/
mv ~/.prompts/blog_writer.txt ~/.prompts/writing/

2. Use Descriptive Names¶

# Good prompt names
~/.prompts/development/code_review_security.txt
~/.prompts/writing/blog_post_technical.txt
~/.prompts/analysis/data_insights.txt

# Avoid generic names
~/.prompts/prompt1.txt
~/.prompts/test.txt

3. Version Control Your Prompts¶

cd ~/.prompts
git init
git add .
git commit -m "Initial prompt collection"

# Keep your prompts under version control
git add new_prompt.txt
git commit -m "Add prompt for API documentation"

4. Test Different Models¶

# Test with different models to find the best fit
aia --model gpt-3.5-turbo code_review app.py
aia --model gpt-4 code_review app.py  
aia --model claude-3-sonnet code_review app.py

# Compare outputs and choose the best model for each task

Next Steps¶

Now that you understand the basics:

Explore Advanced Features:
Chat Mode Guide
Working with Models
Tools Integration
Learn Advanced Techniques:
Advanced Prompting
Workflows & Pipelines
Prompt Management
Browse Examples:
Examples Directory
Tools & MCP Examples
Reference Documentation:
CLI Reference
Directives Reference
Configuration Guide

Troubleshooting¶

Common Issues¶

"No prompt found"¶

Check that the prompt file exists: ls ~/.prompts/
Verify the filename matches what you're typing
Try fuzzy search: aia --fuzzy

"Model not available"¶

Check your API keys: echo $OPENAI_API_KEY
List available models: aia --available_models
Check your internet connection

"Permission denied"¶

Check file permissions: ls -la ~/.prompts/
Ensure the prompts directory is readable

Getting Help¶

Use aia --help for command help
Use --verbose flag to see what AIA is doing
Use --debug flag for detailed debugging information
Check the FAQ for common questions
Report issues on GitHub

Summary¶

You've learned:

✅ How to run basic AIA commands
✅ How to create and use prompts
✅ How to work with different AI models
✅ How to use roles and context files
✅ How to organize your workflow
✅ Basic troubleshooting

You're now ready to explore AIA's more advanced features and create your own AI-powered workflows!