vibelens 1.0.1

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!

---

Your AI coding agents run hundreds of tool calls, burn thousands of tokens, and you have no idea what happened. VibeLens changes that.

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

No Python, no pip, nothing to set up first. The script installs uv (a single binary), fetches VibeLens, and opens it in your browser.

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

One install. Reads local logs. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw out of the box.

Features

Feature	Description
Session visualization	Step-by-step timeline with tool calls, thinking, and sub-agents
Dashboard analytics	Usage heatmaps, cost breakdowns, and per-project stats
Productivity tips (needs LLM key or Agent)	Detects recurring frustration patterns and suggests concrete fixes
Personalization (needs LLM key or Agent)	Retrieve, customize, and evolve reusable skills from your real sessions
Session sharing	Share sessions via one-click links
Multi-agent support	Claude Code, Codex CLI, Gemini CLI, OpenClaw with auto-detection

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/

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.

Quick Start

One-liner (recommended)

Zero prerequisites: no Python, no pip. The commands below install uv first, then run VibeLens.

# 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

VibeLens starts on http://localhost:12001 and your browser opens automatically. Change it with --port (for example, vibelens serve --port 8080).

Pick your path

Your situation	Command
Nothing installed (recommended)	one-liner above
Already have Python 3.10+	pip install vibelens && vibelens serve
Prefer the npm workflow (Python also required)	npx @chats-lab/vibelens serve
Want to hack on VibeLens	developer setup

What happens on first run

1. Your browser opens to http://localhost:12001.
2. If you have Claude Code, Codex CLI, Gemini CLI, or OpenClaw sessions, VibeLens auto-detects them from ~/.claude/, ~/.codex/, ~/.gemini/, or ~/.openclaw/.
3. Otherwise, bundled example sessions (recipe-book) show up so you can look around.
4. Productivity Tips and Personalization need a language-model API key. Optional; configure later in Settings.

pip (if you already have Python 3.10+)

pip install vibelens
vibelens serve

Check your version first with python3 --version. Need Python? See docs/INSTALL.md.

uv (run without a permanent install)

uvx vibelens serve

This fetches VibeLens into uv's cache and runs it without a global install. The one-liner above calls this under the hood.

npm (if you already have Python and prefer the npm workflow)

VibeLens is a Python app with an npm wrapper for convenience. The wrapper still requires Python 3.10+ and an installed vibelens package. Use this when you already have both and want npx/npm ergonomics.

npx @chats-lab/vibelens serve

Or install globally: npm install -g @chats-lab/vibelens.

Developer setup

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

Configuration

YAML configuration with environment variable overrides (VIBELENS_*). See config/vibelens.example.yaml for all options.

# Use a config file
vibelens serve --config config/self-use.yaml

# Override host/port
vibelens serve --host 0.0.0.0 --port 8080

Troubleshooting

Top issues. For the full list, see docs/INSTALL.md.

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