Skip to main content
Every Fliiq agent run — whether single-shot, REPL, TUI, or scheduled job — automatically produces a structured audit trail. These trails are stored locally on your machine, never transmitted anywhere, and designed to capture what the agent did without exposing sensitive data.

​
How It Works

  1. An agent run starts (any mode: autonomous, supervised, or plan)
  2. When the run completes, Fliiq walks the message history
  3. A structured summary is extracted — content is truncated, input values are omitted
  4. The summary is saved as a JSON file to the audit directory
Audit trail saving is non-fatal. If the audit directory is unwritable or an error occurs, the failure is silently logged and the agent run is unaffected.

​
Where Audit Trails Are Stored

Resolution follows the same project > global precedence as other Fliiq resources. See Configuration — Config Resolution for details.

​
What’s Captured

Each audit trail records:
  • id — 12-character hex identifier
  • prompt — the original user prompt
  • started_at / completed_at — UTC timestamps
  • total_iterations — number of assistant turns
  • stop_reason — why the run ended: end_turn, max_iterations, cancelled, etc.
  • model — the model name used for the run (e.g. claude-sonnet-4-6)
  • provider — the LLM provider (anthropic, openai, gemini)
  • input_tokens / output_tokens — token usage for the run
  • duration_ms — total wall-clock time per iteration
Each message in the conversation becomes an entry with:
  • timestamp — when the message occurred (UTC)
  • role — user or assistant
  • content_summary — first 100–200 characters of the message content
  • tool_calls — list of tools invoked, recording only the tool name and input_keys (parameter names, not values)
  • tool_results — list of results, recording only the tool_use_id and a content_preview (first 100 characters)
final_text — the agent’s final response text, captured in full.
A list of warning strings detected during analysis, including confabulation detection results (see below).

​
File Format

Audit trails are saved as JSON with 2-space indentation. Files are named:
Example: 20260305_143022_a1b2c3d4e5f6.json

​
Example audit trail

​
Reading tool calls

The id field in tool_calls (e.g., toolu_0173a8f...) is an opaque identifier generated by the LLM API — it is not a tool name. The name field tells you which tool was actually invoked. To pair a tool invocation with its result, match tool_calls[].id to tool_results[].tool_use_id:

​
Confabulation Detection

After each run, Fliiq analyzes the audit trail for a common hallucination pattern: the agent claims tasks are complete but never actually executed them. The detection checks whether:
  1. The agent marked TODO items as done (via the todo tool with a status update)
  2. No execution tools (shell, write_file, edit_file) were called during the run
If this pattern is found, a warning is added:
Confabulation detection is a heuristic, not a guarantee. It catches the most common pattern — claiming work was done without executing tools — but cannot detect all forms of incorrect output. Always review agent results for critical tasks.

​
Privacy Design

Audit trails are designed to be useful without being invasive:
  • Summaries, not transcripts — Content is truncated to 100–200 characters, not stored in full
  • Input keys, not values — Tool call inputs record parameter names only (e.g., ["timezone"]), never the actual values passed
  • Content previews — Tool results store only the first 100 characters
  • Local-only — Audit files live on your machine and are never transmitted to any server
  • You control retention — Delete audit files anytime; there is no remote copy
Audit logs may still contain sensitive conversation snippets in the summaries. See Security for recommendations on handling sensitive data.

​
Audit Trails vs Job Run Logs

Scheduled jobs produce both an audit trail and a job run log. Here’s how they differ:

​
Reviewing Audit Trails

Use the fliiq audit CLI to browse and inspect runs without touching JSON files directly.
The list output shows a Rich table with columns for timestamp, run ID, prompt preview, iteration count, token usage, and model name. The show command renders the full conversation structure, tool calls, and any confabulation warnings.
1

List recent runs

2

Inspect a specific run

3

Find runs with warnings (raw JSON)

4

Check which tools were used in a run (raw JSON)

5

Clean up old audit files

Security

Understand what Fliiq protects and best practices for safe usage.

Jobs

Set up scheduled automations with run logs and per-job memory.