Code Editing

PraisonAI provides a powerful code editing module for AI-powered code manipulation, inspired by Kilo Code’s architecture.

Installation

The code editing module is included with PraisonAI:

pip install praisonai

Quick Start

from praisonai.code import (
    set_workspace,
    code_read_file,
    code_write_file,
    code_apply_diff,
    code_execute_command,
    CODE_TOOLS
)

# Set the workspace directory
set_workspace("/path/to/project")

# Read a file with line numbers
content = code_read_file("src/main.py")
print(content)

# Write to a file
code_write_file("src/new_file.py", "print('Hello, World!')")

# Execute a command
output = code_execute_command("python --version")

SEARCH/REPLACE Diff Format

The code editing module uses a SEARCH/REPLACE diff format for precise code modifications:

from praisonai.code import code_apply_diff

diff = """
<<<<<<< SEARCH
def old_function():
    return "old"
=======
def new_function():
    return "new"
>>>>>>> REPLACE
"""

result = code_apply_diff("src/main.py", diff)
print(result)  # "Successfully applied diff to src/main.py"

Line Number Hints

For faster matching in large files, use line number hints:

diff = """
<<<<<<< SEARCH :start_line:42
def target_function():
    pass
=======
def target_function():
    return "updated"
>>>>>>> REPLACE
"""

result = code_apply_diff("src/large_file.py", diff)

Available Tools

code_read_file

Read file contents with optional line range:

from praisonai.code import code_read_file

# Read entire file
content = code_read_file("src/main.py")

# Read specific lines (1-indexed)
content = code_read_file("src/main.py", start_line=10, end_line=20)

code_write_file

Create or overwrite a file:

from praisonai.code import code_write_file

code_write_file("src/new_file.py", """
def hello():
    print("Hello, World!")
""")

code_apply_diff

Apply SEARCH/REPLACE diffs:

from praisonai.code import code_apply_diff

diff = """
<<<<<<< SEARCH
old_code
=======
new_code
>>>>>>> REPLACE
"""

result = code_apply_diff("src/file.py", diff)

code_search_replace

Apply multiple search/replace operations:

from praisonai.code import code_search_replace

operations = [
    {"search": "old_name", "replace": "new_name"},
    {"search": "deprecated_func", "replace": "new_func"}
]

result = code_search_replace("src/file.py", operations)

code_list_files

List files in a directory:

from praisonai.code import code_list_files

files = code_list_files("src/", recursive=True)
for f in files:
    print(f)

code_execute_command

Execute shell commands:

from praisonai.code import code_execute_command

output = code_execute_command("python -m pytest tests/")
print(output)

code_run_python

Execute Python source in a subprocess (not a sandbox — the child inherits the current interpreter and environment). Source is passed as an argv list, so newlines, backslashes and quotes reach the child interpreter exactly as written, identically on POSIX and Windows.

from praisonai.code import code_run_python

result = code_run_python(
    code="print('hello')\nfor i in range(3): print(i)",
    cwd=".",
    timeout=30,
)
# {
#   'success': True, 'exit_code': 0,
#   'stdout': 'hello\n0\n1\n2\n',
#   'stderr': '',
#   'command': '/usr/bin/python -c <code>',
#   'cwd': '.',
# }

Field	Type	Notes
`success`	bool	`True` iff `exit_code == 0`
`exit_code`	int	`-1` on timeout / launch error
`stdout`	str	Child stdout
`stderr`	str	Child stderr
`command`	str	Always `"<python> -c <code>"` — source is not echoed back
`cwd`	str	Working directory used
`error`	str	Present only on timeout / launch error

Not a sandbox. Do not pass untrusted code from end users without isolating the host process (subprocess with setrlimit, container, or VM). See python_tools for the safer, already-timeout-boxed alternative for user-supplied code.

Using with Agents

The code tools can be used directly with PraisonAI agents:

from praisonai import Agent
from praisonai.code import CODE_TOOLS

agent = Agent(
    name="Code Editor",
    role="Software Developer",
    goal="Edit and improve code",
    tools=CODE_TOOLS
)

result = agent.start("Refactor the main.py file to use async/await")

Features

Fuzzy Matching

The diff application uses fuzzy matching with Levenshtein distance:

from praisonai.code import code_apply_diff

