Skip to content

Configuration Reference

The aicodec workflow is controlled by the .aicodec/config.json file, which is created when you run aicodec init. This file allows you to customize the tool's behavior for your specific project.

While command-line flags can override these settings for a single run, editing the config file is the best way to set persistent project-wide defaults.

File Structure

The config.json is organized into sections that correspond to the main commands:

{
    "aggregate": {
        // Settings for the 'aggregate' command
    },
    "prompt": {
        // Settings for the 'prompt' command
    },
    "prepare": {
        // Settings for the 'prepare' command
    },
    "apply": {
        // Settings for the 'apply' command
    }
}

aggregate Section

This section controls which files are collected into context.json.

  • "directories": ["src", "tests"]

    • A list of root directories to scan for files. . refers to the project root.
    • Default: ["."]
  • "use_gitignore": true | false

    • If true, aicodec will respect the rules in your project's .gitignore file.
    • Default: true
  • "include": ["src/api/**", "*.conf"]

    • A list of gitignore-style glob patterns to always include, even if they are excluded by other rules (like .gitignore).
  • "exclude": ["dist/", "**/*.log"]

    • A list of gitignore-style glob patterns to always exclude. Note that .git/** and .aicodec/** are always excluded by default.

Note on Precedence: The include rules have higher precedence than exclude rules (including .gitignore). If a file matches both an include and an exclude pattern, it will be included.


prompt Section

This section controls how the LLM prompt is generated by aicodec prompt.

  • "output_file": ".aicodec/prompt.txt"

    • The default path where the generated prompt file is saved.
    • Default: .aicodec/prompt.txt
  • "tech_stack": "Python/FastAPI"

    • A string describing your project's language or tech stack. This is inserted into the prompt template to give the LLM better context.
    • Default: (none)
  • "minimal": true | false

    • If true, a smaller, more concise prompt template is used. This reduces token count but may provide the LLM with less guidance.
    • Default: false
  • "include_code": true | false

    • If false, the code from context.json will not be included in the prompt. Useful for asking general questions.
    • Default: true
  • "include_map": true | false

    • If true, the prompt command will include the .aicodec/repo_map.md file by default. This can be overridden by the --include-map or --exclude-map flags.
    • Default: false
  • "clipboard": true | false

    • If true, the prompt command will copy the generated prompt to the clipboard by default instead of writing it to a file.
    • Default: false

prepare Section

This section controls how aicodec prepare handles the LLM's response.

  • "changes": ".aicodec/changes.json"

    • The path where the validated JSON response from the LLM is stored, ready for the apply step.
    • Default: .aicodec/changes.json
  • "from_clipboard": true | false

    • If true, the prepare command will attempt to read the LLM's response directly from the clipboard by default.
    • Default: false

apply Section

This section controls the target directory for applying changes.

  • "output_dir": "."
    • The root directory where file changes will be applied. In most cases, this should be your project root.
    • Default: .