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

# Live Logs

> Real-time log streaming for debugging agents and monitoring activity.

## Overview

The **Live Logs** feature streams the runner log directly to your browser using server-sent events (SSE). Each agent's logs are filterable from its detail page.

Logs capture everything the runner produces for a given agent: startup events, incoming Slack messages, AI backend calls, MCP tool invocations, memory writes, and errors.

## Accessing logs

1. Open an agent from the dashboard
2. Click the **Logs** tab on the agent detail page

Logs begin streaming immediately. New log lines appear in real time as the agent processes messages.

## Log levels

SlackHive uses structured logging (Winston) with four levels:

| Level   | Color   | When it appears                                                                                |
| ------- | ------- | ---------------------------------------------------------------------------------------------- |
| `error` | Red     | Unrecoverable failures: Slack auth errors, AI backend exceptions, DB connection failures       |
| `warn`  | Yellow  | Recoverable issues: stale session retries, MCP server startup failures, malformed memory files |
| `info`  | Default | Normal operation: agent started, message received, memory synced, session created              |
| `debug` | Dimmed  | Verbose detail: SDK options, session directory paths, MCP server config                        |

Use the **level filter** in the log viewer to show only the levels you care about. In production, `info` and above is usually sufficient. Enable `debug` when diagnosing unexpected behavior.

## Log search

The log viewer includes a search bar. Type any string to filter log lines to those containing that text. Useful for finding:

* Log lines for a specific user ID (`U012AB3CD`)
* Log lines for a specific session (`session_key`)
* All memory sync events (`memory synced`)
* All MCP-related activity (`mcp__`)

## What you'll see in logs

### Agent startup

```
[info] Agent started { mcpServers: ['redshift', 'filesystem'] }
[info] Memory watcher started { memoryDir: '~/.slackhive/agents/data-bot/memory' }
[debug] MCP servers configured { servers: ['redshift'] }
```

### Incoming message

```
[info] Streaming query { sessionKey: 'U012-C456-1234.5678', resume: 'new', cwd: '...' }
[debug] Session work dir created { sessionKey: '...', sessionDir: '...' }
[debug] Session created { sessionKey: '...', sessionId: 'sess_...' }
```

### Memory write

```
[info] Memory synced to DB { filePath: '...', name: 'kai_preferences', type: 'user' }
[info] Memory synced from session { file: 'user_kai_preferences.md', name: 'kai_preferences', type: 'user' }
```

### MCP tool use

MCP tool invocations are rendered in the Slack response as tool-use labels. In logs, you'll see the MCP proxy management:

```
[info] MCP proxy started { server: 'redshift', port: 14050 }
```

### Session cleanup

```
[info] Cleaned up stale sessions { count: 2 }
```

### Errors

```
[error] AI backend query failed { sessionKey: '...', backend: 'codex', error: 'No conversation found' }
[warn] Stale session, retrying as new { sessionKey: '...', staleSessionId: 'sess_...' }
[error] MCP proxy start failed { server: 'broken-mcp', error: 'Command not found' }
```

## Debugging common issues

### Agent not responding in Slack

Check for:

* `[error]` lines mentioning Slack token or connection errors
* `[warn]` lines about missing or invalid credentials
* Whether the agent shows **Running** status in the dashboard

### MCP tools not working

Check for:

* `[error] MCP proxy start failed` - the server binary is not found or not executable
* `[warn] MCP envRef not found` - the referenced env var key doesn't exist in the encrypted store
* `[warn] Memory dir watcher error` - filesystem permission issues

### Memory not persisting

Check for:

* `[warn] Could not parse memory file` - the agent wrote a memory file with invalid frontmatter
* Absence of `[info] Memory synced to DB` lines - the watcher may not have detected the file

### Stale session errors

Stale sessions can occur after a runner restart or backend session interruption. SlackHive retries automatically as a new session. You'll see:

```
[warn] Stale session, retrying as new
```

This is normal after restarts and resolves itself automatically.

## Tailing logs from the CLI

For shell access to runner logs, use the CLI:

```bash theme={null}
slackhive logs
```

This tails `~/.slackhive/logs/runner.log` live. Ctrl-C to stop. To print without following:

```bash theme={null}
tail -n 100 ~/.slackhive/logs/runner.log
```

To filter to a single agent, each log line is JSON - pipe through `grep`:

```bash theme={null}
slackhive logs | grep '"agent":"data-bot"'
```