> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Session logs

# Session Logs

AgentUse automatically tracks every agent execution with detailed logs, providing full visibility into what happened during each run.

## Quick Start

```bash theme={"system"}
# List recent sessions
agentuse sessions

# View session details (partial ID match supported)
agentuse sessions show 01JFN8

# Show full tool inputs/outputs
agentuse sessions show 01JFN8 --full

# Export as JSON
agentuse sessions show 01JFN8 --json
```

## What Gets Tracked

Each session captures:

| Category     | Data                                                        |
| ------------ | ----------------------------------------------------------- |
| **Session**  | Agent name, model, MCP servers, project context, timestamps |
| **Messages** | User prompts, system prompts, token usage, cost, duration   |
| **Parts**    | Text output, tool calls, reasoning, step boundaries         |
| **Tools**    | Tool name, input, output, duration, errors                  |

## CLI Reference

### List Sessions

```bash theme={"system"}
agentuse sessions list [options]
agentuse sessions ls [options]
```

**Options:**

* `-s, --subagents` - Include subagent sessions
* `-n, --limit <n>` - Limit results (default: 10)
* `-j, --json` - Output as JSON
* `--all` - Show sessions across all projects
* `--project [path]` - Show sessions for a project path; defaults to the current project

**Example output:**

```
Sessions for current project: /Users/you/project

ID            STATUS     AGENT                 DATE
--------------------------------------------------
01JFN8K3M2P1  done       daily-reporter        Today 14:32
01JFN7XYZAB   suspended  seo-analyzer          Yesterday 09:15
01JFN6DEFGH   fail       code-reviewer         Mon 16:45
```

Session state is stored globally and partitioned by project. The CLI defaults to the current project; use `agentuse sessions list --all` when you are looking for a session but are not sure which project owns it.

### Show Session Details

```bash theme={"system"}
agentuse sessions show <id> [options]
```

**Options:**

* `-f, --full` - Show complete tool input/output (not truncated)
* `-j, --json` - Output as JSON
* `--project [path]` - Search a project path; defaults to the current project
* `--all-search` - Search all projects if not found in the selected project

**Example output:**

```
════════════════════════════════════════════════════════════
SESSION: 01JFN8K3M2P1NRXZW4Y5V6Q7B8
════════════════════════════════════════════════════════════

Agent:       daily-reporter
Description: Generate daily motivation quotes
Model:       anthropic:claude-sonnet-5
Started:     12/21/2025, 2:32:45 PM
MCP Servers: postgres

Project:     /Users/you/project
Working Dir: /Users/you/project

────────────────────────────────────────────────────────────
Task: Generate a daily motivation quote with an interesting fact
Tokens: 1523 (in: 892, out: 631)  Duration: 3.2s
Parts: text: 2, tool: 3

Output:
Here's today's motivation quote...

─── ✓ Postgres{query} (SELECT * FROM quotes...) 0.8s ────────
{"rows": [{"id": 1, "quote": "..."}]}
────────────────────────────────────────────────────────────

Generated your daily quote successfully!
```

### Show Storage Path

```bash theme={"system"}
agentuse sessions path
agentuse sessions path --project ../other-project
```

Shows where session data is stored for the current project.

## Subagent Sessions

Use `--subagents` to include subagent sessions in listings:

```bash theme={"system"}
agentuse sessions list --subagents
```

## Use Cases

### Debugging Failed Runs

```bash theme={"system"}
# Find recent failed session
agentuse sessions list | grep -i fail

# View full details with complete tool outputs
agentuse sessions show 01JFN8 --full
```

### Cost Tracking

```bash theme={"system"}
# Export sessions as JSON for analysis
agentuse sessions list --json > sessions.json

# Query costs with jq
cat sessions.json | jq '.[].cost'
```

### Audit Logging

Session logs provide a complete audit trail:

* What prompts were sent
* Which tools were called with what inputs
* What outputs were generated
* Token usage and costs
* Error details and stack traces

## Browse Sessions in the Browser

When `agentuse serve` is running, the same sessions are browsable as web pages:

* `/sessions` lists every run, newest first. Filter the list with `?agent=<id>`,
  `?trigger=scheduled|manual|slack|api`, and `?days=<n|all>`.
* `/sessions/<id>` is the per-session page: the full run log, and when the
  session is suspended on an approval gate, the approve / reject / comment and
  resume controls.

The `/agents` page opens each agent's detail hub, where you can inspect source,
recent runs, and start a run. Schedule rows also link to the agent detail hub;
last-run badges still link to the matching session page.

When the model streams its reasoning, it renders inline in the log as dimmed
"Reasoning" entries (the model's "why", subordinate to the visible answer it
precedes). This is on by default for reasoning-capable OpenAI models; for Claude
it requires opting into extended thinking. See
[model configuration](/guides/model-configuration#provider-options) for the
`openai.reasoningSummary` and `anthropic.thinking` options.

```bash theme={"system"}
agentuse serve
open http://127.0.0.1:12233/sessions
```

On an exposed host these pages require the API key, or a per-session token on the
session page link. See [Approval Gates](/guides/approval-gates#auth-and-the-session-token).

## Related

* [Session Storage Reference](/reference/session-storage) - Directory structure and data schemas
* [Environment Variables](/reference/environment-variables#storage) - Configure storage location with `XDG_DATA_HOME`