Implement Operation

June 29, 2026 · View on GitHub

The implement operation is a core feature of the Perpetual tool designed to automate code implementation based on user-provided instructions. This operation leverages Large Language Models (LLMs) to analyze your project, understand the context, and generate, modify, or delete code files according to your specifications.

Understanding the Implement Operation

The implement operation is run in one of two modes selected with the required -m flag: task mode or comment mode.

In task mode (-m task), you provide implementation instructions directly—via standard input or from a file using the -i flag—thereby bypassing the search for ###IMPLEMENT### comments. Task mode always uses planning and can affect any project files (modify, create, or delete them). This is the recommended mode for most use cases, as it allows you to describe your requirements freely without modifying source files and gives the LLM the freedom to make broader, coordinated changes across the project.

In comment mode (-m comment), the operation works by identifying and processing sections of your code marked with ###IMPLEMENT### comments. These comments serve as indicators for where new code should be generated or existing code modified. Comment mode is recommended only for minor edits or for cases where you want to precisely specify the location of the code to be generated or changed. By default, comment mode cannot affect files other than those containing the ###IMPLEMENT### comments unless the -p flag is used to enable planning.

Both modes follow a multi-stage process to ensure accurate and contextually appropriate code implementation:

  1. Project Analysis
    The operation begins by analyzing your project structure and content. It utilizes the project index and annotations generated by the annotate operation to understand the overall context of your codebase.

  2. Target File Identification
    In task mode, ###IMPLEMENT### comments are ignored; there are no initial target files, and relevant files are selected later according to the task instructions and project index. In comment mode, files containing ###IMPLEMENT### comments are identified as initial targets for code implementation.

  3. Context Gathering
    The operation collects relevant information from target files and related project files to provide comprehensive context to the LLM.

  4. Code Generation and File Planning
    Using the gathered context and the task instructions or the instructions provided in the ###IMPLEMENT### comments, the LLM generates or modifies code for each selected file. Depending on the planning mode, it may also modify related files, create new files, or delete existing files if necessary.

  5. Integration
    Generated changes and requested deletions are saved as a "stash" and then automatically applied. You can later use the stash operation to roll the changes back or re-apply them, including restoring deleted files or re-applying file deletions.

Throughout this process, the implement operation relies heavily on the project index and file annotations to make informed decisions about code implementation, ensuring that the generated code is consistent with your project's structure, coding style, and existing functionality.

Workflow and Usage Guide

