Skip to main content

Screenshot Analysis

Codely CLI provides intelligent screenshot analysis, letting you directly paste images from the clipboard into input prompts. The system automatically saves the images and inserts references.

Overview​

The screenshot feature is a convenient capability of Codely CLI that can:

  • Automatically detect images in the clipboard: Identify whether the clipboard contains image data

  • Automatically save to a temporary directory: Save images to the project's .codely-cli/clipboard/ directory

  • Intelligently insert references: Automatically insert image reference text at the cursor position

  • Cross-platform support: Support for Windows and macOS systems

  • Automatic cleanup: Automatically clean up temporary image files older than 1 hour

How It Works​

Detection Process​

  • User presses Ctrl+V to perform paste operation
  • System detects clipboard content type
  • If it's an image, execute screenshot save process
  • If it's text, execute normal text paste

Save Process​

User takes screenshot → Copy to clipboard → Ctrl+V paste
    ↓
Detect clipboard type
    ↓
Save to .codely-cli/clipboard/clipboard-\{timestamp\}.png
    ↓
Insert "Screenshot saved to {relativePath}." at cursor position

Non-Interactive Mode Usage​

In non-interactive mode, the screenshot feature is triggered by keyboard shortcuts.

Basic Usage​

# Start Codely CLI
codely

# In input prompt:
# 1. Use system screenshot tool to capture (e.g., Windows Win+Shift+S or macOS Cmd+Shift+4)
# 2. Press Ctrl+V or Alt+V to paste

Usage Examples​

1. Basic Screenshot Pasting​

