Layman

Agentic Insight and Oversight

• Monitor your AI assistants
• Explain their actions in Layman's Terms
• Analyze for risk, security, and safety automatically
• Evaluate "Drift" from user directives and CLAUDE.md (or AGENTS.md) instructions
• Visualize and explore live activity in a dashboard, logs, or flowchart
• Record and Bookmark sessions including user prompts and agent responses
  • Opt-in required
  • PII filtered by default

When AI coding assistants like Claude Code, Codex, OpenCode, Mistral Vibe, or Cline help you build software, they do it by reading your files, writing code, and performing dozens of actions per session.

Layman is a dashboard that explains exactly what your AI assistants are doing, in plain language, in your web browser. Understand and remember every file AI reads, every change AI makes, every command AI runs.

---

Supported Harnesses

• Claude Code
• OpenAI Codex
• Mistral Vibe
• OpenCode
• Cline

---

Screenshot

---

Features

Automated analysis

Layman can use an AI model to classify the risk level of each action, explain what it means in plain language, and flag anything that looks risky.

Drift monitoring

Layman continuously monitors AI agent sessions for two kinds of drift:

• Session goal drift - detects when the agent strays from what you asked it to do (scope creep, phantom file references, pattern breaks).
• Rules drift - detects when the agent violates rules defined in your project's CLAUDE.md files (wrong commands, forbidden actions, convention breaks). AGENTS.md files are also supported for harnesses besides Claude Code.

Drift scores are EMA-smoothed (alpha 0.3) to avoid reacting to one-off spikes. Scores map to four color levels (green → yellow → orange → red) with configurable thresholds. At orange the agent gets an in-context reminder; at red Layman can pause the agent entirely and require your approval to continue. Individual drift findings can be dismissed as false positives - dismissed items are fed back into the LLM prompt so they won't be re-flagged.

Flowchart view

Toggle between the event timeline and an interactive directed graph that shows how tool calls, agent responses, and user prompts connect. Pan and zoom with the mouse or keyboard, and click any node to open the Investigation panel for that event. Available for both live and historical sessions.

Session summary

Each session header shows an AI-generated plain-English summary of what the agent did, updated live as the session progresses and available in history. Click the summary to see previous versions and timestamps.

Session metrics

When connected to Claude Code, the dashboard shows a live metrics bar with model name, context window usage, cumulative session cost, token counts, lines changed, and rate limit warnings.

Tool approval

For Claude Code and Cline, Layman can intercept tool calls before they execute and ask for your approval.

Session History, Bookmarks, and Search

Sessions can optionally be recorded to a local SQLite database, capturing all user prompts, system responses, permission requests, tool calls, etc. Once captured, session data can be searched, bookmarked, and reviewed with a variety of session filters.

Searches cover the complete history of recorded sessions, with its own set of search filters.

File and URL access tracking

Layman tracks every file the agent reads or writes and every URL it fetches during a session, surfacing them in a dedicated access panel so you can see exactly what was touched.

PII filter

All logged events are automatically scanned for personally identifiable information (email addresses, API keys, passwords, credit card numbers, etc.) and redacted before storage. Toggle in Settings → Session Recording → PII Filter.

Setup Wizard

Intial setup is aided by a complete setup wizard to walk through some available configuration options.

---

Dashboard Icons

Icon	Meaning
⚡	Tool call pending approval
✅	Tool call approved
❌	Tool call denied
⏭	Tool call delegated (auto-allowed)
✓	Tool call completed
✗	Tool call failed
🔐	Permission request (Claude asking for explicit approval)
💬	User prompt
🤖	Agent response
-	Agent stopped
🟢	Session started
⬜	Session ended
🔔	Notification
🔀	Subagent started / stopped
⚠	Stop failure
📦	Context compacted
📋	Elicitation (structured input request)
🔍	Analysis result
📐	Drift check completed
🚨	Drift alert (level changed)

Agent badges in session cards:

• CC = Claude Code
• CX = Codex
• OC = OpenCode
• MV = Mistral Vibe
• CL = Cline

---

Setup

Requires Docker.

Quick Start

macOS / Linux - one command downloads the config and starts Layman:

