Analyze File Tool

The analyze_file tool reads a file from disk, submits its contents together with a short natural-language prompt to an LLM agent, and returns the analysis result.

Quick start

Ensure your settings declare an LLM and point the tool at it:

# ~/.config/aifred-tk/settings.yml
llms:
  my-llm:
    provider: openai
    model: gpt-4o-mini

tools:
  analyze_file:
    llm:
      type: ref
      ref: my-llm

Then invoke the tool:

aifred-tk analyze_file --file-path src/main.py --prompt "briefly describe each function"

Configuration

LLM setting

The tools.analyze_file.llm key is required. It accepts a reference to a named LLM or an inline definition. See LLMs for the full format.

# Reference a named LLM
tools:
  analyze_file:
    llm:
      type: ref
      ref: my-llm

# Or define inline
tools:
  analyze_file:
    llm:
      type: custom
      provider: ollama
      model: gemma4:e4b
      host: 127.0.0.1
      port: 11434

Enabling and disabling

The tool respects the standard enabled flag:

tools:
  analyze_file:
    enabled: false

Usage

CLI

aifred-tk analyze_file --file-path PATH --prompt TEXT [--output-file PATH]

Option	Description
--file-path PATH	Absolute or relative path to the file to analyse. Required.
--prompt TEXT	Short description of the desired analysis (max 500 characters). Required.
--output-file PATH	Optional path to write the result. When omitted the result is returned inline.

MCP

The tool is registered automatically when the MCP server starts. Invoke it as aifred_analyze_file with the required file_path and prompt arguments, and an optional output_file argument.

Output

Inline result (status: ok)

Returned when output_file is not set:

{
  "status": "ok",
  "analysis": "The file defines three public functions: ..."
}

Written to file (status: written)

Returned when output_file is set and the write succeeds:

{
  "status": "written",
  "output_file": "/tmp/analysis.txt",
  "analysis": "The file defines three public functions: ..."
}

Error (status: error)

{"status": "error", "message": "File not found: src/missing.py"}

{"status": "error", "message": "File exceeds the 1 MB size limit (2097152 bytes)."}

{"status": "error", "message": "File is ignored by .aiignore: secrets/db.env"}

{"status": "error", "message": "Agent error: <provider error details>"}

Limits and security

• .aiignore — before reading any file, analyze_file checks for .aiignore files from the target path up to the filesystem root. Files matching any pattern are refused immediately and never read or sent to the LLM.
• Size limit — files larger than 1 MB (1,048,576 bytes) are rejected before any LLM call. Use output_file to persist results for large projects split across many files.
• Encoding — files are read as UTF-8 with errors='replace', so binary or mixed-encoding files are handled without crashing; undecodable bytes appear as the replacement character.
• Prompt injection isolation — both the analysis prompt and the file contents are wrapped in XML isolation markers (<analysis_request> and <file_content>) before being forwarded to the agent. This prevents embedded instructions inside the file from acting as agent directives.