VibeLens

See what your AI coding agents are actually doing.
Replay. Analyze. Evolve.

Live Demo · Quick Start · Supported Agents · Screenshots · Donate Data · Human Study · PyPI · npm · Changelog

English · 中文

---

Let your agent know you better!

---

VibeLens is an open-source tool that visualize and analyze your AI agent sessions. It reads your existing session logs, and supports 11 local agents out of the box (Claude Code, Codex, Gemini, Cursor, and more). Analyze every session, get paste-ready CLAUDE.md actions for productivity tips, and distill recurring workflows into reusable skills.

Just want a look? Try the live demo. Nothing to install.

Quick Start

Requirement: either uv (preferred) or Python 3.10+.

# macOS / Linux. Paste into Terminal.
curl -LsSf https://raw.githubusercontent.com/CHATS-lab/VibeLens/main/install.sh | sh

# Windows. Paste into PowerShell.
irm https://raw.githubusercontent.com/CHATS-lab/VibeLens/main/install.ps1 | iex

Have Python 3.10+:

pip install vibelens && vibelens serve

Have uv:

uv tool install vibelens && vibelens serve

Run without installing:

uvx vibelens serve

Prefer npm (Python also required):

npx @chats-lab/vibelens serve

Run vibelens serve to start it again.

VibeLens opens on http://localhost:12001 and your browser launches automatically.

Change the port with --port (for example, vibelens serve --port 8080). Press Ctrl+C to stop.

Full install guide and troubleshooting: docs/INSTALL.md.

Don't have uv or Python yet?

Install uv (recommended, single binary, no Python needed):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# or: brew install uv

# Windows
irm https://astral.sh/uv/install.ps1 | iex
# or: winget install --id=astral-sh.uv -e

Install or upgrade Python 3.10+ (alternative):

# macOS
brew install python@3.12

# Debian / Ubuntu
sudo apt update && sudo apt install -y python3 python3-pip

# Fedora / RHEL
sudo dnf install -y python3 python3-pip

# Arch
sudo pacman -S python python-pip

# Windows
winget install --id Python.Python.3.12 -e
# or: choco install python

Official downloads: python.org · uv docs

vibelens: command not found after a uv install?

This happens when uv's tool bin directory isn't on your shell's PATH. The installer tries to fix this automatically, but the change only takes effect in new terminals.

Try one of:

1. Open a new terminal and run vibelens serve again.
2. Run the PATH fix manually, then reopen your terminal:

   uv tool update-shell

3. Add it to PATH yourself (replace the path with what uv tool dir --bin prints):

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
   source ~/.zshrc

4. Skip the shim entirely and always use:

   uvx vibelens serve

Supported Agents

Agent	Format	Data Location
Claude Code	JSONL	~/.claude/projects/
Codex	JSONL + SQLite	~/.codex/sessions/
Gemini CLI	JSON	~/.gemini/tmp/
Cursor	SQLite	~/.cursor/chats/
Copilot CLI	JSONL	~/.copilot/session-state/
Kilo Code	SQLite	~/.local/share/kilo/
Kiro	JSONL + JSON	~/.kiro/sessions/
OpenCode	SQLite	~/.local/share/opencode/
OpenClaw	JSONL	~/.openclaw/agents/
Hermes	JSONL + SQLite	~/.hermes/sessions/
CodeBuddy	JSONL	~/.codebuddy/projects/
Claude.ai (web)	exported JSON	drag-and-drop upload

VibeLens auto-detects all your agent directories.

Screenshots

Session Visualization & Dashboard Analytics

Session Visualization Step-by-step timeline with messages, tool calls, thinking blocks, and sub-agent spawns.

Dashboard Analytics Usage heatmaps, cost breakdowns by model, and per-project drill-downs.

Productivity Tips & Personalization

Productivity Tips Detect friction patterns and get concrete suggestions to improve your workflow.	Skill Recommendation Match workflow patterns to pre-built skills from the catalog.
Skill Customization Generate new SKILL.md files tailored to your session patterns.	Skill Evolution Evolve installed skills with targeted edits based on your real sessions.

Developer setup

git clone https://github.com/CHATS-lab/VibeLens.git
cd VibeLens
uv sync --extra dev
uv run vibelens serve

Uninstall

Match the command to how you installed:

# Installed with pip
pip uninstall vibelens

# Installed with uv (one-liner picked this path, or you ran `uv tool install`)
uv tool uninstall vibelens

# Installed globally via npm
npm uninstall -g @chats-lab/vibelens

VibeLens stores logs and cached data under ~/.vibelens/ and logs/ in the working directory. Remove them if you want a clean slate:

rm -rf ~/.vibelens

Data Donation

VibeLens supports donating your agent session data to advance research on coding agent behavior. Donated sessions are collected by CHATS-Lab (Conversation, Human-AI Technology, and Safety Lab) at Northeastern University.

How to donate

• Live demo: drag-and-drop a session file, preview it, then click Donate Data.
• Local install: VibeLens auto-detects your existing sessions. Pick the ones you want to share, then click Donate Data.

Northeastern University researchers are recruiting active AI coding agent users for a paid study (~20 min, up to $100). See docs/HUMAN_STUDY.md for details.

Contributing

Contributions are welcome!

1. New parsers: read docs/spec/parsers/add-parser-skill.md before writing code. Each existing parser's per-format spec lives alongside it in docs/spec/parsers/<agent>.md.

License

This project is licensed under the MIT License. See the LICENSE file for details.