mkdir -p ~/layman && curl -fsSL https://raw.githubusercontent.com/castellotti/layman/main/docker-compose.ghcr.yml -o ~/layman/docker-compose.yml && docker compose -f ~/layman/docker-compose.yml up -d

Windows (PowerShell):

md -Force "$env:USERPROFILE\layman"; Invoke-WebRequest "https://raw.githubusercontent.com/castellotti/layman/main/docker-compose.ghcr.yml" -OutFile "$env:USERPROFILE\layman\docker-compose.yml"; $env:HOME=$env:USERPROFILE; docker compose -f "$env:USERPROFILE\layman\docker-compose.yml" up -d

Windows / WSL2: If you're running Docker from a WSL2 terminal, use the macOS/Linux command above instead.

Then open http://localhost:8880. On first visit, a modal lists any AI agent clients detected on your system - toggle the ones you want and click Accept to install hooks.

If you've cloned the repo, make start does the same thing (macOS/Linux).

To update to the latest image:

# macOS / Linux
docker compose -f ~/layman/docker-compose.yml pull && docker compose -f ~/layman/docker-compose.yml up -d

# Windows (PowerShell)
$env:HOME=$env:USERPROFILE; docker compose -f "$env:USERPROFILE\layman\docker-compose.yml" pull; docker compose -f "$env:USERPROFILE\layman\docker-compose.yml" up -d

To stop:

# macOS / Linux
docker compose -f ~/layman/docker-compose.yml down

# Windows (PowerShell)
docker compose -f "$env:USERPROFILE\layman\docker-compose.yml" down

A banner will appear in the dashboard if your hooks or commands are out of date after an update - click Update to refresh them.

---

Full Details

What gets mounted

Layman runs in Docker but needs read/write access to several directories on your host machine so it can install hooks and watch agent log files:

Mount	Purpose
~/.claude	Read/write Claude Code hooks, slash commands, and the StatusLine relay script
~/.config	Detect and write commands for XDG-based clients (e.g. OpenCode)
~/.vibe	Detect Mistral Vibe and tail its session log files for passive monitoring
~/Documents/Cline	Detect Cline and write hook scripts to ~/Documents/Cline/Hooks/
~/.codex	Detect Codex and write hook scripts and ~/.codex/hooks.json entries

Layman only writes inside these directories when you explicitly click Install in Settings. Nothing is written automatically on startup.

Port binding

The default config binds to 127.0.0.1:8880, so the dashboard is only reachable from your local machine. Do not change this to 0.0.0.0 unless you have a specific reason and understand the implications - Layman has no authentication.

AI analysis (optional)

Layman can use an AI model to classify the risk level of each action and explain it in plain language. To enable this, pass your API key when starting the container:

ANTHROPIC_API_KEY=your-key-here docker compose -f ~/layman/docker-compose.yml up -d

Supports Anthropic, OpenAI-compatible APIs, and LiteLLM. Auto-analysis and auto-explain can be configured independently in Settings → Analysis, with severity thresholds (All / Medium+ / High only) and detail level (Quick / Detailed).

Compose file reference

The compose file downloaded by the Quick Start command is docker-compose.ghcr.yml from this repo. You can review it before running, or substitute any fields (e.g. a pinned image tag instead of latest).

Windows: The compose file uses ${HOME} for volume paths. The PowerShell Quick Start command sets $env:HOME=$env:USERPROFILE so Docker Compose resolves these correctly - no manual editing needed. If you run docker compose commands later, prefix them with $env:HOME=$env:USERPROFILE; or set HOME persistently in your system environment variables.

---

Usage by agent

Claude Code

Sessions are not recorded by default. To opt a session in:

1. Start Claude Code in any project directory:

   claude

2. Type /layman inside the Claude Code session.

3. Claude runs an activation command. From that point on, all events flow to the dashboard.

You can activate multiple sessions across different projects - they all appear in the same dashboard.

Auto-activate: To skip the /layman step, go to Settings → Client Setup and toggle Auto-activate sessions on the Claude Code row. All new Claude Code sessions will be monitored automatically.

---

Codex

Codex uses shell-script hooks that Layman installs to ~/.codex/hooks/layman/ and registers in ~/.codex/hooks.json. Sessions are activated per-session by typing @layman in Codex.

