vibelens 1.0.7

Agent Trajectory visualization and analysis platform

VibeLens

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

Live Demo · Quick Start · Supported Agents · PyPI · Changelog

---

Let your agent know you better!

---

Sound familiar?

• Your agent is powerful, but it doesn't know you.
• So many agent skills out there. Which ones actually fit your workflow?
• Your agent keeps repeating the same mistakes.
• Running an agent team but no idea what they're doing.

Why VibeLens:

• Personalization: Turns your real sessions into reusable skills your agent can load.
• Productivity tips: Spots where the agent got stuck or went off track, and tells you how to fix it.
• Session visualization: Replays what actually happened, step by step.
• Multi-agent support: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Hermes with auto-detection
• Dashboard analytics: Show usage heatmaps, cost breakdowns, and per-project stats

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

Quick Start

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

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

Run the one-liner:

# 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

After installation, start VibeLens any time with:

vibelens serve

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

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

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
   

Prefer a manual install?

Your situation	Command
Have uv	uv tool install vibelens && uv tool update-shell (then open a new terminal and run vibelens serve)
Have Python 3.10+	pip install vibelens && vibelens serve
Want to run without installing	uvx vibelens serve
Prefer the npm workflow (Python also required)	npx @chats-lab/vibelens serve
Want to hack on VibeLens	developer setup

The npm wrapper requires Python 3.10+ and an installed vibelens package. It's a convenience layer, not a replacement. Install globally with npm install -g @chats-lab/vibelens if you prefer.

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

Supported Agents

Agent	Format	Data Location
Claude Code	JSONL	~/.claude/projects/
Codex CLI	JSONL	~/.codex/sessions/
Gemini CLI	JSON	~/.gemini/tmp/
OpenClaw	JSONL	~/.openclaw/agents/
Hermes	JSONL	~/.hermes/sessions/

VibeLens auto-detects the agent format. Just point it at your session directory and it works.

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 uv (one-liner picked this path, or you ran `uv tool install`)
uv tool uninstall vibelens

# Installed with pip
pip 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.

To donate, upload your data, select the sessions you want to share, and click the Donate Data button.

Contributing

Contributions are welcome! Please ensure code passes ruff check and pytest before submitting.

License

MIT