Init Operation

June 29, 2026 · View on GitHub

The init operation is the starting point for using Perpetual with your project. It sets up the necessary configuration and directory structure required for Perpetual to function properly within your project environment.

Usage

To initialize a new Perpetual configuration for your project, run the following command from the root directory of your project:

Perpetual init [flags]

The init operation supports several command-line flags to customize its behavior:

  • -l <language>: Select the programming language for setting up default LLM prompts. This flag is required and must be provided with a valid language option.
  • -h: Display the help message, showing all available flags and their descriptions.
  • -v: Enable debug logging. This flag increases the verbosity of the operation's output.
  • -vv: Enable both debug and trace logging. This flag provides the highest level of verbosity.
  • -ex: Create env-file examples inside the .perpetual directory. When used, this flag generates example .env configuration files for Perpetual and each supported LLM provider.

Example Usage

Perpetual init -l go

This command initializes Perpetual for a Go project, setting up the appropriate configuration files with Go-specific prompts and file-selection rules.

Supported Languages

Perpetual currently supports the following programming languages and technologies:

  1. Go (go)
  2. .NET (dotnet) – Includes C#, VB.NET, XAML, Razor, CSS, JavaScript, and HTML files
  3. Bash (bash) – Intended mostly for Linux shell scripting
  4. Python 3 (python3)
  5. Visual Basic 6 (vb6) – Legacy VB6 projects
  6. C (c)
  7. C++ (cpp)
  8. Arduino (arduino) – Arduino sketches with C/C++ support
  9. Flutter (flutter) – Flutter/Dart apps, including selected native platform files

When using the -l flag, provide the language identifier as shown above. The language value is case-insensitive. You can add support for your programming language or project manually by editing file-selection regexps and LLM prompts in the corresponding config files.

Details

The init operation performs several tasks to set up your project for use with Perpetual:

  1. Creates a local Perpetual configuration directory. By default this is .perpetual in the current directory. If the directory already exists, it is reused.
  2. Creates a .gitignore file within the .perpetual directory to exclude generated Perpetual state files and local .env files from version control.
  3. Creates a description.md.template file that can be used as a starting point for creating a project description document.
  4. Generates JSON configuration files for the selected programming language, including default prompts, regexps, tags, context-saving settings, incremental-mode settings, and file-selection rules.
  5. Creates example .env.example files for Perpetual and each supported LLM provider, but only when the -ex flag is used: .env.example, ollama.env.example, openai.env.example, anthropic.env.example, and generic.env.example.
  6. Warns about obsolete configuration files and directories if any are found in the .perpetual directory.

When run inside an already initialized project, init will overwrite the generated project-local config files, .gitignore, and description template (and the example environment files when -ex is used). Back up any manual changes before running it again.

Note: The init operation respects the PERPETUAL_DIR environment variable. If set, it uses the specified directory instead of creating .perpetual in the current directory.

Directory and File Structure

After running the init operation, the following project-local structure is created by default:

<project_root>/
└── .perpetual/
    ├── .gitignore
    ├── description.md.template
    ├── op_annotate.json
    ├── op_implement.json
    ├── op_doc.json
    ├── op_explain.json
    ├── op_report.json
    └── project.json

When the -ex flag is used, the following example environment files are additionally created inside the .perpetual directory:

<project_root>/
└── .perpetual/
    ├── .env.example
    ├── ollama.env.example
    ├── openai.env.example
    ├── anthropic.env.example
    └── generic.env.example

In addition to project-local configuration, Perpetual can also read environment values from a global, OS-specific user config directory when loading settings, for example:

~/.config/Perpetual/
└── *.env

on Linux, or:

<User profile dir>\AppData\Roaming\Perpetual\
└── *.env

on Windows. The init operation itself does not create this global directory or any global .env file.

Customizable Files

Most files generated by the init operation can be customized to fine-tune Perpetual's behavior for your project:

  1. .env files

    Perpetual does not create a project-local .env file by default. To configure environment variables, run init with the -ex flag to generate example files, copy one or more of them to files ending with .env, then edit them as needed.

    For example:

    • Copy .env.example to .env for general provider-selection settings.
    • Copy openai.env.example to openai.env for OpenAI-specific settings.
    • Copy ollama.env.example to ollama.env for Ollama-specific settings.

    You can merge settings into a single .env file or keep them split across multiple *.env files.

    Perpetual loads environment values with the following precedence:

    • Existing system environment variables have the highest priority.
    • Project-local env files: <project_root>/.perpetual/*.env
    • Global env files: e.g. ~/.config/Perpetual/*.env on Linux or <User profile dir>\AppData\Roaming\Perpetual\*.env on Windows

    Files are loaded in alphabetical order within each directory. Values loaded earlier take precedence over values loaded later.

  2. Operation-specific JSON configs

    Files like op_annotate.json, op_implement.json, op_doc.json, op_explain.json, and op_report.json contain prompts, regex patterns, tags, and other settings Perpetual uses when interacting with your source code. You can adjust these to change how Perpetual processes files and communicates with the LLM.

  3. project.json

    This file controls project-wide behavior, including:

    • project_files_whitelist: Regex patterns to include relevant files.
    • project_files_blacklist: Regex patterns to exclude files from processing.
    • project_test_files_blacklist: Regex patterns to exclude test files when operations are run without test inclusion.
    • files_to_md_code_mappings: Maps file path patterns to Markdown code-block languages.
    • filename_tags and filename_tags_rx: Tags and regexps used when sending and parsing filenames.
    • delete_tags and delete_tags_rx: Tags and regexps used when parsing file-deletion requests from LLM responses.
    • code_tags_rx: Regexps used to parse code blocks from LLM responses.
    • noupload_comments_rx: Regexps for detecting files marked as not uploadable.
    • Project index and description prompts: Prompt and response text used when providing project structure or project description context to the LLM.
    • Context-saving settings: Thresholds and percentages used to reduce LLM context usage for larger projects.
    • Incremental file-modification settings: Regexps and minimum file-size mappings used by implementation mode when generating compact search-and-replace changes.

  4. description.md.template

    This file is a template for an optional project description. To use it, copy or rename it to .perpetual/description.md and edit it for your project. The resulting description.md can provide additional context to operations such as implement, explain, doc, annotate, and report.

These configuration files can be committed to version control to share and track changes across your team. Local .env files should usually not be committed.

Files Not Intended for User Modification

The following are managed automatically by Perpetual and should not be edited manually:

  1. .annotations.json: Stores source-code annotations for your project. Updated via the annotate operation.
  2. .embeddings.msgpack: Stores source-code vector embeddings for your project. Updated via the embed operation.
  3. .stash/: Contains code backups created during operations. Managed by the stash operation.
  4. .message_log.txt*: Logs interactions with the LLM provider for debugging purposes, including rotated log files.

Obsolete Files and Directories

When running init, Perpetual checks the .perpetual directory for deprecated items left over from older versions. It does not remove them automatically; instead, it prints a warning so you can delete them manually.

  • Obsolete Files

    • filename_embed_regexp.json
    • filename_tags_regexps.json
    • filename_tags.json
    • no_upload_comment_regexps.json
    • output_tags_regexps.json
    • project_files_blacklist.json
    • project_files_to_markdown_lang_mappings.json
    • project_files_whitelist.json
    • reasonings_tags_regexps.json
    • reasonings_tags.json

  • Obsolete Directories

    • prompts