Installation (first time or after a Layman update):

1. Ensure Codex is installed (codex binary on PATH or at /opt/homebrew/bin/codex).
2. Open the Layman dashboard → Settings → Client Setup → click Install next to Codex.
3. Layman writes hook scripts to ~/.codex/hooks/layman/, adds entries to ~/.codex/hooks.json, and enables the codex_hooks feature flag in ~/.codex/config.toml (required - hooks are disabled by default in Codex).

Usage:

1. Start Codex in any project directory:

   codex

2. Type @layman to activate monitoring for the session. Events will appear in the Layman dashboard.

Notes:

• Codex's hook system is an under-development feature. The installer enables it automatically via codex_hooks = true in ~/.codex/config.toml. You can also enable it manually with codex features enable codex_hooks.
• Codex supports 5 hook events: PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, and Stop. Features that require PermissionRequest or subagent hooks are not available.
• Tool approval/denial from the Layman UI is supported for PreToolUse events.
• Prompt submission from the Layman UI is not yet supported for Codex sessions.
• The hook scripts require jq on the host (/usr/bin/jq works); a sed fallback is used if jq is not available.

---

OpenCode

OpenCode requires a one-time plugin registration before first use.

1. Register the Layman plugin in your OpenCode config (~/.config/opencode/opencode.json):

   {
     "plugin": [
       "file:///absolute/path/to/layman/packages/opencode-plugin"
     ]
   }

2. Open the Layman dashboard → Settings → Client Setup → click Install next to OpenCode to install the /layman command for it.

3. Start OpenCode and type /layman to activate monitoring for the current session.

You can also send prompts and respond to questions directly from the Layman UI when an OpenCode session is active.

---

Mistral Vibe

Vibe has no hook or plugin system, so Layman monitors it passively by watching Vibe's session log files.

No activation step is needed. When the Layman server is running, any active Vibe session is automatically monitored. Events appear in the dashboard within a few seconds of each turn.

• Layman watches ~/.vibe/logs/session/ for new JSONL messages
• Sessions that started within the last 5 minutes are replayed from the beginning
• Sessions idle for more than 15 minutes are treated as ended

The /layman skill file is installed to ~/.vibe/skills/layman/ for informational purposes (it tells Vibe that Layman is watching), but invoking it is optional.

---

Cline (VS Code / IntelliJ)

Cline uses shell-script hooks that Layman installs to ~/Documents/Cline/Hooks/. After installation, sessions are not monitored by default - you activate per session using the /layman workflow.

Installation (first time or after a Layman update):

1. Ensure Cline is installed in VS Code or IntelliJ.
2. Open the Layman dashboard → Settings → Client Setup → click Install next to Cline.
3. Layman writes hook scripts to ~/Documents/Cline/Hooks/ and a workflow file to ~/Documents/Cline/Workflows/layman.md.

Activating a session:

1. Open Cline in VS Code or IntelliJ and start a task.
2. Make sure you are in Act mode (not Plan mode) - the activation requires running a shell command.
3. Type /layman (or /layman.md) in the Cline chat.
4. Cline runs echo "layman:activate" and confirms activation.

From that point on, all tool calls in that workspace are monitored. If you switch between Plan and Act modes, monitoring automatically resumes when you return to Act mode - you do not need to run /layman again.

Notes:

• Tool approval/denial from the Layman UI is supported - Cline will pause and wait up to 25 seconds for your decision before auto-allowing.
• Prompt submission from the Layman UI is not supported (Cline has no inbound HTTP API).
• Agent responses are captured when Cline uses attempt_completion; purely conversational inline replies may not appear.

---

Adding a new AI client

If you install a supported client after Layman is already running:

1. Install the client as normal.
2. Open the Layman dashboard at http://localhost:8880.
3. Go to Settings (gear icon) → Client Setup.
4. Click Install next to the newly detected client - Layman writes its hooks and commands.

No container restart required.

---

Stopping Layman

# macOS / Linux
docker compose -f ~/layman/docker-compose.yml down

# Windows (PowerShell)
docker compose -f "$env:USERPROFILE\layman\docker-compose.yml" down

If you used make start, you can also run make stop.