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

LocationPathWhen Used
Global~/.fliiq/audit/Default for all runs
Project.fliiq/audit/When a project-level .fliiq/ exists (takes precedence)
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: 
YYYYMMDD_HHMMSS_{12-char-id}.json
Example: 20260305_143022_a1b2c3d4e5f6.json

​
Example audit trail

{
  "id": "a1b2c3d4e5f6",
  "prompt": "what time is it in Tokyo",
  "entries": [
    {
      "timestamp": "2026-03-05T14:30:22.000000Z",
      "role": "user",
      "content_summary": "what time is it in Tokyo",
      "tool_calls": [],
      "tool_results": []
    },
    {
      "timestamp": "2026-03-05T14:30:23.000000Z",
      "role": "assistant",
      "content_summary": "I'll check the current time in Tokyo for you.",
      "tool_calls": [
        {
          "id": "toolu_01ABC",
          "name": "get_current_time",
          "input_keys": ["timezone"]
        }
      ],
      "tool_results": []
    },
    {
      "timestamp": "2026-03-05T14:30:24.000000Z",
      "role": "user",
      "content_summary": "",
      "tool_calls": [],
      "tool_results": [
        {
          "tool_use_id": "toolu_01ABC",
          "content_preview": "2026-03-06 00:30:24 JST (Asia/Tokyo)"
        }
      ]
    },
    {
      "timestamp": "2026-03-05T14:30:25.000000Z",
      "role": "assistant",
      "content_summary": "It's currently 12:30 AM on March 6, 2026 in Tokyo (JST, UTC+9).",
      "tool_calls": [],
      "tool_results": []
    }
  ],
  "final_text": "It's currently 12:30 AM on March 6, 2026 in Tokyo (JST, UTC+9).",
  "total_iterations": 2,
  "stop_reason": "end_turn",
  "started_at": "2026-03-05T14:30:22.000000Z",
  "completed_at": "2026-03-05T14:30:25.000000Z",
  "warnings": []
}

​
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: 
assistant entry:
  tool_calls[].id   = "toolu_01ABC"       ← correlation ID
  tool_calls[].name = "get_current_time"   ← the actual tool

user entry (next):
  tool_results[].tool_use_id    = "toolu_01ABC"   ← same ID → this is the result
  tool_results[].content_preview = "2026-03-06..." ← what the tool returned

​
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: 
WARNING: Tasks were marked complete but no execution tools
(shell, write_file, edit_file) were used.
The agent may have confabulated results.
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:
Audit TrailsJob Run Logs
ScopeEvery agent run (REPL, TUI, single-shot, jobs)Scheduled jobs only
Location~/.fliiq/audit/ or .fliiq/audit/.fliiq/jobs/<name>/runs/
ContentConversation structure with entries, tool calls, warningsSummary: status, duration, iterations, final text
RetentionUnlimited (manual cleanup)Last 50 runs (auto-pruned)
Accessfliiq audit list, fliiq audit show <id>, or read JSON directlyfliiq job logs <name>, fliiq job output <name>
PurposeDebugging, compliance, understanding agent behaviorMonitoring job health and output

​
Reviewing Audit Trails

Use the fliiq audit CLI to browse and inspect runs without touching JSON files directly. 
fliiq audit list                    # Tabular view: time, ID, prompt, iterations, tokens, model
fliiq audit list -n 50              # Show more entries (default: 20)
fliiq audit show <id>               # Full detail for a specific run
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

fliiq audit list
2

Inspect a specific run

fliiq audit show a1b2c3d4e5f6
3

Find runs with warnings (raw JSON)

grep -l "WARNING" ~/.fliiq/audit/*.json
4

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

jq '[.entries[].tool_calls[] | .name] | unique' ~/.fliiq/audit/FILENAME.json
5

Clean up old audit files

# Delete audit files older than 30 days
find ~/.fliiq/audit/ -name "*.json" -mtime +30 -delete

Security

Understand what Fliiq protects and best practices for safe usage.

Jobs

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