{"id":29194772,"url":"https://github.com/paradite/ai-file-edit","last_synced_at":"2026-03-02T05:01:12.744Z","repository":{"id":291243148,"uuid":"976504957","full_name":"paradite/ai-file-edit","owner":"paradite","description":"A library for editing files using AI models","archived":false,"fork":false,"pushed_at":"2025-06-20T13:38:13.000Z","size":757,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-20T13:56:16.321Z","etag":null,"topics":["diff","edit","llm","prompt"],"latest_commit_sha":null,"homepage":"https://prompt.16x.engineer/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paradite.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-02T08:19:50.000Z","updated_at":"2025-11-23T02:11:48.000Z","dependencies_parsed_at":"2025-05-03T10:41:16.348Z","dependency_job_id":"5a65e18b-3fb9-4b66-8eb1-cf769e1831bd","html_url":"https://github.com/paradite/ai-file-edit","commit_stats":null,"previous_names":["paradite/mcp-file-edit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/paradite/ai-file-edit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradite%2Fai-file-edit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradite%2Fai-file-edit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradite%2Fai-file-edit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradite%2Fai-file-edit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paradite","download_url":"https://codeload.github.com/paradite/ai-file-edit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradite%2Fai-file-edit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29993021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diff","edit","llm","prompt"],"created_at":"2025-07-02T04:38:04.544Z","updated_at":"2026-03-02T05:01:12.722Z","avatar_url":"https://github.com/paradite.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI File Edit\n\n[![npm](https://img.shields.io/npm/v/ai-file-edit)](https://www.npmjs.com/package/ai-file-edit)\n\nA library for editing files using AI models such as GPT, Claude, and Gemini.\n\nDeveloped by the [16x Prompt](https://prompt.16x.engineer/) team.\n\nRelated projects:\n\n- [llm-info](https://github.com/paradite/llm-info): Information on LLM models, context window token limit, output token limit, pricing and more.\n- [send-prompt](https://github.com/paradite/send-prompt): A unified TypeScript library for AI model interactions with standardized interfaces and function calling.\n\n## Features\n\nFile Operations\n\n- Edit files using natural language\n- Create new files\n- Overwrite existing files\n- Make selective edits to files\n- Support for multiple file edits in a single operation\n\nAI Integration\n\n- Support for OpenAI, Anthropic, and Google AI models\n- Support for multiple tool use rounds\n- Debug mode for detailed logging\n\nVersion Control \u0026 Safety\n\n- Generate diffs for all changes\n- Generate reverse diffs for reverting changes\n- Ability to revert changes using reverse diffs\n\nSecurity\n\n- Secure file access with allowed directories\n- API key security\n- File path validation\n- Safe symlink handling\n\n## Supported Models\n\n```typescript\nimport {SUPPORTED_MODELS} from 'ai-file-edit';\nimport {ModelEnum, AI_PROVIDERS} from 'llm-info';\n\n// Print all supported models\nconsole.log(SUPPORTED_MODELS);\n\n// Example output:\n[\n  {\n    model: ModelEnum['gpt-4.1'],\n    provider: AI_PROVIDERS.OPENAI,\n    recommended: true,\n    supportMultipleEditsPerMessage: true,\n  },\n  {\n    model: ModelEnum['claude-3-7-sonnet-20250219'],\n    provider: AI_PROVIDERS.ANTHROPIC,\n    recommended: false,\n    supportMultipleEditsPerMessage: false,\n  },\n  {\n    model: ModelEnum['gemini-2.5-pro-preview-05-06'],\n    provider: AI_PROVIDERS.GOOGLE,\n    recommended: false,\n    supportMultipleEditsPerMessage: true,\n  },\n  {\n    model: ModelEnum['gemini-2.5-pro-exp-03-25'],\n    provider: AI_PROVIDERS.GOOGLE,\n    recommended: false,\n    supportMultipleEditsPerMessage: true,\n  },\n];\n```\n\nNote: The recommended model is `gpt-4.1` as it provides the best performance for file editing tasks.\n\n## Installation\n\n```bash\nnpm install ai-file-edit\n```\n\n## Usage\n\n### Basic Setup\n\n```ts\nimport {FileEditTool} from 'ai-file-edit';\nimport {ModelEnum, AI_PROVIDERS} from 'llm-info';\n\n// Initialize the tool with Claude\nconst claudeFileEditTool = new FileEditTool(\n  '/path/to/parent/directory', // Parent directory for relative paths\n  ['/path/to/allowed/directory'], // Allowed directories for file operations\n  {\n    provider: AI_PROVIDERS.ANTHROPIC,\n    model: ModelEnum['claude-3-7-sonnet-20250219'],\n    apiKey: process.env.ANTHROPIC_API_KEY,\n  },\n  ['/path/to/file1.js', '/path/to/file2.js'], // Optional: Files to include in context\n  5, // Optional: Maximum number of tool use rounds (default: 5)\n);\n\n// Initialize the tool with GPT\nconst gptFileEditTool = new FileEditTool(\n  '/path/to/parent/directory', // Parent directory for relative paths\n  ['/path/to/allowed/directory'], // Allowed directories for file operations\n  {\n    provider: AI_PROVIDERS.OPENAI,\n    model: ModelEnum['gpt-4.1'],\n    apiKey: process.env.OPENAI_API_KEY,\n  },\n  ['/path/to/file1.js', '/path/to/file2.js'], // Optional: Files to include in context\n  5, // Optional: Maximum number of tool use rounds (default: 5)\n);\n\n// Initialize the tool with Google AI\nconst googleFileEditTool = new FileEditTool(\n  '/path/to/parent/directory', // Parent directory for relative paths\n  ['/path/to/allowed/directory'], // Allowed directories for file operations\n  {\n    provider: AI_PROVIDERS.GOOGLE,\n    model: ModelEnum['gemini-2.5-pro-preview-05-06'],\n    apiKey: process.env.GOOGLE_API_KEY,\n  },\n  ['/path/to/file1.js', '/path/to/file2.js'], // Optional: Files to include in context\n  5, // Optional: Maximum number of tool use rounds (default: 5)\n);\n```\n\n### Basic Usage\n\n```typescript\nimport {FileEditTool} from 'ai-file-edit';\nimport {ModelEnum, AI_PROVIDERS} from 'llm-info';\n\nconst fileEditTool = new FileEditTool(\n  '/path/to/parent/directory', // Parent directory for relative paths\n  ['/path/to/allowed/directory'], // Allowed directories for file operations\n  {\n    provider: AI_PROVIDERS.ANTHROPIC,\n    model: ModelEnum['claude-3-7-sonnet-20250219'],\n    apiKey: 'your-api-key',\n  },\n  ['/path/to/file/to/edit'], // Optional: Files to include in context\n);\n\n// Process query with debug mode enabled\nconst response = await fileEditTool.processQuery('Update the file to add a new function', true);\nconsole.log(response.finalText);\nconsole.log(response.toolResults);\nconsole.log(response.rawDiff);\nconsole.log(response.reverseDiff);\nconsole.log(response.toolCallRounds);\n```\n\n### Diffs and Reverting Changes\n\nThe tool generates both forward and reverse diffs for all file changes. The forward diff shows what was changed, while the reverse diff can be used to revert the changes.\n\n#### Forward Diff\n\nThe forward diff is returned in the `rawDiff` field of the response. It shows the changes made to the file in a git-style diff format:\n\n```diff\n--- file.js original\n+++ file.js modified\n@@ -1,2 +1,2 @@\n-function add(a, b) { return a + b; }\n-console.log(add(1, 2));\n+function multiply(a, b) { return a * b; }\n+console.log(multiply(1, 2));\n```\n\n#### Reverse Diff\n\nThe reverse diff is returned in the `reverseDiff` field of the response. It shows how to revert the changes in a git-style diff format:\n\n```diff\n--- file.js modified\n+++ file.js original\n@@ -1,2 +1,2 @@\n-function multiply(a, b) { return a * b; }\n-console.log(multiply(1, 2));\n+function add(a, b) { return a + b; }\n+console.log(add(1, 2));\n```\n\n#### Reverting Changes\n\nYou can use the reverse diff to revert changes using the `applyReversePatch` function:\n\n```typescript\nimport {applyReversePatch} from 'ai-file-edit';\n\n// Apply the reverse patch to revert changes\nconst result = await applyReversePatch(filePath, reverseDiff);\nif (result.success) {\n  console.log('Changes reverted successfully');\n} else {\n  console.error('Failed to revert changes:', result.error);\n}\n```\n\nThe `applyReversePatch` function returns a promise that resolves to an object with:\n\n- `success`: boolean indicating whether the operation was successful\n- `error`: optional string containing error message if the operation failed\n\n### File Context and Tool Use Rounds\n\nYou can provide a list of files to include in the context of the query. This is useful when you want to reference multiple files in your query:\n\n```typescript\nconst fileEditTool = new FileEditTool(\n  '/path/to/parent/directory',\n  ['/path/to/allowed/directory'],\n  ModelEnum['claude-3-7-sonnet-20250219'],\n  AI_PROVIDERS.ANTHROPIC,\n  'your-api-key',\n  ['/path/to/file1.js', '/path/to/file2.js'],\n  5, // Maximum number of tool use rounds (default: 5)\n);\n```\n\nThe tool supports multiple rounds of tool use, allowing the model to make multiple changes in response to a single query. The maximum number of rounds is configurable through the `maxToolUseRounds` parameter in the constructor.\n\n### Debug Mode\n\nThe `processQuery` method supports an optional debug mode that provides detailed logging of the tool's operation:\n\n```typescript\nconst response = await fileEditTool.processQuery('Update the file to add a new function', true);\n```\n\nWhen debug mode is enabled, the tool will log:\n\n- The initial query\n- Each tool call round\n- The message history\n- Tool call processing details\n- Response details\n\nThis is useful for debugging and understanding how the tool processes queries and makes changes.\n\n## Response Structure\n\nThe `processQuery` method returns an object with the following structure:\n\n```ts\n{\n  finalText: string[];      // Array of text responses from the AI\n  toolResults: string[];    // Array of results from tool operations\n  finalStatus: 'success' | 'failure' | 'retry_limit_reached' | 'no_tool_calls';\n  toolCallCount: number;    // Number of tool calls made\n  toolCallRounds: number;   // Number of tool call rounds used\n  rawDiff?: Record\u003cstring, string\u003e;    // Forward diffs for each file, keyed by file path\n  reverseDiff?: Record\u003cstring, string\u003e; // Reverse diffs for each file, keyed by file path\n}\n```\n\nExample response with diffs:\n\n```ts\n{\n  finalText: [\"Successfully updated files\"],\n  toolResults: [\"File updated successfully\"],\n  finalStatus: \"success\",\n  toolCallCount: 1,\n  toolCallRounds: 1,\n  rawDiff: {\n    \"/path/to/file1.js\": \"Index: /path/to/file1.js\\n...\",\n    \"/path/to/file2.js\": \"Index: /path/to/file2.js\\n...\"\n  },\n  reverseDiff: {\n    \"/path/to/file1.js\": \"Index: /path/to/file1.js\\n...\",\n    \"/path/to/file2.js\": \"Index: /path/to/file2.js\\n...\"\n  }\n}\n```\n\n## Limitations\n\n- Cannot delete files\n- Cannot edit too many files at once (\u003e 3 files)\n\n## Testing\n\nThe library includes test cases for both Claude and GPT models. To run the tests:\n\n```bash\nnpm test\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparadite%2Fai-file-edit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparadite%2Fai-file-edit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparadite%2Fai-file-edit/lists"}