vibelens

VibeLens

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

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

VibeLens Comic: Understand your agent. Teach it. Master it.

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:

Open a new terminal and run vibelens serve again.
Run the PATH fix manually, then reopen your terminal:
```
uv tool update-shell
```

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

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

Metadata

Release files for vibelens 1.0.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vibelens 1.0.8
File	Size	Uploaded
vibelens-1.0.8.tar.gz	29.6 MB	Apr 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for vibelens 1.0.8
File	Interpreter	ABI	Platform	Reset
vibelens-1.0.8-py3-none-any.whl 16.1 MB Apr 28, 2026	Python 3	none	any	Details

Total release size: 45.7 MB

Release files / vibelens-1.0.8.tar.gz

Download URL	vibelens-1.0.8.tar.gz
Size	29.6 MB
Tags	Source
SHA-256 checksum How to use checksums	`991bdedd17a405da1c3e27d20bc2f0e82a70053ebeede7da81792fe7e9b1bf81`
BLAKE2b-256 checksum How to use checksums	`ecd845ceb4ab452da21ded0e5eec9897c3e79abf0adf4d0ddde5ac52320ca986`
Upload date	Apr 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/CHATS-lab/VibeLens
Publishing commit: github.com/CHATS-lab/VibeLens/tree/b2e0254b4db6bd740bdf575b5e3ddca8a660a432

Workflow

Publishing configuration: github.com/CHATS-lab/VibeLens/blob/b2e0254b4db6bd740bdf575b5e3ddca8a660a432/.github/workflows/publish.yml
Publishing logs: github.com/CHATS-lab/VibeLens/actions/runs/25030696321/attempts/1

Artifact

Subject: vibelens-1.0.8.tar.gz
SHA-256 checksum: 991bdedd17a405da1c3e27d20bc2f0e82a70053ebeede7da81792fe7e9b1bf81 Verifying attestations

Release files / vibelens-1.0.8-py3-none-any.whl

Download URL	vibelens-1.0.8-py3-none-any.whl
Size	16.1 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`7e17bd75fb9caa3e0cdb32e5c910fc49622096f688b83ee9623bba86c0ecdbbc`
BLAKE2b-256 checksum How to use checksums	`7ddc5248fa5884d60c64dbc036bc9327451f8cd8fd1d8351a8babc3defc3701d`
Upload date	Apr 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/CHATS-lab/VibeLens
Publishing commit: github.com/CHATS-lab/VibeLens/tree/b2e0254b4db6bd740bdf575b5e3ddca8a660a432

Workflow

Publishing configuration: github.com/CHATS-lab/VibeLens/blob/b2e0254b4db6bd740bdf575b5e3ddca8a660a432/.github/workflows/publish.yml
Publishing logs: github.com/CHATS-lab/VibeLens/actions/runs/25030696321/attempts/1

Artifact

Subject: vibelens-1.0.8-py3-none-any.whl
SHA-256 checksum: 7e17bd75fb9caa3e0cdb32e5c910fc49622096f688b83ee9623bba86c0ecdbbc Verifying attestations