DiffWriter

Human-in-the-loop file writing with diff display and approval.

Installation

main.py
python
from connectonion import DiffWriter

writer = DiffWriter()

Want to customize? Run co copy diff_writer to get an editable copy.

API

write(path, content)

Write content to a file with diff display and user approval.

main.py
python
result = writer.write("hello.py", "print('hello')")
# Shows colorized diff
# Asks user to choose: 1=Yes, 2=Yes to all, 3=No + feedback
# Returns: "Wrote 15 bytes to hello.py" or feedback message

diff(path, content)

Show diff without writing (preview mode).

main.py
python
diff_text = writer.diff("hello.py", "print('hello')")
# Returns the diff string without writing

read(path)

Read file contents.

main.py
python
content = writer.read("hello.py")
# Returns: "print('hello')"

Approval Options

When a file change is proposed, user sees:

╭─── Changes to hello.py ────────────────────────╮

│ --- a/hello.py │

│ +++ b/hello.py │

│ @@ -1,2 +1,3 @@ │

│ def hello(): │

│ - pass │

│ + print("Hello!") │

╰────────────────────────────────────────────────╯

Choose an option:
  1 - Yes, apply this change
  2 - Yes to all (auto-approve for this session)
  3 - No, and tell agent what to do instead

Apply changes to hello.py? [1/2/3]:

Option	Effect
1	Apply this change, ask again for next change
2	Apply this and all future changes (session-wide)
3	Reject + provide feedback for agent to try again

Options

auto_approve

Skip approval prompts (for automation).

main.py
python
# Ask for approval (default)
writer = DiffWriter(auto_approve=False)

# Auto-approve all writes
writer = DiffWriter(auto_approve=True)

Use with Agent

main.py
python
from connectonion import Agent, DiffWriter

writer = DiffWriter()
agent = Agent("coder", tools=[writer])

agent.input("create a hello.py file with a hello world function")
# Agent calls writer.write()
# User sees diff and chooses 1, 2, or 3
# If 3: User provides feedback, agent receives it and tries again

Feedback Flow

When user chooses option 3 (reject):

User is prompted: "What should the agent do instead?"
User types feedback, e.g., "use snake_case for function names"
Agent receives: "User rejected changes to hello.py. Feedback: use snake_case for function names"
Agent can retry with the feedback

Common Use Cases

main.py
python
# Interactive coding with approval
writer = DiffWriter()
agent = Agent("coder", tools=[writer])

# CI/CD automation - skip prompts
writer = DiffWriter(auto_approve=True)
agent = Agent("automation", tools=[writer])

# Preview changes only
diff = writer.diff("config.py", new_config)
print(diff)