Skip to main content
Scratch integrates with local AI CLI tools to provide AI-powered editing capabilities. Your notes are edited locally using the Claude Code CLI or OpenAI Codex CLI - no cloud API required.

​
Overview

AI editing in Scratch:
  • Uses your local Claude Code CLI or Codex CLI installation
  • Edits notes directly based on natural language prompts
  • Runs completely locally (no data sent to Scratch servers)
  • Supports undo with Cmd+Z or Ctrl+Z
  • Works with any markdown content

​
Prerequisites

​
Claude Code CLI

To use Claude for AI editing:
  1. Install the Claude Code CLI from code.claude.com/docs/en/quickstart
  2. Restart Scratch to detect the installation
  3. Open any note and use the command palette (Cmd+P or Ctrl+P)
  4. Select Edit with Claude

​
OpenAI Codex CLI

To use Codex for AI editing:
  1. Install the OpenAI Codex CLI
  2. Restart Scratch to detect the installation
  3. Open any note and use the command palette (Cmd+P or Ctrl+P)
  4. Select Edit with Codex
Scratch automatically detects which AI CLI tools are installed when you open the AI editing modal.

​
Using AI Editing

​
Basic Workflow

  1. Open a note you want to edit
  2. Open the command palette (Cmd+P or Ctrl+P)
  3. Select Edit with Claude or Edit with Codex
  4. Enter a natural language prompt describing your desired changes
  5. Press Enter to submit
  6. Review the AI-generated changes
  7. Undo with Cmd+Z or Ctrl+Z if needed

​
Example Prompts

Make this more concise and professional

​
AI Edit Modal

The AI editing interface provides: Input Field
  • Natural language prompt entry
  • Auto-focus on open
  • Disabled if CLI not installed
Provider Detection
  • Automatic CLI availability check
  • Installation instructions if not found
  • Spinner during detection
Keyboard Shortcuts
  • Enter - Submit prompt and execute edit
  • Esc - Cancel and return to command palette
Help Text
  • Explains how the feature works
  • Links to CLI installation instructions
  • Shows active provider (Claude or Codex)

​
Response Display

After AI editing completes, Scratch displays a toast notification with:
  • Success message: “AI Edit Complete”
  • Output preview: Shows the AI’s response with markdown formatting
  • Undo instructions: Reminder that Cmd+Z or Ctrl+Z will undo changes
  • Provider icon: Visual indicator of which AI was used
The toast automatically parses markdown in the AI’s response, including:
  • Headers
  • Bold and italic text
  • Inline code
  • Code blocks
  • Bulleted lists
  • Numbered lists

​
Implementation

AI editing is implemented across multiple layers:

​
Frontend Service (src/services/ai.ts)

export async function checkClaudeCli(): Promise<boolean> {
  return invoke("ai_check_claude_cli");
}

export async function executeClaudeEdit(
  filePath: string,
  prompt: string
): Promise<AiExecutionResult> {
  return invoke("ai_execute_claude", { filePath, prompt });
}

​
UI Components

AiEditModal (src/components/ai/AiEditModal.tsx)
  • Prompt input interface
  • CLI availability detection
  • Provider-specific icons and messaging
  • Loading states during execution
  • Error handling for missing CLI
AiResponseToast (src/components/ai/AiResponseToast.tsx)
  • Response display with markdown parsing
  • Undo instructions
  • Provider branding

​
Backend Commands

The Rust backend exposes these Tauri commands:
CommandDescription
ai_check_claude_cliChecks if Claude Code CLI is installed
ai_execute_claudeExecutes Claude edit on file with prompt
ai_check_codex_cliChecks if Codex CLI is installed
ai_execute_codexExecutes Codex edit on file with prompt

​
Security & Privacy

AI editing executes local CLI commands. Ensure you trust the AI CLI tools installed on your system.
Data Flow:
  1. Your prompt and note content stay on your machine
  2. Scratch calls the local CLI tool
  3. The CLI tool may send data to Claude/OpenAI servers (per their terms)
  4. Edited content is written back to your local file
What Scratch Does NOT Do:
  • Send your notes to Scratch servers
  • Store prompts or responses
  • Track AI usage
  • Require a Scratch account or API key

​
Troubleshooting

​
CLI Not Detected

If Scratch doesn’t detect your installed CLI:
  1. Ensure the CLI is in your system PATH
  2. Restart Scratch after installation
  3. Try running the CLI command manually in a terminal
  4. Check that the CLI binary has execute permissions

​
Edit Failed

If an AI edit fails:
  1. Check your internet connection (CLIs need to reach AI servers)
  2. Verify your CLI authentication is configured
  3. Try a simpler prompt
  4. Check the CLI logs for detailed error messages

​
Changes Not Applied

If changes aren’t appearing:
  1. Check the toast notification for errors
  2. Try reloading the note (Cmd+R or Ctrl+R)
  3. Verify the file wasn’t modified by another process
  4. Check file permissions

​
Advanced Usage

​
Batch Editing

While Scratch doesn’t support batch AI editing through the UI, you can:
  1. Use the AI CLI directly on multiple files
  2. Use git to track and review changes
  3. Reload notes in Scratch to see updates

​
Custom Prompts

Create reusable prompts for common tasks:
  • “Format as weekly review with sections for wins, challenges, and next week”
  • “Convert meeting notes to action items with owners and deadlines”
  • “Generate a table of contents for this document”
  • “Extract key takeaways as a bulleted summary”

​
Integration with External Agents

Scratch detects external file changes, so you can:
  1. Use AI agents outside Scratch to edit notes
  2. Scratch will detect changes and prompt to reload
  3. Maintain full edit history via git
Combine AI editing with git integration to track all AI-generated changes and easily revert if needed.

​
Limitations

  • One note at a time (no batch editing)
  • Requires local CLI installation
  • Depends on CLI tool availability and authentication
  • No streaming or progress indication during long edits
  • Limited to providers with CLI tools (Claude Code, Codex)

​
Future Enhancements

Potential improvements being considered:
  • Support for additional AI providers
  • Batch editing across multiple notes
  • Prompt templates and history
  • Streaming responses for long edits
  • Diff preview before applying changes

Build docs developers (and LLMs) love

Get started for freeTalk to us