claude-edit

A CLI wrapper for the Claude Agent SDK that enables running autonomous edit plans with real-time streaming feedback.

Features

• 🚀 Real-time Streaming - Watch responses appear as they're generated
• 📝 Markdown Plans - Execute complex editing tasks via structured plans
• 🛠️ Live Tool Execution - See file operations, bash commands, and other tools in real-time
• 📊 Session Tracking - Clear session information and usage metrics
• 🎯 Streamlined Interface - Simple stdin-first design with minimal flags
• 🔄 Multiple Output Modes - Streaming, traditional summary, or JSON automation

Quick Start

Installation

# Clone and install
git clone https://github.com/cperion/claude-edit.git
cd claude-edit
bun install
bun link  # Install locally

# Or add to your project
bun add claude-edit

Basic Usage

# From file (recommended)
claude-edit < your-plan.md

# From pipe
echo "Fix the login button validation" | claude-edit

# From argument
claude-edit "Add error handling to API endpoints"

# Traditional summary output
claude-edit < plan.md --no-stream

# JSON automation
claude-edit < plan.md --json

Usage Examples

Simple Fix

# Create plan.md
cat > plan.md << EOF
# Fix Login Button Validation

## What needs to be done
Login button stays disabled after email validation passes

## Current situation
- File: src/LoginForm.tsx
- Line 46: isDisabled checks both email AND password validation
- Should only check email validation

## Changes to make
- Line 46: Remove password validation from isDisabled calculation

## Validation
- npm test should pass
- npm run build should succeed
EOF

# Execute
claude-edit < plan.md

Complex Refactoring

claude-edit < refactor-plan.md --timeout 300000

Plan Format

Claude-edit uses markdown plans to specify what changes to make. The format is flexible:

Simple Format

# [Task Title]: Brief Description

## What needs to be done
[Clear description of the goal]

## Current situation
[What you found - relevant files, patterns, issues]

## Changes to make
[Be specific about files and modifications]

## Validation
[How to verify it works]

Detailed Format

# [Task Title]

## Overview
[Brief summary]

## Current State
[Key findings about existing code]

## Implementation
1. Discovery: Find/analyze files using Grep/Glob
2. Changes: Create/modify files with specific instructions
3. Validation: Test/build commands and expected results

## Error Handling
[What to do if things go wrong]

Output Modes

Real-time Streaming (Default)

Conversation Summary
session: 12345678-1234-1234-1234-123456789abc
model: claude-3-7-sonnet-20250219

assistant:
I'll help you refactor the authentication system...

tool_use: Read (call_abc123)
tool_result: Read (call_abc123) Found 3 auth-related files...

tool_use: Edit (call_def456)
tool_result: Edit (call_def456) Updated auth service with new methods...

Result: success • turns: 5 • cost: $0.12
Authentication system refactored successfully!

Traditional Summary (--no-stream)

Conversation Summary
session: 12345678-1234-1234-1234-123456789abc
model: claude-3-7-sonnet-20250219

[1] user:
Refactor the authentication system...

[2] assistant:
I'll help you refactor the authentication system...

[3] tool_use: Read (call_abc123)
Found 3 auth-related files...

[4] result: success
Authentication system refactored successfully!

JSON Mode (--json)

{"event":"start","options":{"cwd":"/project","maxTurns":30,...}}
{"event":"message","data":{"type":"assistant","message":{"content":[...]}}}
{"event":"end"}

Options

Options:
      --max-turns <n>       Max agent turns (default: 30)
      --timeout <ms>        Overall timeout in ms
      --cwd <path>          Working directory (default: current)
      --model <m>           Model id (e.g. claude-3-7-sonnet, custom)
      --settings <s>        Settings: user|project|local|all|none (default: project)
      --json                Emit JSON events
      --show-diff           Show diffs (placeholder in MVP)
      --no-stream           Disable real-time streaming (default: streaming enabled)
      --ai-help             Print AI integration help and exit
      --permission-mode <m> default|acceptEdits|bypassPermissions|plan (default: bypassPermissions)
  -h, --help                Show help

Configuration

Settings File

Create ~/.claude-edit/settings.json:

{
  "apiKey": "sk-ant-...",
  "apiUrl": "https://api.anthropic.com",
  "model": "claude-3-7-sonnet-20250219",
  "env": {
    "ANTHROPIC_MODEL": "claude-3-7-sonnet-20250219",
    "HTTP_PROXY": "http://proxy:8080"
  }
}

Environment Variables

export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_API_URL="https://api.anthropic.com"

Agent Integration

Perfect for integration with AI agents and automation workflows:

# Agent creates plan
agent-code-review > review-plan.md

# Execute fixes
claude-edit < review-plan.md

# Process results
if [ $? -eq 0 ]; then
  echo "Review fixes completed successfully"
else
  echo "Review fixes failed, check output"
fi

Development

# Clone repository
git clone https://github.com/cperion/claude-edit.git
cd claude-edit

# Install dependencies
bun install

# Run locally
bun run src/cli.ts --help

# Link for development
bun link

# Run tests
bun test

Architecture

• TypeScript/Bun runtime for optimal performance
• Claude Agent SDK integration for powerful agent capabilities
• Real-time streaming with includePartialMessages
• Tool ecosystem: Read, Write, Edit, Bash, Grep, Glob, and more
• Permission system: Fine-grained control over agent capabilities

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

• 📖 AI Integration Help: claude-edit --ai-help
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Built with ❤️ for the Claude developer community