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 <session_name> [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 <n> already exists” or Fail “Invalid session name”¶
Context: Creates new session context, no file context yet¶
End <session_name>¶
Terminates an editing session and saves session metadata.
Parameters: session_name: Session to terminate¶
Success: Ok, Session saved¶
Failure: Fail “Session <n> 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: <change_summary>¶
Example: Ok: Modified 3 files, Added 45 lines, Deleted 12 lines, 2 functions created¶
File Operations¶
Open [Create] [path/] <filename>¶
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 <line>:<col>, Length <bytes>¶
Failure: Fail “File not found” or Fail “Permission denied”¶
Context: Sets file context, cursor at 0:0¶
Save [Close] <filename>¶
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 <size> or Ok, Saved and closed, Bytes <size>¶
Failure: Fail “No changes to save” or Fail “Write permission denied”¶
Close <filename>¶
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¶
Code Inspection¶
Show <target> [context_lines]¶
Displays code at specified target with optional context.
Targets¶
Function <n>[(params)]: Specific function
Class <n>: Class definition
Method <class>.<method>: Class method
Variable <n>: Variable declaration/assignment
Line <number>: Specific line number
Block <start_line>:<end_line>: Range of lines
Current: Current cursor position
Parameters: context_lines: Lines before/after to include (default: 2)¶
Success: Ok: At <line>:<col>, Txt <code_content>¶
Failure: Fail “Not found” or Fail “Ambiguous match”¶
Analyze <target> [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: <analysis_result>¶
Example: Ok: Function has complexity 8, uses 3 external dependencies, 2 potential issues found¶
Code Modification¶
Insert <type> <content>¶
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 <chars/lines> at <line>, At <new_line>:<col>¶
Context: Cursor moves to end of inserted content¶
Delete <target>¶
Removes specified code element.
Targets¶
Line [count]: Current or specified number of lines
Function <n>: Entire function
Method <class>.<method>: Class method
Class <n>: Entire class
Block <start>:<end>: Range of lines
Current: Current line
Success: Ok, Deleted <description>, At <line>:<col>¶
Failure: Fail “Target not found”¶
Modify <target> <change_type> <content>¶
Modifies existing code elements.
Targets: Function, Method, Class, Variable¶
Change Types¶
Rename <new_name>: Rename element
AddParam <param_def>: Add parameter to function
RemoveParam <param_name>: Remove parameter
ChangeSignature <new_signature>: Modify function signature
AddDecorator <decorator>: Add decorator/annotation
SetVisibility <public|private|protected>: Change access level
Success: Ok, Modified <target>, At <line>:<col>¶
Refactor <operation> <target> [parameters]¶
Performs complex refactoring operations.
Operations¶
ExtractFunction <n> <start_line>:<end_line>: Extract code into function
InlineFunction <n>: Inline function calls
MoveMethod <from_class> <to_class> <method>: Move method between classes
ExtractClass <n> <methods_list>: Extract methods into new class
RenameSymbol <old_name> <new_name>: Rename across entire codebase
Success: Ok, Refactored <description>, Modified <file_count> 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 <function_name> <new_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, <n> callers replaced¶
Failure: Fail “Function not found” or Fail “Signature conflict detected”¶
Example: refactor signature example() example(param1, param2)¶
Refactor Extract_Method <method_name> <line_range>¶
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, <n> duplicate blocks replaced¶
Failure: Fail “Invalid range” or Fail “Cannot extract - dependencies”¶
Example: refactor extract_method calculateTotal lines 45:52¶
Refactor Rename_Class <old_name> <new_name>¶
Renames class and updates all references across the codebase.
Parameters¶
old_name: Current class name
new_name: New class name
Success: Ok, Renamed in <n> files, <n> references updated¶
Failure: Fail “Class not found” or Fail “Name conflict exists”¶
Example: refactor rename_class UserManager AccountManager¶
Refactor Move_Method <source_class>.<method> <target_class>.<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, <n> 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 <variable_name>¶
Replaces variable with its value at all usage sites.
Parameters: variable_name: Variable to inline¶
Success: Ok, Variable inlined at <n> locations¶
Failure: Fail “Variable not found” or Fail “Cannot inline - complex usage”¶
Example: refactor inline_variable temp_result¶
Refactor Extract_Interface <class_name> <interface_name>¶
Creates interface from class and updates inheritance hierarchy.
Parameters¶
class_name: Source class
interface_name: New interface name
Success: Ok, Interface extracted, <n> classes now implement <interface>¶
Failure: Fail “Class not found” or Fail “Interface already exists”¶
Example: refactor extract_interface PaymentProcessor Payable¶
Refactor Split_Class <class_name> <new_class_name> <members_list>¶
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, <n> members moved, <n> references updated¶
Example: refactor split_class UserManager UserValidator validate,check_password¶
Refactor Merge_Classes <class1> <class2> <target_name>¶
Merges two classes into a single class.
Parameters¶
class1, class2: Classes to merge
target_name: Name for merged class
Success: Ok, Classes merged, <n> files updated¶
Example: refactor merge_classes UserAuth UserValidator UserManager¶
Refactor Change_Inheritance <class_name> <old_parent> <new_parent>¶
Changes class inheritance hierarchy.
Parameters¶
class_name: Class to modify
old_parent: Current parent class
new_parent: New parent class
Success: Ok, Inheritance changed, <n> method calls updated¶
Example: refactor change_inheritance Rectangle Shape Drawable¶
Preview <refactor_command>¶
Shows what changes would be made without executing them.
Parameters: refactor_command: Any refactoring command¶
Success: Ok, Preview: Would modify <n> files: <file_list>, <change_summary>¶
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 <operation_description>¶
Redo [count]¶
Redoes previously undone operations.
Bookmark <n> [position]¶
Creates named bookmarks for quick navigation.
Comment <target> [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 <name>, File <filename>, At <line>:<col>, <modified_status>¶
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 srcauth/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 <target> <action>¶
Iterates over code elements and applies actions.
Targets¶
caller of <function>: All call sites of a function
method in <class>: All methods in a class
class implementing <interface>: Classes that implement interface
file matching <pattern>: Files matching glob pattern
line in range <start:end>: Lines in specified range
symbol of type <type>: All symbols of given type (function, class, variable)
Actions¶
replace <old> with <new>: Text replacement
flag <message>: Mark for manual review
suggest <refactoring>: Suggest refactoring operation
remove: Delete the element
add <content>: 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 <condition> <action> [Else <action>]¶
Conditional execution based on code analysis.
Conditions¶
complexity > <n>: Cyclomatic complexity threshold
params.count == <n>: Parameter count
line_count > <n>: Line count threshold
has_annotation <annotation>: Presence of decorator/annotation
imports <module>: File imports specific module
contains <pattern>: Contains text pattern
unused: Element is unused
Examples¶
if complexity > 10 suggest extract_method
if params.count == 1 replace with <new_signature> else flag “Manual review”
if unused remove import
Variable Commands (Single-line)¶
Let <variable> = <expression>¶
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 <variable> <action>¶
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 <changeset_name>¶
Groups operations into named changesets for batch application.
Apply Changeset <name>¶
Executes all operations in a changeset.
Rollback Changeset <name>¶
Undoes all operations in a changeset.
Preview Changeset <name>¶
Shows what would change without executing.
Context Management¶
Store Current_Position As <bookmark>¶
Saves current cursor position.
Goto <bookmark>¶
Returns to saved position.
Push Context / Pop Context¶
Context stack for nested operations.
Error Handling¶
Try { … } Catch { … }¶
Exception handling for script execution.
On_Error <action>¶
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 foreachiflet 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”:<stream_name>, “msg_type”:”stream_open”, “whitelist_recipient”:”eddi”, “user”:”eddi”}
then updates will come on mizuki.stream.update with the message in {“appended”:<text>, “from”:<connection_id>, “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.6: Basic Code Inspection¶
Objective: Implement Show commands for code viewing¶
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 LDAPSAMLOAuth 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.