* What is Eddi Eddi is a conversational editor designed for seamless integration with Large Language Models (LLMs). It provides a text-based command interface that allows LLMs to perform complex code editing operations through natural language commands. Unlike traditional editors that require GUI interaction, Eddi operates entirely through a stream-based messaging protocol, making it ideal for AI-assisted development workflows. ** Key Features - Stream-based Communication: Uses NATS messaging for real-time command processing - Context-Aware: Maintains cursor position and file context across operations - Session Management: Groups related editing operations for better organization - Terse Protocol: Optimized for token efficiency when working with LLMs - Asynchronous Processing: Handles multiple commands concurrently * How does Eddi work Eddi connects to a NATS message stream and processes commands directed at it. Each command follows a structured format optimized for clarity and token efficiency. The system maintains context through sessions and cursor positioning. ** Example Workflow #+BEGIN_EXAMPLE To Eddi: Start refactor_session "Refactoring user authentication module" Eddi : Ok To Eddi: Open Create src/auth user_manager.py Eddi : Ok, At 0:0, Length 0 To Eddi: Insert Block "class UserManager:\n def __init__(self):\n self.users = {}\n" Eddi : Ok, Inserted 3 lines at 0, At 3:0 To Eddi: Show Function __init__() Eddi : Ok: At 1:4, Txt def __init__(self):\n self.users = {} To Eddi: Goto EndOfClass Eddi : Ok, At 3:0 To Eddi: Insert Method "def authenticate(self, username, password):\n # TODO: Implement authentication\n return False\n" Eddi : Ok, Inserted 3 lines at 3, At 6:0 To Eddi: Save Close user_manager.py Eddi : Ok, Bytes 156 To Eddi: Summary refactor_session Eddi : Created user_manager.py (156 bytes), Added UserManager class with __init__ and authenticate methods To Eddi: End refactor_session Eddi : Ok, Session saved #+END_EXAMPLE ** Context sensitive To prevent repeating the same parts over and over again, eddi is context sensitive. It holds a "cursor" which the user moves around. When examining the cursor is also moved. ** Terseness Since the intent of eddi is to work with LLMs terseness are needed to an extent. As few tokens as possible while still being crystal clear. Using machine code like commands, are however unnecessary as they would in best case be single tokens themselves, and in worst case require more interpretation. * Eddi's commands ** Session Management Commands *** Start [description] Initiates a new editing session for grouping related operations. **** Parameters - session_name: Unique identifier for the session - description: Optional human-readable description **** Success: Ok **** Failure: Fail "Session already exists" or Fail "Invalid session name" **** Context: Creates new session context, no file context yet *** End Terminates an editing session and saves session metadata. **** Parameters: session_name: Session to terminate **** Success: Ok, Session saved **** Failure: Fail "Session not found" **** Context: Closes all files in session, clears session context *** Summary [session_name] Provides a summary of changes made in current or specified session. **** Parameters: session_name: Optional, defaults to current session **** Success: Ok: **** Example: Ok: Modified 3 files, Added 45 lines, Deleted 12 lines, 2 functions created ** File Operations *** Open [Create] [path/] Opens an existing file or creates a new one if Create flag is used. **** Parameters - Create: Optional flag to create file if it doesn't exist - path/: Optional directory path - filename: Target file name **** Success: Ok, At :, Length **** Failure: Fail "File not found" or Fail "Permission denied" **** Context: Sets file context, cursor at 0:0 *** Save [Close] Saves the current file, optionally closing it. **** Parameters - Close: Optional flag to close after saving - filename: File to save (validates against current context) **** Success: Ok, Bytes or Ok, Saved and closed, Bytes **** Failure: Fail "No changes to save" or Fail "Write permission denied" *** Close Closes a file without saving (warns if unsaved changes exist). **** Success: Ok or Ok, Unsaved changes discarded **** Failure: Fail "File not open" *** List [Open] [pattern] Lists files in current directory or open files in session. **** Parameters - Open: Lists only currently open files - pattern: Optional glob pattern for filtering **** Success: Ok: file1.py, file2.cpp, file3.h or Ok: 3 files ** Navigation Commands *** Goto Moves cursor to specified location. **** Targets - :: Specific position - StartOfFile: Beginning of file (0:0) - EndOfFile: End of file - StartOfLine: Beginning of current line - EndOfLine: End of current line - StartOfFunction: Beginning of current function - EndOfFunction: End of current function - StartOfClass: Beginning of current class - EndOfClass: End of current class **** Success: Ok, At : **** Failure: Fail "Invalid position" or Fail "Not in function/class" *** Find [Next|Prev|All] Searches for text pattern in current file. **** Parameters - pattern: Text or regex to search for - Next/Prev: Direction from cursor (default: Next) - All: Show all matches **** Success: Ok, At : or Ok: Found 3 matches at lines 45, 67, 89 **** Failure: Fail "Not found" *** Replace [All|Confirm] Replaces text in current file. **** Parameters - All: Replace all occurrences without confirmation - Confirm: Prompt for each replacement **** Success: Ok, Replaced 3 occurrences or Ok, At :, Replace? (y/n) **** Failure: Fail "Pattern not found" ** Code Inspection *** Show [context_lines] Displays code at specified target with optional context. **** Targets - Function [(params)]: Specific function - Class : Class definition - Method .: Class method - Variable : Variable declaration/assignment - Line : Specific line number - Block :: Range of lines - Current: Current cursor position **** Parameters: context_lines: Lines before/after to include (default: 2) **** Success: Ok: At :, Txt **** Failure: Fail "Not found" or Fail "Ambiguous match" *** Analyze [type] Provides code analysis for specified target. **** Targets: Function, Class, Method, File **** Types - Dependencies: Shows imports/includes used - Complexity: Cyclomatic complexity metrics - Structure: Outline of classes/functions - Issues: Potential problems or code smells **** Success: Ok: **** Example: Ok: Function has complexity 8, uses 3 external dependencies, 2 potential issues found ** Code Modification *** Insert Inserts code at current cursor position. **** Types - Line: Single line of code - Block: Multi-line code block - Function: Complete function definition - Method: Class method - Class: Class definition - Import: Import/include statement (placed appropriately) **** Success: Ok, Inserted at , At : **** Context: Cursor moves to end of inserted content *** Delete Removes specified code element. **** Targets - Line [count]: Current or specified number of lines - Function : Entire function - Method .: Class method - Class : Entire class - Block :: Range of lines - Current: Current line **** Success: Ok, Deleted , At : **** Failure: Fail "Target not found" *** Modify Modifies existing code elements. **** Targets: Function, Method, Class, Variable **** Change Types - Rename : Rename element - AddParam : Add parameter to function - RemoveParam : Remove parameter - ChangeSignature : Modify function signature - AddDecorator : Add decorator/annotation - SetVisibility : Change access level **** Success: Ok, Modified , At : *** Refactor [parameters] Performs complex refactoring operations. **** Operations - ExtractFunction :: Extract code into function - InlineFunction : Inline function calls - MoveMethod : Move method between classes - ExtractClass : Extract methods into new class - RenameSymbol : Rename across entire codebase **** Success: Ok, Refactored , Modified files ** Semantic Refactoring Commands High-level refactoring operations that handle cross-file coordination and maintain code consistency. These commands operate at the semantic level, understanding code relationships and dependencies. *** Refactor Signature Changes function signature and updates all call sites automatically. **** Parameters - function_name: Target function to modify - new_signature: New function signature with parameters **** Success: Ok, Signature updated, callers replaced **** Failure: Fail "Function not found" or Fail "Signature conflict detected" **** Example: refactor signature example() example(param1, param2) *** Refactor Extract_Method Extracts code block into a new method and replaces duplicates. **** Parameters - method_name: Name for the new method - line_range: Lines to extract (format: start:end) **** Success: Ok, Method extracted, duplicate blocks replaced **** Failure: Fail "Invalid range" or Fail "Cannot extract - dependencies" **** Example: refactor extract_method calculateTotal lines 45:52 *** Refactor Rename_Class Renames class and updates all references across the codebase. **** Parameters - old_name: Current class name - new_name: New class name **** Success: Ok, Renamed in files, references updated **** Failure: Fail "Class not found" or Fail "Name conflict exists" **** Example: refactor rename_class UserManager AccountManager *** Refactor Move_Method . . Moves method between classes and updates callers. **** Parameters - source_class.method: Method to move - target_class.method: Destination (class must exist) **** Success: Ok, Method moved, callers updated, imports added **** Failure: Fail "Method not found" or Fail "Target class missing" **** Example: refactor move_method User.validate() UserValidator.validate() *** Refactor Inline_Variable Replaces variable with its value at all usage sites. **** Parameters: variable_name: Variable to inline **** Success: Ok, Variable inlined at locations **** Failure: Fail "Variable not found" or Fail "Cannot inline - complex usage" **** Example: refactor inline_variable temp_result *** Refactor Extract_Interface Creates interface from class and updates inheritance hierarchy. **** Parameters - class_name: Source class - interface_name: New interface name **** Success: Ok, Interface extracted, classes now implement **** Failure: Fail "Class not found" or Fail "Interface already exists" **** Example: refactor extract_interface PaymentProcessor Payable *** Refactor Split_Class Splits a class by moving specified members to a new class. **** Parameters - class_name: Source class to split - new_class_name: Name for new class - members_list: Comma-separated list of members to move **** Success: Ok, Class split, members moved, references updated **** Example: refactor split_class UserManager UserValidator validate,check_password *** Refactor Merge_Classes Merges two classes into a single class. **** Parameters - class1, class2: Classes to merge - target_name: Name for merged class **** Success: Ok, Classes merged, files updated **** Example: refactor merge_classes UserAuth UserValidator UserManager *** Refactor Change_Inheritance Changes class inheritance hierarchy. **** Parameters - class_name: Class to modify - old_parent: Current parent class - new_parent: New parent class **** Success: Ok, Inheritance changed, method calls updated **** Example: refactor change_inheritance Rectangle Shape Drawable *** Preview Shows what changes would be made without executing them. **** Parameters: refactor_command: Any refactoring command **** Success: Ok, Preview: Would modify files: , **** Example: preview refactor rename_class UserManager AccountManager ** Additional Commands *** Diff [target] Shows changes made since last save or between versions. **** Success: Ok: +15 -8 lines, 3 functions modified *** Undo [count] Undoes recent operations. **** Success: Ok, Undid *** Redo [count] Redoes previously undone operations. *** Bookmark [position] Creates named bookmarks for quick navigation. *** Comment [style] Adds comments to code elements. *** Format [target] [style] Formats code according to style guidelines. *** Validate [target] Runs syntax/semantic validation on code. *** Status Queries current context information. **** Success: Ok: Session , File , At :, * Eddi's architecture Eddi listens to a (NATS driven) line-based stream, and replies back to this stream. The architecture reflects the flow of data. It uses asyncio allowing new commands entering when it awaits the current commands. ** Communication layer Here the direct communication with NATS occur. Eddi gets invitation to streams here, and then starts to listen for messages directed at it. The raw message including sender is then sent to the Session layer. *** NATSStreamListener **** Responsibility: Manages NATS connection and message routing **** Methods - connect_to_stream(stream_name: str) -> bool - subscribe_to_subject(subject: str, callback: MessageCallback) -> Subscription - publish_response(subject: str, message: str) -> bool - handle_connection_loss() -> void *** MessageRouter **** Responsibility: Routes incoming messages to appropriate session handlers **** Methods - route_message(raw_message: RawMessage) -> SessionContext - register_session(session_id: str, handler: SessionHandler) -> void - get_active_sessions() -> List[str] *** MessageValidator **** Responsibility: Validates message format and security **** Methods - validate_message_format(message: str) -> ValidationResult - check_permissions(sender: str, command: str) -> bool - sanitize_input(raw_input: str) -> str ** Session layer The session layer contains the context of the commands. And the correct context is picked by looking at the sender. With a context, the rest of the message can be interpreted by the language layer. *** SessionManager **** Responsibility: Manages multiple editing sessions and their contexts **** Methods - create_session(session_id: str, description: str) -> SessionContext - get_session(session_id: str) -> SessionContext - end_session(session_id: str) -> SessionSummary - list_active_sessions() -> List[SessionInfo] *** SessionContext **** Responsibility: Maintains state for a single editing session **** Attributes - session_id: str - open_files: Dict[str, FileContext] - current_file: Optional[FileContext] - change_history: List[ChangeRecord] - bookmarks: Dict[str, Position] **** Methods - add_file(filename: str, file_context: FileContext) -> void - set_current_file(filename: str) -> bool - record_change(change: ChangeRecord) -> void - get_summary() -> SessionSummary *** FileContext **** Responsibility: Tracks state for individual files **** Attributes - filename: str - cursor_position: Position - content_hash: str - is_modified: bool - undo_stack: List[Operation] - redo_stack: List[Operation] **** Methods - move_cursor(position: Position) -> bool - apply_operation(op: Operation) -> OperationResult - undo_last_operation() -> bool - get_content_at(position: Position, length: int) -> str ** Language layer The message is split up into commands, and then each command is interpreted into - A service - A set of commands - containing the correct parameters. This data is then executed by the Service layer. *** CommandParser **** Responsibility: Parses natural language commands into structured operations **** Methods - parse_command(command_text: str) -> ParsedCommand - validate_syntax(command: ParsedCommand) -> ValidationResult - suggest_corrections(invalid_command: str) -> List[str] *** CommandInterpreter **** Responsibility: Converts parsed commands into service requests **** Methods - interpret_command(parsed_cmd: ParsedCommand, context: SessionContext) -> ServiceRequest - resolve_targets(target: str, context: FileContext) -> List[CodeLocation] - build_service_request(command_type: str, params: Dict) -> ServiceRequest *** ResponseFormatter **** Responsibility: Formats service responses for LLM consumption **** Methods - format_success_response(result: ServiceResult) -> str - format_error_response(error: ServiceError) -> str - format_code_display(code: str, context: DisplayContext) -> str ** Service layer The service is chosen, and the service layer uses the different ServiceClient classes to communicate with them. It receives messages when they completed and creates an answer. This answer is directed to an reply which is returned back again through the pipeline. *** ServiceDispatcher **** Responsibility: Routes requests to appropriate service clients **** Methods - dispatch_request(request: ServiceRequest) -> Future[ServiceResult] - register_service_client(service_type: str, client: ServiceClient) -> void - handle_service_response(response: ServiceResponse) -> ServiceResult *** ServiceClientFactory **** Responsibility: Creates and manages service client instances **** Methods - create_client(service_type: str, config: ServiceConfig) -> ServiceClient - get_client(service_type: str) -> ServiceClient - shutdown_all_clients() -> void ** Service clients Not really a part of eddi, but provided by the services used to edit, search and handle files. *** ServiceClient (Abstract Base) **** Responsibility: Base interface for all service interactions **** Methods - execute_request(request: ServiceRequest) -> Future[ServiceResult] - validate_request(request: ServiceRequest) -> bool - handle_error(error: Exception) -> ServiceError *** FileServiceClient **** Responsibility: Handles file I/O operations **** Methods - read_file(filename: str) -> FileContent - write_file(filename: str, content: str) -> WriteResult - create_file(filename: str) -> CreateResult - delete_file(filename: str) -> bool *** CodeAnalysisServiceClient **** Responsibility: Provides code analysis and parsing **** Methods - parse_code(content: str, language: str) -> SyntaxTree - find_symbol(symbol_name: str, tree: SyntaxTree) -> List[SymbolLocation] - analyze_complexity(function_node: ASTNode) -> ComplexityMetrics - validate_syntax(content: str, language: str) -> List[SyntaxError] *** RefactoringServiceClient **** Responsibility: Handles complex code transformations **** Methods - extract_function(code: str, range: Range, function_name: str) -> RefactorResult - rename_symbol(code: str, old_name: str, new_name: str) -> RefactorResult - inline_function(code: str, function_name: str) -> RefactorResult ** Helper Classes *** Position **** Responsibility: Represents cursor/code positions **** Attributes: line: int, column: int **** Methods: to_offset(content: str) -> int, from_offset(content: str, offset: int) -> Position *** ChangeRecord **** Responsibility: Records changes for undo/redo and session tracking **** Attributes: timestamp: datetime, operation_type: str, location: Position, old_content: str, new_content: str *** OperationResult **** Responsibility: Encapsulates results of editing operations **** Attributes: success: bool, new_position: Position, content_changed: bool, message: str * LLM Integration Assessment ** Why Context is a Strength for LLMs 1. Cognitive Load Reduction: LLMs have limited context windows and need to track enormous amounts of state when editing code. Having Eddi maintain cursor position, open files, and session state allows LLMs to focus on coding logic rather than remembering positional information. 2. Token Efficiency: Without context management, every command would need to specify full file paths, line numbers, and positioning. With context, LLMs can use terse commands like "Insert Method" instead of "Insert Method at line 45 in /src/auth/user_manager.py". 3. Natural Workflow Alignment: LLMs naturally work in focused, incremental steps. The cursor-based approach mirrors how LLMs think about code changes - identify a location, make changes there, then move to the next logical location. 4. Error Recovery: When a command fails, the context remains stable. LLMs don't lose track of where they were working, making it easier to try alternative approaches. ** Potential Context Challenges 1. Context Confusion: Risk of losing track of current context - if an LLM thinks it's in file_a.py but it's actually in file_b.py, commands could be completely wrong. 2. Multi-file Operations: When working across multiple files simultaneously (common in refactoring), context switching could become cumbersome. 3. Session Complexity: Long editing sessions might accumulate complex state that becomes hard to reason about. ** Semantic Refactoring Advantage High-level refactoring commands solve many context management challenges by operating at the semantic level: *** Cross-file Coordination Instead of breaking down complex refactoring into dozens of low-level commands across multiple files, LLMs can express intent at the semantic level. Eddi handles the coordination internally. *** Reduced Error Surface A single "refactor signature" command is far less error-prone than manually: - Finding function definition - Modifying signature - Searching for all callers - Updating each caller individually - Handling edge cases *** Transactional Semantics Refactoring commands can be all-or-nothing operations. If something fails, the entire operation rolls back rather than leaving code in an inconsistent state. *** Example Benefit #+BEGIN_EXAMPLE Traditional approach (many commands, context switching): To Eddi: Open user.py To Eddi: Find authenticate To Eddi: Modify signature... To Eddi: Open test_user.py To Eddi: Find all calls to authenticate... [Many more commands across multiple files] Semantic approach (single command): To Eddi: refactor signature authenticate(username) authenticate(username, timeout=30) Eddi : Ok, Signature updated, 12 callers replaced #+END_EXAMPLE ** Potential Challenges 1. Command Learning Curve: LLMs need to learn the specific command syntax 2. Context Switching: Managing multiple files might require careful attention to current context 3. Complex Refactoring: Some operations might require multiple commands to achieve desired results 4. Error Recovery: LLMs need strategies for handling failed operations gracefully ** Recommendations for LLM Integration 1. Command Templates: Provide LLMs with command templates for common operations 2. Context Queries: Add commands to query current context (current file, cursor position, etc.) 3. Batch Operations: Consider supporting compound commands for related operations 4. Preview Mode: Add ability to preview changes before applying them 5. Rollback Capabilities: Implement transaction-like operations for complex changes ** Overall Assessment Eddi appears to be well-designed for LLM integration. The stream-based architecture, context management, and terse protocol align well with LLM capabilities and constraints. The object-oriented design with clear separation of concerns should make it maintainable and extensible. The push-based architecture is particularly good for LLM workflows, as it allows the LLM to drive the editing process without needing to poll for state changes. The asynchronous nature also means multiple LLMs could potentially collaborate on the same codebase. ** Key success factors will be - Comprehensive documentation and examples for LLMs - Robust error handling and recovery mechanisms - Efficient context switching between files and projects - Good performance with large codebases - Semantic refactoring commands that handle cross-file operations - Context visibility tools to help LLMs understand current state - Preview capabilities for complex operations - Transactional semantics for multi-step refactoring This system could significantly enhance LLM-assisted development by providing both low-level editing capabilities and high-level semantic operations. The combination of context management for focused editing and semantic refactoring for complex operations creates a powerful interface that matches how LLMs naturally approach code modification tasks. * Eddi - Stage 2: Scripting Language Extension ** Overview Stage 2 extends Eddi from individual commands to a domain-specific language (DSL) for code editing. This evolution transforms Eddi from a "command interface" into a "code transformation language" optimized for systematic refactoring and bulk operations across codebases. ** Development Phases *** Phase 2.1: Single-line Scripting Introduction of programming constructs as single-line commands before full language implementation. **** Iteration Commands (Single-line) ***** Foreach Iterates over code elements and applies actions. ****** Targets - caller of : All call sites of a function - method in : All methods in a class - class implementing : Classes that implement interface - file matching : Files matching glob pattern - line in range : Lines in specified range - symbol of type : All symbols of given type (function, class, variable) ****** Actions - replace with : Text replacement - flag : Mark for manual review - suggest : Suggest refactoring operation - remove: Delete the element - add : Add content ****** Examples - foreach caller of authenticate() replace with authenticate($1, timeout=30) - foreach method in UserManager flag "Review complexity" - foreach file matching "test_*.py" add import logging **** Conditional Commands (Single-line) ***** If [Else ] Conditional execution based on code analysis. ****** Conditions - complexity > : Cyclomatic complexity threshold - params.count == : Parameter count - line_count > : Line count threshold - has_annotation : Presence of decorator/annotation - imports : File imports specific module - contains : Contains text pattern - unused: Element is unused ****** Examples - if complexity > 10 suggest extract_method - if params.count == 1 replace with else flag "Manual review" - if unused remove import **** Variable Commands (Single-line) ***** Let = Store code analysis results for reuse. ****** Examples - let $complex_methods = methods in UserManager where complexity > 8 - let $auth_callers = callers of authenticate() - let $test_files = files matching "test_*.py" ***** Use Apply actions to stored variables. ****** Examples - use $complex_methods suggest extract_method - use $auth_callers replace authenticate() with authenticate(timeout=30) *** Phase 2.2: Full Language Implementation Complete scripting language with blocks, control flow, and advanced constructs. **** Block Syntax Multi-line scripts enclosed in braces for complex operations. ***** Example Block Script #+BEGIN_EXAMPLE To Eddi: { let $old_methods = methods in UserManager where complexity > 8 foreach $method in $old_methods { extract_method($method, "Extracted" + $method.name) } foreach caller of UserManager.new() { replace with AccountManager.new() } rename_class UserManager LegacyUserManager } Eddi: Ok, Script completed: 5 methods extracted, 23 callers updated, class renamed #+END_EXAMPLE **** Advanced Language Features ***** Changeset Management ****** Collect Changes As Groups operations into named changesets for batch application. ****** Apply Changeset Executes all operations in a changeset. ****** Rollback Changeset Undoes all operations in a changeset. ****** Preview Changeset Shows what would change without executing. ***** Context Management ****** Store Current_Position As Saves current cursor position. ****** Goto Returns to saved position. ****** Push Context / Pop Context Context stack for nested operations. ***** Error Handling ****** Try { ... } Catch { ... } Exception handling for script execution. ****** On_Error Default error handling strategy. **** Complex Scripting Examples ***** Systematic Code Migration #+BEGIN_EXAMPLE To Eddi: { foreach file matching "src/**/*.py" { replace "from old_auth import" with "from new_auth import" foreach call to old_auth.login { replace with new_auth.authenticate } } collect changes as "auth_migration" } Eddi: Ok, Migration prepared: 45 files affected, use 'apply changeset auth_migration' #+END_EXAMPLE ***** Code Quality Cleanup #+BEGIN_EXAMPLE To Eddi: { foreach file matching "*.py" { foreach function where line_count > 50 { flag "Consider splitting: " + function.name } foreach import where unused { remove import } if imports logging and not contains "logger =" { add line "logger = logging.getLogger(__name__)" } } } Eddi: Ok, 15 functions flagged, 8 unused imports removed, 12 loggers added #+END_EXAMPLE ***** Refactoring Workflow #+BEGIN_EXAMPLE To Eddi: { let $target_class = class UserManager let $complex_methods = methods in $target_class where complexity > 10 try { foreach $method in $complex_methods { extract_method($method, $method.name + "_extracted") } foreach caller of $target_class { if file.path contains "test_" { flag "Update test: " + caller.location } else { replace UserManager with AccountManager } } rename_class UserManager LegacyUserManager collect changes as "user_manager_refactor" } catch { rollback all flag "Refactoring failed, manual intervention needed" } } #+END_EXAMPLE ** Language Architecture Extensions *** Script Parser **** Responsibility: Parses DSL syntax into abstract syntax trees **** Methods - parse_script(script_text: str) -> ScriptAST - validate_syntax(ast: ScriptAST) -> ValidationResult - optimize_script(ast: ScriptAST) -> OptimizedAST *** Script Executor **** Responsibility: Executes parsed scripts with proper scoping and error handling **** Methods - execute_script(ast: ScriptAST, context: ExecutionContext) -> ExecutionResult - manage_variables(scope: VariableScope) -> void - handle_control_flow(node: ControlFlowNode) -> FlowResult *** Changeset Manager **** Responsibility: Manages transaction-like operations for script execution **** Methods - create_changeset(name: str) -> ChangesetId - add_operation(changeset: ChangesetId, op: Operation) -> void - apply_changeset(changeset: ChangesetId) -> ApplicationResult - rollback_changeset(changeset: ChangesetId) -> RollbackResult *** Code Query Engine **** Responsibility: Provides advanced code analysis for DSL conditions and iterations **** Methods - find_elements(query: CodeQuery, scope: AnalysisScope) -> List[CodeElement] - evaluate_condition(condition: Condition, element: CodeElement) -> bool - analyze_dependencies(element: CodeElement) -> DependencyGraph ** Benefits for LLM Integration *** Declarative Programming Model LLMs can express intent at a high level rather than managing step-by-step execution. The scripting language handles context switching, error recovery, and consistency automatically. *** Bulk Operations Perfect for systematic changes across large codebases without losing track of context. Single scripts can handle complex refactoring that would require hundreds of individual commands. *** Reduced Cognitive Load LLMs think in terms of code relationships and transformations rather than file navigation and cursor management. The language abstracts away low-level details. *** Composability and Reusability Complex refactoring becomes composition of simpler language constructs. Scripts can be stored, modified, and reused across similar projects. *** Safety Through Abstraction Changeset management provides transactional semantics - scripts either complete successfully or rollback cleanly. Preview mode allows validation before execution. ** Implementation Strategy *** Stage 2.1 Implementation 1. Extend command parser to handle foreach/if/let syntax 2. Add code analysis capabilities for conditions and iterations 3. Implement variable storage and retrieval 4. Create single-line script execution pipeline *** Stage 2.2 Implementation 1. Develop full script parser with block syntax 2. Implement changeset management system 3. Add advanced control flow (try/catch, loops) 4. Create script optimization and validation systems 5. Build comprehensive code query engine This staged approach allows gradual adoption - Stage 1 users can continue with individual commands while Stage 2 enables powerful scripting capabilities for complex refactoring workflows. * Eddi Development Plan - Phase Implementation ** Project Overview Eddi is a conversational code editor designed for LLM integration, progressing through three phases: - Phase 1: Core command-based editor with NATS messaging - Phase 2: Python-based scripting API with advanced refactoring - Phase 3: Full IDE integration and ecosystem ** Development Phases *** Phase 1: Core Eddi Implementation **** Task 1.1: Communication Layer Foundation ***** Objective: Implement NATS-based messaging infrastructure ***** Prerequisites: None ***** Protocol information ****** Connection to the service: Client sending example: The name of the message is mizuki.eddi.connection_request { "message_type": "connection_request", "sender": { "id": "claude-4-sonnet-20250514", "type": "llm", "client_info": { "name": "Claude", "version": "4.0", "capabilities": ["code_analysis", "refactoring", "python_scripting"] } }, "stream_name": "claude.eddi.code_editing", "eddispeak_version": "2.0", "requested_features": { "basic_commands": ["2.0", "mandatory"], "python_api": ["1.0", "optional"], "semantic_refactoring": ["1.0", "optional"], "changeset_management": ["1.0", "optional"] ], "session_preferences": { "response_format": "terse", "error_handling": "detailed", "preview_mode": true }, "timestamp": "2025-08-02T14:30:00Z", "connection_id": "conn_claude_20250802_143000" } ****** Reply to client: { "message_type": "connection_response", "status": "accepted", "stream_id": "claude.eddi.code_editing", "available_features": {"basic_commands":"2.0", "python_api":"1.0", "semantic_refactoring":"1.1"}, "server_info": { "eddi_version": "2.1.0", "supported_eddispeak": ["1.0", "2.0"], "max_concurrent_operations": 10 }, "connection_established": "2025-08-02T14:30:01Z" } ***** Deliverables - NATSStreamListener class with connection management - Need a listen method, setting it up to receive requests for connection. - When request is received - make sure that it support same version of eddispeak - check with router if session exists - reconnect if it does - if it doesn't exist, create a session with the message router. - check with service manager if it supports feaures requested - make the whole handling conncurrency safe. We only handle one connection at a time. - request connection to stream by sending nats message: mizuki.stream.open and json content {"name":, "msg_type":"stream_open", "whitelist_recipient":"eddi", "user":"eddi"} then updates will come on mizuki.stream.update with the message in {"appended":, "from":, "to":"eddi"} - Every append text message should be sent to the message router, if the message validator approves it. - SessionContext, an empty class for now. - MessageRouter class for session-based routing - needs functions to add, and check if a stream exist. - need a function to route messages. - this message should check with SessionManager (dummy class) if session exist. - if no session exist pass it directly to CommandParser.session_command(message, session_manager) - this can throw, a NotSessionCommand and we should then return a failure: No session exist and this is not a session command. - MessageValidator class for input sanitization and security - Basic error handling and reconnection logic - Create a own unit that reports error to the log. To prevent mess. - The other units can just report errors as if the error reporting module exists. - Then the error module functions can be built on the needs of the rest of the units. - The reconnection handling should be in the main loop. - It should test the StreamListener at intervals. - Main Eddi class with main loop and creation of the current deliverables. - add also a SessionManager class that is empty and can receive - Run function that starts Eddi. ***** Acceptance Criteria - Can connect to NATS server and maintain persistent connection - Routes messages to correct handlers based on sender ID - Validates message format and rejects malformed inputs - Handles connection drops gracefully with automatic reconnection ***** Estimated Complexity: Medium ***** Dependencies: NATS client library, asyncio **** Task 1.2: Session Management System ***** Objective: Implement session lifecycle and context management ***** Prerequisites: Task 1.1 (Communication Layer) ***** Deliverables - SessionManager class for multiple session coordination - On init, - create a command parser (CommandParser) - create a service manager ServiceManager (create a fake one for the moment) - When crete session is called, the manager must make sure that - The session name isn't taken - The user doesn't already have a session running - Receiver should be the session manager (check name) - When create session is called it should - create a SessionContext - connect sender and session_name and session contex. - When has_session check that the user already has a session running. - If the message is a create session (ask the command_parser.session_command(message, self)) - Then the check can be done again. If there still are no session, fil. - Route to session should: - send the message to the command parser parse_message(message) - From parse_messages the session should get a set of commands (one or many). - Each command should be run like this command.run(service_manager, session_context) - When error occurs, it uses the ErrorReporter.report_exception(context, exception) - Has session checks the message for a session id - SessionContext class for individual session state - SessionContext will keep track of files open. The current file and their cursors. - SessionContext will be able to run actions. - FileContext class for per-file state tracking ***** Acceptance Criteria - Can create, manage, and terminate multiple concurrent sessions - Maintains cursor position and file state across operations - Provides session summaries and change tracking - Recovers session state after system restart ***** Estimated Complexity: High ***** Dependencies: Task 1.1, file system access, state serialization **** Task 1.3: Basic Command Parser ***** Objective: Parse and validate core editing commands ***** Prerequisites: Task 1.2 (Session Management) ***** Deliverables - CommandParser class for syntax analysis - Command validation and error reporting - Support for basic commands: Start, End, Open, Save, Close, Show, Goto - Response formatting for consistent output ***** Acceptance Criteria - Parses all basic commands with parameter validation - Provides clear error messages for invalid syntax - Formats responses consistently for LLM consumption - Handles edge cases and malformed commands gracefully ***** Estimated Complexity: Medium ***** Dependencies: Task 1.2, regex/parsing libraries **** Task 1.4: File Operations Service ***** Objective: Implement core file I/O and manipulation ***** Prerequisites: Task 1.3 (Command Parser) ***** Deliverables - FileServiceClient class for file operations - Support for Open, Save, Close, Create operations - File content management and change tracking - Permission handling and error recovery ***** Acceptance Criteria - Can open, read, write, and close files reliably - Tracks file modifications and provides change detection - Handles file permissions and access errors appropriately - Supports concurrent file access across sessions ***** Estimated Complexity: Medium ***** Dependencies: Task 1.3, file system libraries, async I/O **** Task 1.5: Navigation and Search ***** Objective: Implement cursor movement and text search functionality ***** Prerequisites: Task 1.4 (File Operations) ***** Deliverables - Navigation commands: Goto, Find, Replace - Cursor position management and validation - Text search with regex support - Context-aware positioning (functions, classes, etc.) ***** Acceptance Criteria - Accurate cursor positioning with line:column addressing - Fast text search with pattern matching - Replace operations with confirmation options - Smart navigation to code structures ***** Estimated Complexity: Medium ***** Dependencies: Task 1.4, regex libraries, code parsing **** Task 1.6: Basic Code Inspection ***** Objective: Implement Show commands for code viewing ***** Prerequisites: Task 1.5 (Navigation and Search) ***** Deliverables - Code analysis for function/class detection - Show commands with context lines - Syntax highlighting preparation (structure identification) - Code structure parsing foundation ***** Acceptance Criteria - Can identify and display functions, classes, and methods - Provides configurable context around displayed code - Handles various programming languages consistently - Maintains cursor position during inspection ***** Estimated Complexity: High ***** Dependencies: Task 1.5, language parsers (tree-sitter or similar) **** Task 1.7: Basic Code Modification ***** Objective: Implement Insert, Delete, and Modify commands ***** Prerequisites: Task 1.6 (Code Inspection) ***** Deliverables - Insert operations: Line, Block, Function, Method, Class - Delete operations with target specification - Basic modification commands - Undo/redo functionality ***** Acceptance Criteria - Can insert code at cursor or specified locations - Safely deletes code elements with validation - Maintains undo history for error recovery - Updates cursor position after modifications ***** Estimated Complexity: High ***** Dependencies: Task 1.6, code structure analysis **** Task 1.8: Integration Testing and Documentation ***** Objective: Complete Phase 1 with comprehensive testing ***** Prerequisites: Tasks 1.1-1.7 (All Phase 1 components) ***** Deliverables - End-to-end integration tests - LLM interaction examples and workflows - Performance benchmarking and optimization - Complete API documentation for Phase 1 commands ***** Acceptance Criteria - All basic commands work reliably in integration tests - Performance meets requirements for typical file sizes - Documentation enables LLM developers to use Eddi effectively - System handles error conditions gracefully ***** Estimated Complexity: Medium ***** Dependencies: All Phase 1 tasks, testing frameworks *** Phase 2: Python API and Advanced Refactoring **** Task 2.1: Python API Foundation ***** Objective: Design and implement core Python API for Eddi ***** Prerequisites: Phase 1 Complete ***** Deliverables - Core eddi Python module with session management - File and class representation objects - Method chaining API for fluent operations - Connection layer between Python API and Eddi core ***** Acceptance Criteria - Can import eddi and start sessions from Python - Provides intuitive object model for code elements - Maintains connection to Eddi core service - Supports both synchronous and asynchronous operations ***** Estimated Complexity: High ***** Dependencies: Phase 1, Python packaging, IPC mechanisms **** Task 2.2: Code Analysis Engine ***** Objective: Advanced code parsing and analysis capabilities ***** Prerequisites: Task 2.1 (Python API Foundation) ***** Deliverables - CodeAnalysisServiceClient with AST parsing - Symbol resolution and dependency tracking - Complexity analysis and code metrics - Cross-reference analysis (callers, references, etc.) ***** Acceptance Criteria - Can parse and analyze code in multiple languages - Provides accurate symbol resolution and call graphs - Calculates meaningful code complexity metrics - Efficiently handles large codebases ***** Estimated Complexity: Very High ***** Dependencies: Task 2.1, tree-sitter, language servers, AST libraries **** Task 2.3: Basic Refactoring Operations ***** Objective: Implement core refactoring functionality ***** Prerequisites: Task 2.2 (Code Analysis Engine) ***** Deliverables - RefactoringServiceClient with core operations - Rename operations (symbols, classes, methods) - Extract method and inline method operations - Move method between classes - Signature change with caller updates ***** Acceptance Criteria - Can perform safe renames across entire codebase - Extracts methods while maintaining functionality - Updates all callers when signatures change - Preserves code semantics during refactoring ***** Estimated Complexity: Very High ***** Dependencies: Task 2.2, language-specific refactoring tools **** Task 2.4: Python Iteration API ***** Objective: Implement Python-based iteration over code elements ***** Prerequisites: Task 2.3 (Basic Refactoring) ***** Deliverables - Iterator classes for files, classes, methods, calls - Filtering and querying capabilities - Condition evaluation system - Integration with core refactoring operations ***** Acceptance Criteria - Can iterate over code elements with Python for loops - Supports complex filtering conditions - Integrates seamlessly with refactoring operations - Performance suitable for large codebases ***** Estimated Complexity: High ***** Dependencies: Task 2.3, Python iterator protocols **** Task 2.5: Changeset Management ***** Objective: Implement transactional operations and rollback ***** Prerequisites: Task 2.4 (Python Iteration API) ***** Deliverables - Changeset system with transaction semantics - Preview capabilities for complex operations - Rollback and recovery mechanisms - Batch operation optimization ***** Acceptance Criteria - Can group operations into atomic transactions - Provides detailed previews before execution - Reliable rollback on failure or user request - Optimizes batch operations for performance ***** Estimated Complexity: High ***** Dependencies: Task 2.4, database-like transaction systems **** Task 2.6: Advanced Refactoring Operations ***** Objective: Complex refactoring with cross-file coordination ***** Prerequisites: Task 2.5 (Changeset Management) ***** Deliverables - Extract interface and split class operations - Inheritance hierarchy modifications - Large-scale code migrations - Template-based code generation ***** Acceptance Criteria - Can perform complex refactoring across multiple files - Maintains code correctness during large transformations - Provides rollback for failed complex operations - Handles edge cases and conflicts gracefully ***** Estimated Complexity: Very High ***** Dependencies: Task 2.5, advanced static analysis tools **** Task 2.7: Python Script Execution Engine ***** Objective: Execute Python scripts with Eddi API integration ***** Prerequisites: Task 2.6 (Advanced Refactoring) ***** Deliverables - Python script execution environment - Security sandboxing for untrusted scripts - Interactive Python shell integration - Script debugging and error reporting ***** Acceptance Criteria - Can execute Python scripts safely with Eddi API access - Provides secure execution environment - Supports interactive development and debugging - Clear error reporting and stack traces ***** Estimated Complexity: High ***** Dependencies: Task 2.6, Python execution security, sandboxing **** Task 2.8: Phase 2 Integration and Testing ***** Objective: Complete Python API with comprehensive testing ***** Prerequisites: Tasks 2.1-2.7 (All Phase 2 components) ***** Deliverables - Comprehensive test suite for Python API - LLM integration examples and workflows - Performance optimization for complex operations - Complete Python API documentation ***** Acceptance Criteria - All Python API functions work reliably in tests - Complex refactoring scripts execute successfully - Performance acceptable for real-world codebases - Documentation enables effective LLM usage ***** Estimated Complexity: Medium ***** Dependencies: All Phase 2 tasks, advanced testing frameworks *** Phase 3: IDE Integration and Ecosystem **** Task 3.1: IDE Plugin Architecture ***** Objective: Design plugin system for popular IDEs ***** Prerequisites: Phase 2 Complete ***** Deliverables - Plugin architecture specification - VS Code extension foundation - IntelliJ plugin foundation - Emacs integration layer ***** Acceptance Criteria - Consistent plugin API across IDE platforms - Basic Eddi integration in target IDEs - Maintains performance within IDE constraints - User experience consistent with IDE conventions ***** Estimated Complexity: High ***** Dependencies: Phase 2, IDE SDK knowledge, plugin frameworks **** Task 3.2: Language Server Protocol Integration ***** Objective: Integrate with LSP for enhanced language support ***** Prerequisites: Task 3.1 (IDE Plugin Architecture) ***** Deliverables - LSP client integration for enhanced code analysis - Multiple language server coordination - Semantic analysis improvements - Cross-language refactoring support ***** Acceptance Criteria - Leverages existing language servers for analysis - Supports refactoring across multiple languages - Maintains responsiveness with LSP integration - Provides enhanced semantic understanding ***** Estimated Complexity: Very High ***** Dependencies: Task 3.1, LSP specification, language servers **** Task 3.3: Web Interface and Remote Access ***** Objective: Browser-based interface for remote Eddi usage ***** Prerequisites: Task 3.2 (LSP Integration) ***** Deliverables - Web-based Eddi interface - Real-time collaboration features - Remote session management - Cloud deployment capabilities ***** Acceptance Criteria - Full Eddi functionality available via web browser - Multiple users can collaborate on same codebase - Secure remote access with authentication - Scalable cloud deployment options ***** Estimated Complexity: Very High ***** Dependencies: Task 3.2, web frameworks, real-time communication **** Task 3.4: Enterprise Features ***** Objective: Enterprise-grade features for large organizations ***** Prerequisites: Task 3.3 (Web Interface) ***** Deliverables - Multi-tenant architecture - Audit logging and compliance features - Integration with enterprise authentication - Large codebase optimization ***** Acceptance Criteria - Supports multiple organizations with isolation - Comprehensive audit trail for all operations - Integrates with LDAP/SAML/OAuth systems - Handles enterprise-scale codebases efficiently ***** Estimated Complexity: High ***** Dependencies: Task 3.3, enterprise security systems ** Task Assignment Guidelines *** Task Complexity Levels - Low: 1-3 days for experienced developer - Medium: 1-2 weeks for experienced developer - High: 2-4 weeks for experienced developer - Very High: 1-2 months for experienced developer *** LLM Coder Assignment Strategy **** Phase 1 Tasks (Foundation) - Assign tasks 1.1-1.3 to establish core architecture - Tasks 1.4-1.7 can be parallelized once core is stable - Task 1.8 requires human oversight for integration testing **** Phase 2 Tasks (Python API) - Task 2.1-2.2 require sequential completion (foundation → analysis) - Tasks 2.3-2.6 can be partially parallelized with careful coordination - Tasks 2.7-2.8 require integration focus **** Phase 3 Tasks (Ecosystem) - All tasks require Phase 2 completion - Tasks 3.1-3.2 can be parallelized by IDE platform - Tasks 3.3-3.4 build on each other sequentially *** Success Criteria per Phase **** Phase 1 Success - LLM can perform basic file editing through Eddi commands - System handles multiple concurrent sessions reliably - Core command set works across common programming languages **** Phase 2 Success - LLM can write Python scripts for complex refactoring - System handles large-scale code transformations safely - Performance suitable for medium-sized projects (10K-100K lines) **** Phase 3 Success - Eddi integrates seamlessly with popular development environments - Supports enterprise deployment and collaboration - Performance suitable for large-scale projects (100K+ lines) ** Dependencies and Prerequisites *** External Dependencies - NATS server for messaging - Tree-sitter or similar for code parsing - Language servers for enhanced analysis - Database for session persistence - Security frameworks for sandboxing *** Hardware Requirements - Development: Standard development machine - Testing: Multi-core system for parallel test execution - Production: Scalable based on concurrent users and codebase size *** Team Prerequisites - Strong Python and asyncio experience - Understanding of compiler/parser technology - Experience with code analysis tools - Knowledge of IDE plugin development (Phase 3) - LLM integration experience preferred This development plan provides a structured approach to building Eddi incrementally, with clear task boundaries suitable for LLM-assisted development while maintaining architectural coherence across phases.