To effectively use the implement operation, follow this typical workflow:

  1. Project Setup

    • Create the basic structure of your project, including main files and directories.
    • Initialize your project for use with the Perpetual tool by using the init operation.
    • Create a local .env configuration file(s) at <project_root>/.perpetual/*.env and/or a global configuration file(s) at ~/.config/Perpetual/*.env on Linux or <User profile dir>\AppData\Roaming\Perpetual\*.env on Windows. Settings from the local project configuration file take precedence over global configuration settings. Use example *.env files from <project_root>/.perpetual/*.env.example as reference.

  2. Describing the Implementation

    • In task mode (the recommended approach), prepare a task description in plain text or Markdown that explains what you want implemented. You can describe new functionality, modifications, or even file creation or deletion explicitly if needed. The description is provided through standard input or via a file with the -i flag.

    • In comment mode, use ###IMPLEMENT### comments in your source files to indicate where you want code to be generated or modified. This is best suited for minor edits or when you need to precisely specify the location of the code. You may also describe when related files should be created or obsolete files should be deleted, but creating and deleting files requires planning mode (-p).

    • Example of a comment-mode marker:

      //###IMPLEMENT###
//Create a function to check user input

  3. Running the Implement Operation

    • Execute the implement operation using the command:

      Perpetual implement -m <mode> [flags]

    • You must select a mode with the -m flag.

    • Task Mode (-m task, recommended): Instructions are provided through standard input or by specifying a file with -i. Task mode always uses planning and can affect any project files.

    • Comment Mode (-m comment): The operation processes all files with ###IMPLEMENT### comments. It cannot affect other files unless the -p flag is used.

  4. Reviewing and Iterating

    • Review the generated code and any created or deleted files for accuracy and consistency.

    • If necessary, use the stash operation to revert changes:

      Perpetual stash -m rollback

    • Modify your task instructions or ###IMPLEMENT### comments to provide more specific guidance if needed.

    • Re-run the implement operation to generate new code based on updated instructions.

  5. Finalizing

    • Once satisfied with the generated code and file changes, commit the changes to your version control system.
    • Repeat from step 2 for further implementations.

Special Comments

  • ###IMPLEMENT###: Marks sections for code implementation in comment mode. You can provide detailed instructions after this comment.

  • ###NOUPLOAD###: Marks files that should generally be excluded from upload as related/review files during the implement, doc, and explain workflows unless the -f flag is used.

    It is important to note that ###NOUPLOAD### is not a complete data-protection mechanism. Files explicitly selected as implementation targets can still be sent to the LLM as part of the implementation task, and the file may still be processed during the annotate operation. The annotation process is necessary to create the project index, which helps the LLM understand the project structure and write new code in context. While the annotation may leak some contextual information about the file, this can be mitigated with special summarization instructions (see the annotate operation documentation for more details). Users should be aware of these limitations and take appropriate precautions when dealing with sensitive information. To ensure a file is never processed by the LLM, exclude it using project.json configuration or a user filter file.

    ###NOUPLOAD### controls whether file contents are uploaded as context; it is not a general protection against all file operations. If you must prevent a file from being modified or deleted by implement, exclude it with the project whitelist/blacklist configuration or a user filter file.

Examining Logs

Perpetual provides detailed logging of LLM interactions in the <project_root>/.perpetual/.message_log.txt file. This file contains an unformatted log of the actual messages exchanged between Perpetual and the LLM. The log provides a complete record of the communication and can be useful if you need to understand the exact content of the messages sent to the LLM.

Command-Line Usage

To run the implement operation, use the following command:

Perpetual implement -m <mode> [flags]

Supported flags:

  • -h: Display help information about the implement operation.
  • -m <mode>: Select operation mode (required). Valid values: task, comment.
    • task: Implement code based on a task read from a text file or stdin (see the -i flag). Uses planning and can affect any project files. This is the recommended mode.
    • comment: Generate code marked with ###IMPLEMENT### comments in the source code. Cannot affect other files unless using the -p flag. Best suited for minor edits or precise placement of code.
  • -c <mode>: Context saving mode, reduce LLM context use for large projects (valid values: auto|off|medium|high).
  • -df <file>: Optional path to project description file for adding into LLM context (valid values: file path or disabled).
  • -f: Disable the no-upload file filter and upload such files for review and processing if requested.
  • -i <file>: Path to a text file (plain text or Markdown) with the task to implement in task mode (-m task). If empty or -, the task is read from stdin. Only valid in task mode.
  • -n: No annotate mode. Skip re-annotating changed files and skip updating embeddings; use current annotations and embeddings if any.
  • -ni: No incremental mode. Disable using incremental search-and-replace mode when generating file changes.
  • -p: Enable extra planning that allows making changes to other files (create new files, delete files, or modify files not originally marked with ###IMPLEMENT###) when using comment mode (-m comment). Disabled by default to save tokens. This flag is only applicable in comment mode; task mode always uses planning.
  • -s <n>: Limit number of files related to the task returned by local search (0 = disable local search, only use LLM-requested files; default: 5). This flag uses embeddings and performs local similarity search for files related to the implementation context.
  • -sp <n>: Set number of passes for related files selection at Stage 1 (default: 1). Higher pass-count values can select more files and compensate for possible LLM errors when finding relevant files, but they cost more API calls, tokens, and context.
  • -u: Do not exclude unit-test source files from processing.
  • -x <file>: Path to a user-supplied regex filter file for filtering out certain files from processing. See more info about using the filter here.
  • -v: Enable debug logging for more detailed output.
  • -vv: Enable debug and trace logging for maximum verbosity.

Implementation Details

The implement operation is divided into four main stages.

Stage 1: Context Gathering

  1. Run annotate and embed to update project source code annotations and vector embeddings, unless the -n flag is used or all project files are already selected for processing.
  2. Generate a project index containing filenames and their annotations.
  3. Create a request for relevant files based on task instructions or ###IMPLEMENT### target files. Query the LLM to identify which project source code files are relevant. Local vector search is also used to find relevant files that the LLM may miss, if embeddings are configured and search is enabled.
  4. Return the list of files to review.

Stage 2: Context Preparation and Optional Work Plan

  1. Gather Source Code: Collect source code from the files identified for review.
  2. Planning Mode: In task mode (-m task) or comment mode with the -p flag, the LLM produces reasonings and a work plan outlining the codebase changes required. This allows subsequent stages to modify related files, create new files, and delete existing files.
  3. No Planning Mode: In comment mode without the -p flag, the LLM is given the target files and related context and is prepared to implement only the initially targeted files. File creation and deletion are not planned in this mode.

Stage 3: Planning Changes

  1. Determine Files to Modify, Create, or Delete: If planning is enabled, query the LLM for the list of files that will be modified, created, or deleted. If planning is disabled, this stage does not perform an LLM request and simply uses the initial target files.
  2. Parse and Validate the LLM Response: Extract filenames, normalize paths, check them against the project structure, and separate existing target files, other existing files, new files, and files selected for deletion.
  3. Safety Handling: If the LLM requests modification of an existing file that was not previously provided as context, Perpetual can add its contents to the message history to reduce the risk of overwriting it incorrectly. For deletion requests, Perpetual validates that the file exists before adding it to the deletion list.
  4. Filtering and Deletion Rules: Additional files selected for modification are filtered through ###NOUPLOAD###, project whitelist/blacklist rules, and user filters where applicable. Files selected for deletion must already exist and must pass project whitelist/blacklist and user-filter checks. If a file is selected for both modification and deletion, deletion takes precedence.

Stage 4: Code Generation

  1. Use Gathered Context and Work Plan: Use the relevant source code, selected file list, optional deletion list, and optional work plan as guidance.
  2. Iterative Processing of Each File:
    • Query the LLM to produce implemented code for each file selected for modification or creation.
    • Prefer incremental search-and-replace mode when enabled, supported by the provider, and allowed by project configuration.
    • Fall back to full-file generation when incremental mode is disabled, not applicable, or fails.
    • Handle partial full-file responses and continue generation if token limits are reached, up to the configured segment limit.
    • Parse and store the generated code for each file.
  3. Integration via Stash: Save generated changes and requested deletions into a stash and automatically apply that stash to the working tree.

Working with Large Projects

When working with large projects, Perpetual employs several context saving measures to manage LLM context limits. This is mainly needed to make project annotations, task summaries, and source-code analysis fit LLM model context window limits during Stage 1.

Context Saving Modes

The -c flag allows you to control context saving behavior:

  • auto (default): Automatically enables context saving based on project file count thresholds.
  • off: Disables context saving measures.
  • medium: Enables moderate context saving regardless of project size.
  • high: Enables aggressive context saving regardless of project size.

File Count Thresholds

Context saving is automatically triggered based on project file count:

  • Medium Context Saving: Activated when the project exceeds 400 files by default, configurable via medium_context_saving_file_count in project.json.
  • High Context Saving: Activated when the project exceeds 1200 files by default, configurable via high_context_saving_file_count in project.json.

Context Saving Measures

  1. Shorter Annotations: When context saving is enabled, the annotate operation generates shorter, more concise file summaries to reduce context usage. Important: If you change context saving settings, you may need to manually regenerate annotations using Perpetual annotate -f to ensure consistency.

  2. Project File Pre-selection: Uses local similarity search with embeddings to pre-select the most relevant files for processing:

    • Medium Context Saving: Selects 60% of project files by default, with 25% randomized.
    • High Context Saving: Selects 30% of project files by default, with 20% randomized.

  3. Multi-pass File Selection: The -sp flag enables multiple passes of file selection at Stage 1, helping compensate for potential LLM errors in identifying relevant files. It works with or without context saving enabled, but it costs more API calls and may lead to higher token usage.

Requirements for Context Saving

  • Embeddings Support: Context saving features require an embedding model to be configured in your *.env files for local similarity search functionality.
  • Annotation Updates: Ensure your project annotations are current when using context saving, as these are used for file relevance calculations. Annotations are not rebuilt automatically when starting to use context saving measures, so you need to rebuild them with the annotate operation using the -f flag to make all current annotations smaller, not only annotations for new or modified files.

Configuration

For details, see the project.json configuration file description below.

LLM Configuration

The implement operation can be fine-tuned using environment variables in .env files. These variables allow you to customize the behavior of the LLM used for code implementation. Key configuration options include:

  1. LLM Provider

    • LLM_PROVIDER_OP_IMPLEMENT_STAGE1, LLM_PROVIDER_OP_IMPLEMENT_STAGE2, LLM_PROVIDER_OP_IMPLEMENT_STAGE3, LLM_PROVIDER_OP_IMPLEMENT_STAGE4: Specify the LLM provider for each stage of the implement operation.
    • LLM_PROVIDER_OP_EMBED: Specify the provider used for embeddings and local similarity search.
    • LLM_PROVIDER: Default fallback provider.

  2. Model Selection

    • ANTHROPIC_MODEL_OP_IMPLEMENT_STAGE1, ANTHROPIC_MODEL_OP_IMPLEMENT_STAGE2, ANTHROPIC_MODEL_OP_IMPLEMENT_STAGE3, ANTHROPIC_MODEL_OP_IMPLEMENT_STAGE4: Anthropic models for each stage.
    • Similar variables exist for OpenAI, Ollama, and Generic providers, such as OPENAI_MODEL_OP_IMPLEMENT_STAGE1, OLLAMA_MODEL_OP_IMPLEMENT_STAGE1, GENERIC_MODEL_OP_IMPLEMENT_STAGE1, etc.

  3. Token Limits

    • ANTHROPIC_MAX_TOKENS_OP_IMPLEMENT_STAGE1, ANTHROPIC_MAX_TOKENS_OP_IMPLEMENT_STAGE2, ANTHROPIC_MAX_TOKENS_OP_IMPLEMENT_STAGE3, ANTHROPIC_MAX_TOKENS_OP_IMPLEMENT_STAGE4: Set maximum tokens for each stage.
    • Similar variables exist for OpenAI, Ollama, and Generic providers.
    • <PROVIDER>_MAX_TOKENS_SEGMENTS: Controls how many continuation segments may be attempted for operations that support continuation after token-limit truncation.

  4. Retry Settings

    • ANTHROPIC_ON_FAIL_RETRIES_OP_IMPLEMENT_STAGE1, ANTHROPIC_ON_FAIL_RETRIES_OP_IMPLEMENT_STAGE2, ANTHROPIC_ON_FAIL_RETRIES_OP_IMPLEMENT_STAGE3, ANTHROPIC_ON_FAIL_RETRIES_OP_IMPLEMENT_STAGE4: Specify retry attempts for each stage.
    • Similar variables exist for OpenAI, Ollama, and Generic providers.

  5. Incremental Mode Settings

    • <PROVIDER>_INCRMODE_SUPPORT_OP_IMPLEMENT_STAGE4: Enable or disable incremental search-and-replace mode support for Stage 4.
    • <PROVIDER>_INCRMODE_SUPPORT: Default incremental mode support setting for the provider.
    • <PROVIDER>_INCRMODE_RETRIES: Number of retry attempts for incremental mode before falling back to full-file generation.

  6. Temperature

    • ANTHROPIC_TEMPERATURE_OP_IMPLEMENT_STAGE1, ANTHROPIC_TEMPERATURE_OP_IMPLEMENT_STAGE2, ANTHROPIC_TEMPERATURE_OP_IMPLEMENT_STAGE3, ANTHROPIC_TEMPERATURE_OP_IMPLEMENT_STAGE4: Set temperature for each stage.
    • Similar variables exist for OpenAI, Ollama, and Generic providers.

  7. Other LLM Parameters

    • Provider-specific options such as TOP_K, TOP_P, SEED, REPEAT_PENALTY, FREQ_PENALTY, PRESENCE_PENALTY, reasoning controls, prompt role controls, and prompt prefixes/suffixes can be set for each stage by using the corresponding provider-specific environment variable names. Consult the generated *.env.example files for details.

Example configuration in .env file:

LLM_PROVIDER_OP_IMPLEMENT_STAGE1="anthropic"
LLM_PROVIDER_OP_IMPLEMENT_STAGE2="anthropic"
LLM_PROVIDER_OP_IMPLEMENT_STAGE3="anthropic"
LLM_PROVIDER_OP_IMPLEMENT_STAGE4="anthropic"
ANTHROPIC_MODEL_OP_IMPLEMENT_STAGE1="claude-sonnet-4-5-20250929"
ANTHROPIC_MODEL_OP_IMPLEMENT_STAGE2="claude-sonnet-4-5-20250929"
ANTHROPIC_MODEL_OP_IMPLEMENT_STAGE3="claude-sonnet-4-5-20250929"
ANTHROPIC_MODEL_OP_IMPLEMENT_STAGE4="claude-sonnet-4-5-20250929"
ANTHROPIC_MAX_TOKENS_OP_IMPLEMENT_STAGE1="1024"
ANTHROPIC_MAX_TOKENS_OP_IMPLEMENT_STAGE2="4096"
ANTHROPIC_MAX_TOKENS_OP_IMPLEMENT_STAGE3="2048"
ANTHROPIC_MAX_TOKENS_OP_IMPLEMENT_STAGE4="16384"
ANTHROPIC_TEMPERATURE_OP_IMPLEMENT_STAGE1="0.2"
ANTHROPIC_TEMPERATURE_OP_IMPLEMENT_STAGE2="1"
ANTHROPIC_TEMPERATURE_OP_IMPLEMENT_STAGE3="0.2"
ANTHROPIC_TEMPERATURE_OP_IMPLEMENT_STAGE4="0.5"
ANTHROPIC_ON_FAIL_RETRIES_OP_IMPLEMENT_STAGE1="2"
ANTHROPIC_ON_FAIL_RETRIES_OP_IMPLEMENT_STAGE2="7"
ANTHROPIC_ON_FAIL_RETRIES_OP_IMPLEMENT_STAGE3="7"
ANTHROPIC_ON_FAIL_RETRIES_OP_IMPLEMENT_STAGE4="10"

Prompts Configuration

Customization of LLM prompts for the implement operation is handled through the .perpetual/op_implement.json configuration file. This file is populated using the init operation, which sets up default language-specific prompts tailored to your project's needs. You may modify it in case of problems, but normally you should not change it unless you are adapting prompts for a programming language or project type not supported by Perpetual.

The prompt configuration is organized by stages, with each stage having specific prompts for different scenarios. The configuration allows for fine-tuning how the LLM processes requests at each stage of the implementation workflow.

Stage 1 Prompts

Stage 1 is responsible for analyzing the project context and identifying relevant files for code implementation. It creates a project index using file annotations and determines which additional files should be reviewed to provide proper context for the implementation task.

  • stage1_task_analysis_prompt: Analysis prompt for task mode, used when implementation instructions are provided directly rather than through ###IMPLEMENT### comments.
  • stage1_analysis_prompt: Main prompt for comment mode that asks the LLM to identify which project files are relevant for implementing the specified tasks.

Stage 2 Prompts

Stage 2 handles the gathering of source code context and, optionally, the generation of implementation reasoning or work plans. This stage prepares the foundation for subsequent stages by organizing relevant information and creating detailed plans when needed.

  • code_prompt: Prompt for reviewing and analyzing the source code files identified in Stage 1, providing context for implementation decisions.
  • code_response: Simulated response acknowledging the code review completion.
  • stage2_task_reasonings_prompt: Reasoning prompt specifically for task mode implementations, used to generate the work plan.
  • stage2_task_reasonings_prompt_final: Final reasoning prompt for task mode. This is a simplified version of the previous prompt that is used in LLM message history on later stages instead of the full prompt to draw LLM attention away from unneeded instructions.
  • stage2_reasonings_prompt: Prompt for generating detailed reasoning and a work plan when planning mode is enabled in comment mode (-p flag).
  • stage2_reasonings_prompt_final: Final prompt used after reasoning generation to prepare for subsequent stages. This is a simplified version of the previous prompt that is used in LLM message history on later stages instead of the full prompt to draw LLM attention away from unneeded instructions.
  • stage2_noplanning_prompt: Prompt used when planning mode is disabled (comment mode without the -p flag), requesting direct implementation without a work plan.
  • stage2_noplanning_response: Simulated response for the no-planning mode.

Stage 3 Prompts

Stage 3 determines which files will be modified, created, or deleted during the implementation process. This stage analyzes the requirements and optional work plan to produce a list of files that need changes or deletion.

  • stage3_planning_prompt: Main prompt for determining file modifications, creations, and deletions when using planning mode.
  • stage3_extra_files_prompt: Additional prompt used in task mode when extra existing files need to be included in the context to prevent overwriting existing code.

Stage 4 Prompts

Stage 4 performs the actual code implementation, processing each selected file individually and generating the final code based on all previous analysis and planning. Files selected for deletion in Stage 3 are not generated in Stage 4; they are recorded directly in the stash as deleted file states.

  • stage4_changes_done_prompt: Prompt that provides context about previously implemented files during iterative processing.
  • stage4_changes_done_response: Simulated response acknowledging the completed changes.
  • stage4_continue_prompt: Prompt used when the LLM response reaches token limits and needs to continue generating the remaining code.
  • stage4_process_prompt: Main prompt for implementing code in a specific file, with placeholders for file-specific information.
  • stage4_process_incremental_prompt: Prompt for incremental search-and-replace mode implementation, which can be more efficient for large files.

System-level Configuration Options

System-level configuration options that apply across all stages:

  • system_prompt: The primary system prompt that establishes the LLM's role and general behavior for the implement operation.
  • system_prompt_ack: Acknowledgment response that the LLM should provide to confirm understanding of the system prompt.
  • filename_embed_rx: Regular expression pattern used to embed the filename into file implementation requests.
  • implement_comments_rx: Regular expressions to detect ###IMPLEMENT### comments.

Project Configuration

Global project configuration is handled through the .perpetual/project.json configuration file. It defines which source code files are targets for processing with Perpetual and which are not. Update the paths and regex patterns used for project file selection to fit your specific project requirements.

File Selection Configuration

The following configuration keys control which files are included or excluded from processing:

  • project_files_whitelist: An array of regular expressions that define which files should be included for processing. Only files matching these patterns will be considered by Perpetual operations. This allows you to focus on specific file types or directories.

  • project_files_blacklist: An array of regular expressions that define which files should be excluded from processing. Files matching these patterns will be filtered out even if they match the whitelist patterns. Use this to exclude configuration files, build artifacts, or other files that shouldn't be processed.

  • project_test_files_blacklist: An array of regular expressions specifically for identifying unit test files. These files will be excluded from processing by default unless the -u flag is used. This helps keep test files separate from main source code during analysis.

  • files_to_md_code_mappings: A 2D array that maps filename regular expressions to markdown code block language identifiers. This helps the LLM properly format code blocks when presenting source code. For example, ["(?i)\\.go$", "go"] maps Go files to the go language identifier in markdown.

  • noupload_comments_rx: Regular expressions to detect ###NOUPLOAD### comments in files.

Context Saving Configuration

Context saving thresholds and percentages can be customized in your project.json configuration file:

  • medium_context_saving_file_count: The threshold number of files that triggers medium context saving mode automatically when using the auto context saving setting.

  • high_context_saving_file_count: The threshold number of files that triggers high context saving mode automatically when using the auto context saving setting.

  • medium_context_saving_select_percent: Percentage of project files to select during medium context saving mode.

  • medium_context_saving_random_percent: Percentage of selected files that should be chosen randomly during medium context saving mode.

  • high_context_saving_select_percent: Percentage of project files to select during high context saving mode.

  • high_context_saving_random_percent: Percentage of selected files that should be chosen randomly during high context saving mode.

Incremental Mode Configuration

Configuration for incremental search-and-replace mode in Stage 4:

  • files_incremental_mode_min_length: A 2D array that maps filename regular expressions to minimum file sizes for incremental mode. Files smaller than the specified size use full-file processing instead of incremental mode. If a file does not match this configuration, incremental mode is not used for it.
  • files_incremental_mode_rx: Regular expressions used to parse incremental search-and-replace blocks from LLM responses.

Other Configuration

  • project_index_prompt: Initial prompt that presents the project file index with annotations to give the LLM an overview of the project structure and content.
  • project_index_response: Simulated LLM response acknowledging receipt of the project index.
  • project_description_prompt: Prompt for providing project description context to the LLM.
  • project_description_response: Simulated response acknowledging project description.
  • filename_tags: Tags used to denote filenames in messages.
  • filename_tags_rx: Regular expressions to parse filename tags.
  • delete_tags: Tags used by the LLM to mark existing files that should be deleted during planning.
  • delete_tags_rx: Regular expressions to parse deletion tags from LLM responses.
  • code_tags_rx: Regular expressions to identify code blocks in responses.

Best Practices

  1. Prefer Task Mode: For most implementations, use task mode (-m task) and describe your requirements in a task file or via stdin. Reserve comment mode (-m comment) for minor edits or cases where you need to precisely specify the location of the code.
  2. Clear Instructions: Provide detailed and clear instructions in your task description or ###IMPLEMENT### comments.
  3. Incremental Implementation: Break complex features into smaller tasks for easier review and iteration.
  4. Explicitly Request Deletions: If obsolete files should be deleted, state this clearly in your task instructions or implementation comments and use planning mode (task mode, or -p in comment mode).
  5. Regular Code Reviews: Always review the generated code and any file deletions carefully.
  6. Version Control: Use version control systems and the stash operation to manage and revert changes.
  7. Consistent Coding Style: Maintain a consistent style to help the LLM match your existing code.
  8. Good Project Architecture: A clear, modular architecture yields better LLM results.
  9. Use Planning When Needed: Task mode always uses planning. In comment mode, enable -p for extensive changes that require broader file modification, creation, and deletion planning.
  10. Use ###NOUPLOAD### with Awareness: Prevent sensitive or irrelevant files from being used as related context, but configure project.json or a user filter to fully exclude files if needed.
  11. Iterative Refinement: Refine task instructions or comments and re-run the operation as needed.
  12. Fine-tune LLM Settings: Experiment with environment settings for your LLM provider, and consult the *.env.example files at <project_root>/.perpetual/*.env.example.

Error Handling and Retries

  1. LLM Query Failures: Retries up to the number specified in <PROVIDER>_ON_FAIL_RETRIES_OP_IMPLEMENT_STAGE<NUMBER>.
  2. Token Limit Handling: Stage 4 can continue full-file generation if the LLM response reaches the token limit, up to the configured segment limit. Other stages generally retry or fail when token limits are reached, especially when partial responses would make filename-list parsing, deletion-list parsing, or incremental parsing invalid.
  3. Invalid Responses: Checks for properly formatted filename lists, deletion lists, code blocks, or incremental search-and-replace blocks and retries when valid output cannot be parsed.
  4. Incremental Mode Fallback: If incremental search-and-replace output cannot be parsed or applied, Perpetual may retry incremental mode and then fall back to full-file generation.
  5. Stash Safety: Before applying generated output, Perpetual creates a stash containing original and modified file states. This allows generated modifications, creations, and deletions to be rolled back.

Performance Considerations

The implement operation can consume significant time when using a locally running LLM or incur costs when using commercial LLM providers, especially for large projects or complex tasks. Consider the following to optimize performance:

  1. Use Appropriate Models: Choose LLM models/providers that balance capability and speed. For example, use a smaller model for Stages 1 and 3 and more powerful models for Stages 2 and 4. You may also try using small local models with Ollama for the annotate operation to save on costs associated with automatically re-annotating changed files.
  2. Do Not Use -p Unless Needed: In comment mode, you may significantly save on LLM API calls, tokens, and costs by not using the -p flag if you believe that the implementation will not create new files, delete files, or modify files not marked with ###IMPLEMENT### comments. Note that this only applies to comment mode; task mode always uses planning.
  3. Incremental Implementation: For large projects, implement changes in smaller, manageable chunks rather than attempting to modify the entire codebase at once.
  4. Use the -u Flag When Tests Matter: If your project contains unit-test source files that are relevant to the implementation task, use the -u flag to include them in processing. This provides additional context for the LLM and allows it to see and modify unit tests. However, including tests increases the amount of code the LLM needs to analyze, which may increase costs.
  5. Custom File Filtering: For more fine-grained control over which files are processed, use the -x flag with a custom regex filter file. This allows you to exclude specific files or file types that are not relevant to your current implementation task, reducing your costs.
  6. Incremental Mode: The -ni flag disables incremental search-and-replace mode, which can be useful for troubleshooting but may increase token usage for large files. Generally, incremental mode is more efficient and should be left enabled unless you encounter issues.