> [Screenshot and copy to clipboard]
> [Press Ctrl+V or Alt+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.

2. Inserting Screenshot in Existing Text​

> Please analyze the design of this interface: [Press Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png. and provide improvement suggestions

3. Multiple Screenshots​

> This is the first screenshot: [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
>
> This is the second screenshot: [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096100000.png.
>
> Please compare the differences between these two interfaces

Interactive Mode Usage​

In interactive mode, the screenshot feature works the same as in non-interactive mode, mainly triggered by the Ctrl+V shortcut.

Application Scenarios in Interactive Mode​

1. UI/UX Design Review​

> Please help me review the design of this interface: [Ctrl+V paste screenshot]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> Provide suggestions from usability, aesthetics, and consistency perspectives

2. Error Troubleshooting​

> I encountered this error: [Ctrl+V paste error screenshot]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> Please help me analyze possible causes and solutions

3. Code Review​

> Please review the output of this code: [Ctrl+V paste screenshot]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> Point out potential issues and improvements

4. Documentation Writing​

> I need to write documentation for this feature, please based on the screenshot: [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> Generate feature description and usage steps

Technical Implementation​

Platform Support​

Windows​

Using PowerShell for clipboard operations:

# Check if clipboard contains image
Add-Type -AssemblyName System.Windows.Forms
if ([System.Windows.Forms.Clipboard]::ContainsImage()) {
    Write-Output 'true'
} else {
    Write-Output 'false'
}

# Save clipboard image
$image = [System.Windows.Forms.Clipboard]::GetImage()
$image.Save('path/to/file.png', [System.Drawing.Imaging.ImageFormat]::Png)

macOS​

Using AppleScript and osascript for clipboard operations:

# Check clipboard type
clipboard info | grep -E "«class PNGf»|TIFF picture|JPEG picture"

# Save clipboard image
set imageData to the clipboard as «class PNGf»
set fileRef to open for access POSIX file "path/to/file.png" with write permission
write imageData to fileRef
close access fileRef

File Naming Rules​

  • Format: clipboard-{timestamp}.{extension}
  • Timestamp: Use millisecond-level timestamp to ensure uniqueness
  • Extension: Automatically selected based on image format (.png, .jpg, .tiff, .gif)

Examples:

clipboard-1704096000000.png
clipboard-1704096100000.jpg
clipboard-1704096200000.tiff

Storage Location​

  • Default directory: <project root>/.codely-cli/clipboard/
  • Relative path reference: Inserted references use paths relative to the project root

Example:

Project structure:
my-project/
├── .codely-cli/
│   └── clipboard/
│       ├── clipboard-1704096000000.png
│       └── clipboard-1704096100000.png
├── src/
└── README.md

Inserted reference:
"Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png."

Automatic Cleanup Mechanism​

The system automatically cleans up temporary image files older than 1 hour:

Advanced Usage​

Combined with File References​

> Please analyze the following files and screenshots:
> @src/components/Button.tsx
> and [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> Check if code implementation matches screenshot display

Using in Multi-line Input​

> I have the following issues to solve:
>
> 1. [Ctrl+V]
>    Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
>    This interface has layout issues
>
> 2. [Ctrl+V]
>    Screenshot saved to .codely-cli/clipboard/clipboard-1704096100000.png.
>    This button doesn't respond to clicks
>
> Please provide solutions respectively

Combined with Slash Commands​

> /analyze
> [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> Analyze the code structure in this screenshot

Common Questions​

Q: Why don't I see reference text after pasting an image?​

A: Possible reasons: Clipboard doesn't contain image, system performed text paste System doesn't support clipboard operations on current platform (currently only supports Windows and macOS) Image save failed (check disk space and permissions)

Q: Where are screenshots saved?​

A: By default, they are saved in the .codely-cli/clipboard/ directory under the project root. You can use relative paths to reference these files.

Q: Are temporary images automatically deleted?​

A: Yes, the system automatically cleans up temporary image files older than 1 hour. If you need to keep them long-term, manually copy them to another location.

Q: Which image formats are supported?​

A: The system supports the following formats (in priority order): PNG (recommended) JPEG TIFF GIF

Q: Can it be used on Linux?​

A: Currently, the screenshot feature only supports Windows and macOS. Linux support is planned for future versions.

Q: How do I view pasted images?​

A: The inserted text is a relative path reference. You can: Use an image viewer to open files in the .codely-cli/clipboard/ directory Let the AI model analyze the image (if the model supports multimodal) Manually move files to other locations in the project

Q: What if the text position is wrong after pasting an image?​

A: The system automatically inserts text at the cursor position and intelligently adds spaces. If the position is wrong: Use arrow keys to move the cursor to the correct position Delete text at the wrong position Paste again

Best Practices​

1. Name Screenshots for Easier Management​

Although the system automatically generates filenames, it's recommended to describe screenshot content in prompts:

> This is a screenshot of the login interface: [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> Please analyze its user experience

2. Clean Up Unneeded Screenshots​

Although the system automatically cleans up screenshots older than 1 hour, it's recommended to: Regularly check the .codely-cli/clipboard/ directory Manually delete unneeded screenshots Move important screenshots to the project's documentation directory

3. Combine with Text Descriptions​

A standalone screenshot may not be clear enough, it's recommended to combine with text descriptions:

> Please help me fix this bug:
>
> [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
>
> Error message shows "Connection timeout", occurs after clicking the "Submit" button.
> Expected behavior is to show success message and navigate to next page.

4. Use Multiple Screenshots for Comparison​

> Please compare these two design versions:
>
> Version A: [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
>
> Version B: [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096100000.png.
>
> Analyze from visual hierarchy, readability, and interaction friendliness perspectives

5. Using Screenshots in Documentation​

> I need to write documentation for the "User Registration" feature, please generate Markdown documentation based on the following content:
>
> [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
>
> Feature description: Users can register new accounts through this form, need to fill in email, password, and confirm password.
> Validation rules: Email format validation, password at least 8 characters, password entries must match.

Keyboard Shortcuts​

ShortcutDescription
Ctrl+V Alt+VPaste clipboard content. If clipboard contains image, it will be automatically saved and reference inserted
  • File references: Use @path/to/file to reference files in the project
  • Multimodal input: If AI model supports, can directly analyze image content
  • External editor: Use Ctrl+X to open external editor for complex input

Technical Limitations​

  • Platform support: Only supports Windows and macOS
  • Image formats: Depends on formats supported by system clipboard
  • Storage location: Must be within project directory, doesn't support cross-project sharing
  • File size: Limited by system clipboard and disk space
  • Concurrent operations: Rapid consecutive pasting may cause filename conflicts (mitigated by timestamp)

Troubleshooting​

Screenshot Not Saved​

Check:

  • Does clipboard really contain image (try pasting to other apps)
  • Does .codely-cli/clipboard/ directory have write permission
  • Is disk space sufficient
  • Check console error messages

File Reference Path Error​

Check:

  • Is Codely CLI running in the correct project directory
  • Has .codely-cli/clipboard/ directory been created
  • Is relative path calculation correct

No Response After Pasting​

Check:

  • Was Ctrl+V pressed correctly
  • Was paste done when input prompt has focus
  • Is there other shortcut key conflict

Reference Resources​