# Even with slight differences, the diff will match
diff = """
<<<<<<< SEARCH
def function():  # slight whitespace difference
    pass
=======
def function():
    return True
>>>>>>> REPLACE
"""

result = code_apply_diff("src/file.py", diff, similarity_threshold=0.8)

Indentation Preservation

The module automatically preserves indentation when applying diffs:

diff = """
<<<<<<< SEARCH
    def nested_function():
        pass
=======
    def nested_function():
        return "preserved indentation"
>>>>>>> REPLACE
"""

Workspace Security

Every file-modifying tool (code_apply_diff, code_search_replace, code_write_file, code_read_file, code_list_files, and the low-level append_to_file) is confined to the workspace root. Paths that resolve outside the workspace are rejected with "Path '<path>' is outside the workspace".

Default workspace is the current working directory. If you never call set_workspace(...), the tools confine writes and reads to cwd. Absolute paths outside cwd are rejected.
Explicit set_workspace(...) is still recommended — it makes the confinement boundary explicit and portable across working directories.
Protected-path check runs first. System paths (e.g. /etc/hosts, ~/.ssh/) are rejected even if they sit inside the workspace. See Protected Paths.
Gitignore Support: Respects .gitignore patterns for listing.
Access Control: Configurable file access rules.

Behaviour change (PraisonAI #3087, commit d1d0272). Before this fix, workspace confinement was silently skipped in apply_diff, search_replace, and append_to_file whenever no workspace was set. Agents could escape cwd via absolute paths like apply_diff("/etc/hosts", ...). After the fix, cwd is used as the default workspace and confinement is always enforced. If you relied on writing to absolute paths outside cwd without calling set_workspace(), call set_workspace(...) at the intended root instead.

append_to_file

append_to_file is available as a low-level import: from praisonai.code.tools.write_file import append_to_file. An agent-tool wrapper (code_append_to_file) is not yet exported from praisonai.code.

Append content to a file (creates it if missing):

from praisonai.code.tools.write_file import append_to_file

result = append_to_file(
    "logs/run.log",
    "new line\n",
    workspace="/path/to/project",   # optional — defaults to cwd
    create_if_missing=True,          # default True
    encoding="utf-8",                # default utf-8
)

Returns {"success": bool, "path": str, "created": bool, "bytes_appended": int} on success, or {"success": False, "error": str} on failure.

Configuration

Set Workspace

from praisonai.code import set_workspace, get_workspace

# Set workspace
set_workspace("/path/to/project")

# Get current workspace
workspace = get_workspace()
print(workspace)  # "/path/to/project"

Environment Variables

# Set default workspace
export PRAISONAI_CODE_WORKSPACE=/path/to/project

Module Structure

praisonai/code/
├── __init__.py          # Main exports
├── agent_tools.py       # Agent-compatible tool wrappers
├── diff/
│   └── diff_strategy.py # SEARCH/REPLACE diff with fuzzy matching
├── tools/
│   ├── read_file.py     # Read files with line ranges
│   ├── write_file.py    # Create/overwrite files
│   ├── list_files.py    # List directory contents
│   ├── apply_diff.py    # Apply SEARCH/REPLACE diffs
│   ├── search_replace.py # Multiple search/replace ops
│   └── execute_command.py # Run shell commands
└── utils/
    ├── file_utils.py    # Line numbers, file ops
    ├── text_utils.py    # Similarity, fuzzy search
    └── ignore_utils.py  # Gitignore, access control

​Code Editing

​Installation

​Quick Start

​SEARCH/REPLACE Diff Format

​Line Number Hints

​Available Tools

​code_read_file

​code_write_file

​code_apply_diff

​code_search_replace

​code_list_files

​code_execute_command

​code_run_python

​Using with Agents

​Features

​Fuzzy Matching

​Indentation Preservation

​Workspace Security

​append_to_file

​Configuration

​Set Workspace

​Environment Variables

​Module Structure

Code Editing

Installation

Quick Start

SEARCH/REPLACE Diff Format

Line Number Hints

Available Tools

code_read_file

code_write_file

code_apply_diff

code_search_replace

code_list_files

code_execute_command

code_run_python

Using with Agents

Features

Fuzzy Matching

Indentation Preservation

Workspace Security

append_to_file

Configuration

Set Workspace

Environment Variables

Module Structure