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. These paths can be absolute, relative to the current working directory, or relative to the project root (where .aicodec/config.json is located).
  • 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.

• "plugins": [".zip=unzip -l {file}"]

  • A list of strings defining external scripts to process specific file types. Each string is in the format ".ext=command {file}".
  • For more details, see Plugins.

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: .