Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

File References

Include file contents in your prompts using the intuitive @filename syntax. zo reads the files and formats them clearly for the AI, making it easy to analyze code, review documents, or process data.

Basic Usage

Single File

Include a single file in your prompt:

zo @data.csv 'Analyze this dataset and find patterns'

zo reads data.csv and includes its contents in the request to the AI.

Multiple Files

Include multiple files in a single prompt:

zo @version1.rs @version2.rs 'What are the key differences?'

Files are processed in order and each is clearly labeled for the AI.

With Model Selection

Combine file references with slash commands:

zo /sonnet @src/main.rs "Review for bugs and performance issues"

The model is selected first, then the file contents are included in the prompt.

How It Works

File Formatting

Files are formatted with XML-style tags for clarity:

<file name="data.csv">
col1,col2,col3
1,2,3
4,5,6
</file>

This format:

  • Makes it clear to the AI where each file begins and ends
  • Preserves the exact filename for context
  • Handles multi-line content cleanly
  • Works well with AI language models

Message Order

When you use multiple input sources, they're combined in this order:

  1. File references - Provide context first
  2. Prompt text - Your natural language question
  3. STDIN - Any piped input (if present)

For example:

cat log.txt | zo @config.toml "Why is this error occurring?"

The AI receives:

  1. Contents of config.toml (file reference)
  2. Your question: "Why is this error occurring?"
  3. Contents from log.txt (STDIN)

Use Cases

Code Analysis

Analyze a single file:

zo @app.py "Find potential bugs and suggest improvements"

Compare implementations:

zo @old_version.c @new_version.c "Explain the improvements made"

Code Review

Review with a specific model:

zo /sonnet @src/main.rs "Review for bugs and performance issues"

Multi-file review:

zo @api.rs @types.rs "Check if the API matches the type definitions"

Documentation Generation

Generate docs from code:

zo @api.rs "Generate API documentation in markdown format"

Multiple files:

zo @*.rs "Generate comprehensive API documentation with examples"

Data Processing

Analyze datasets:

zo @sales_data.csv "Calculate summary statistics and identify trends"

Transform formats:

zo @input.json "Convert this to CSV format with headers"

Configuration Analysis

Understand config files:

zo @config.toml "Explain what each setting does"

Suggest improvements:

zo @nginx.conf "Review this config and suggest optimizations"

Learning from Code

Explain complex code:

zo @algorithm.c "Explain this algorithm step by step for a beginner"

Understand new codebases:

zo @main.go @types.go "Explain how this application works"

Advanced Patterns

Combining with STDIN

Use files for context and STDIN for input:

git diff | zo @README.md "Do these code changes require README updates?"

The AI receives:

  • README.md contents (for context)
  • Your question
  • The git diff output (changes to review)

Chat Mode with Files

Start a chat with file context:

zo --chat @complex_code.rs "Let's refactor this together"
> Make it more functional
> Add error handling
> Now add comprehensive tests
> exit

File references in subsequent messages:

zo --chat "Let's review some code"
> @main.rs What does this do?
> @tests.rs Are these tests comprehensive?
> exit

Multiple File Workflows

Architecture review:

zo @schema.sql @models.py "Does the database schema match the Python models?"

Debug session:

zo @error.log @app.rs "Why is this error occurring and how do I fix it?"

Refactoring:

zo @old_code.py "Refactor this to use async/await and add type hints"

Path Handling

Relative Paths

Reference files relative to your current directory:

zo @src/main.rs "Review this code"
zo @../config.toml "Explain this config"
zo @./data/input.csv "Analyze this data"

Absolute Paths

Use full paths:

zo @/home/user/project/src/main.rs "Review this"
zo @/var/log/app.log "Find error patterns"

Wildcards

Some shells expand wildcards before zo sees them:

# Shell expands to: zo @file1.rs @file2.rs @file3.rs
zo @*.rs "Generate documentation"

Error Handling

Missing Files

If a file doesn't exist, zo shows a clear error:

zo @nonexistent.txt "analyze"
# Error: Failed to read file 'nonexistent.txt': No such file or directory

Unreadable Files

If you don't have permission:

zo @/root/secret.txt "read"
# Error: Failed to read file '/root/secret.txt': Permission denied

In Chat Mode

Errors during chat don't exit the session:

zo --chat "Let's work together"
> @missing.txt analyze this
# Error: Failed to read file 'missing.txt': No such file or directory
> @correct.txt analyze this instead
# Works normally

Technical Details

File Reading

  • Files are read from disk when zo starts (or when you send a message in chat mode)
  • Contents are cached in memory for the request
  • Large files are supported (limited by available memory)
  • Binary files can be referenced but may not produce useful results
  • UTF-8 encoding is assumed

Supported File Types

File references work with any text file:

  • Code: .rs, .py, .js, .go, .c, .cpp, .java, etc.
  • Data: .csv, .json, .xml, .yaml, .toml, etc.
  • Docs: .md, .txt, .html, .rst, etc.
  • Config: .conf, .ini, .env, .config, etc.
  • Logs: .log, any text-based log format

Parsing Logic

zo detects file references using character-by-character parsing:

  1. Looks for @ character
  2. Followed by non-whitespace characters (the filename)
  3. Terminated by whitespace or end of input
  4. Files at the end of input work correctly (no trailing space needed)

Examples:

zo @file.txt analyze          # ✅ Works
zo analyze @file.txt          # ✅ Works
zo @file.txt                  # ✅ Works (no trailing space needed)
zo @file1.txt @file2.txt      # ✅ Both files parsed
zo "@file with spaces.txt"    # ❌ Quotes not supported, use paths without spaces

Best Practices

Clear Prompts

Be specific about what you want:

# ✅ Good
zo @app.py "Find potential security vulnerabilities in authentication"
 
# ❌ Vague
zo @app.py "check this"

Right Model for the Job

Use appropriate models:

# Complex code review
zo /sonnet @main.rs "Comprehensive review with performance analysis"
 
# Quick syntax check
zo /flash @script.sh "Does this bash script have syntax errors?"

File Order Matters

Put the most important files first:

# Main file first, then dependencies
zo @main.rs @lib.rs @types.rs "Explain the architecture"

Combine Features

Mix file references with other zo features:

# With STDIN
git diff | zo @old_version.rs "Compare the diff with the old version"
 
# With custom models
zo /reviewer @pr_changes.rs "Review this PR"
 
# With chat mode
zo --chat @codebase.rs "Let's discuss the architecture"

Real-World Examples

Debugging

Find the root cause:

zo @error.log @app.py "Why is this error occurring?"

Code Migration

Modernize code:

zo @legacy.py "Convert this Python 2 code to Python 3 with type hints"

Security Review

Audit code:

zo /security @auth.rs @api.rs "Find security vulnerabilities"

Performance Analysis

Optimize code:

zo @slow_function.c "How can I optimize this for better performance?"

Test Generation

Create tests:

zo @lib.rs "Generate comprehensive unit tests with edge cases"

API Documentation

Document APIs:

zo @api.rs @types.rs "Generate OpenAPI/Swagger documentation"

Refactoring

Improve code structure:

zo @messy_code.js "Refactor this to use modern ES6+ features"

Architecture Review

Validate design:

zo @schema.sql @models.py @api.py "Review the overall architecture"

Limitations

Binary Files

Binary files (images, executables, etc.) can be referenced but won't produce useful results:

# Won't work well
zo @image.png "Describe this image"

For vision tasks, you need a vision-capable model and proper image encoding (not currently supported).

File Size

Very large files (100MB+) can:

  • Take time to read
  • Use significant memory
  • Hit API token limits
  • Increase costs

Consider using filters or excerpts:

# Instead of the full log
zo @huge.log 'analyze'
 
# Use excerpts
tail -n 1000 huge.log | zo 'Analyze recent errors'

No Directory References

You can't reference entire directories:

# Doesn't work
zo @src/ "analyze all files"
 
# Instead, use shell expansion
zo @src/*.rs "analyze these files"

Tips and Tricks

Quick File Inspection

# One-liner to understand a file
zo @unknown.py "What does this do in one sentence?"

Compare Versions

# Before and after
zo @before.rs @after.rs "Summarize the changes"

Generate Based on Example

# Use a file as a template
zo @example.rs "Create a similar file but for HTTP handling"

Extract Information

# Pull specific data
zo @config.json "Extract all database connection strings"

Validate Correctness

# Check implementations
zo @interface.ts @implementation.ts "Does the implementation match the interface?"

Next Steps

Now that you understand file references, explore: