> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fliiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Audit Trails
> Automatic, privacy-preserving records of every agent run
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
| Location | Path | When 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](/guides/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
```json theme={null}
{
"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](/guides/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 Trails | Job Run Logs |
| ------------- | ------------------------------------------------------------------ | -------------------------------------------------- |
| **Scope** | Every agent run (REPL, TUI, single-shot, jobs) | Scheduled jobs only |
| **Location** | `~/.fliiq/audit/` or `.fliiq/audit/` | `.fliiq/jobs//runs/` |
| **Content** | Conversation structure with entries, tool calls, warnings | Summary: status, duration, iterations, final text |
| **Retention** | Unlimited (manual cleanup) | Last 50 runs (auto-pruned) |
| **Access** | `fliiq audit list`, `fliiq audit show `, or read JSON directly | `fliiq job logs `, `fliiq job output ` |
| **Purpose** | Debugging, compliance, understanding agent behavior | Monitoring job health and output |
## Reviewing Audit Trails
Use the `fliiq audit` CLI to browse and inspect runs without touching JSON files directly.
```bash theme={null}
fliiq audit list # Tabular view: time, ID, prompt, iterations, tokens, model
fliiq audit list -n 50 # Show more entries (default: 20)
fliiq audit show # 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.
```bash theme={null}
fliiq audit list
```
```bash theme={null}
fliiq audit show a1b2c3d4e5f6
```
```bash theme={null}
grep -l "WARNING" ~/.fliiq/audit/*.json
```
```bash theme={null}
jq '[.entries[].tool_calls[] | .name] | unique' ~/.fliiq/audit/FILENAME.json
```
```bash theme={null}
# Delete audit files older than 30 days
find ~/.fliiq/audit/ -name "*.json" -mtime +30 -delete
```
Understand what Fliiq protects and best practices for safe usage.
Set up scheduled automations with run logs and per-job memory.