Contributing to AgentLens

July 3, 2026 · View on GitHub

Thanks for your interest in contributing to AgentLens! This guide will get you from zero to a running dev environment in under 15 minutes.

Prerequisites

ToolVersionCheck
Node.js20+node -v
pnpm10+pnpm -v
Python3.10+ (only for python-sdk)python3 --version

Getting Started

# 1. Fork & clone
git clone https://github.com/<your-username>/agentlens.git
cd agentlens

# 2. Install dependencies
pnpm install

# 3. Build all packages
pnpm build

# 4. Start dev servers (server + dashboard with hot reload)
pnpm dev

The server starts at http://localhost:3400 and the dashboard at http://localhost:5173 (proxied to the server).

Environment Setup

cp .env.example .env
# Edit .env with your settings — defaults work for local development

Monorepo Structure

packages/
├── core/          Shared types, schemas & utilities (@agentkitai/agentlens-core)
├── server/        Hono API server + SQLite backend (@agentkitai/agentlens-server)
├── dashboard/     React + Vite web dashboard (@agentkitai/agentlens-dashboard)
├── cli/           Command-line interface (@agentkitai/agentlens-cli)
├── sdk/           TypeScript SDK (@agentkitai/agentlens-sdk)
├── python-sdk/    Python SDK + auto-instrumentation (agentlensai)
└── mcp/           MCP tool server (@agentkitai/agentlens-mcp)

Development Workflow

Branch Naming

Use descriptive prefixes:

  • feat/short-description — new features
  • fix/short-description — bug fixes
  • docs/short-description — documentation
  • chore/short-description — maintenance, deps, CI

Dev Servers

# Full stack (server + dashboard)
pnpm dev

# Individual packages
pnpm --filter @agentkitai/agentlens-server dev
pnpm --filter @agentkitai/agentlens-dashboard dev

Working on a Specific Package

Most changes only affect one or two packages. Build dependencies first:

# Build core (most packages depend on it)
pnpm --filter @agentkitai/agentlens-core build

# Then work on your target package
pnpm --filter @agentkitai/agentlens-server dev

Testing

We use Vitest for all TypeScript packages.

# Run all tests
pnpm test

# Run tests for a specific package
pnpm --filter @agentkitai/agentlens-server test
pnpm --filter @agentkitai/agentlens-core test

# Watch mode
pnpm --filter @agentkitai/agentlens-server test -- --watch

Python SDK Tests

cd packages/python-sdk
pip install -e ".[dev]"
pytest

Code Style

  • ESLint + Prettier — run pnpm lint to check, pnpm lint --fix to auto-fix
  • TypeScript strict mode — enabled in all packages
  • No any — use proper types or unknown with type guards
  • Format on save is recommended — configure your editor for Prettier
# Check everything
pnpm lint
pnpm typecheck

Commit Conventions

We follow Conventional Commits:

feat: add session export endpoint
fix: correct hash chain validation on empty sessions
docs: update API reference for v0.10
chore: bump vitest to 2.x
feat(dashboard): add cost sparkline to session list
fix(python-sdk): handle missing provider gracefully

Types: feat | fix | docs | chore | refactor | test | ci

Scope (optional): package name — core, server, dashboard, cli, sdk, python-sdk, mcp

Pull Request Process

  1. Branch off main with proper naming (see above)
  2. Commit with conventional commit messages
  3. Push and open a PR against main
  4. Fill in the PR template — describe what and why
  5. CI must pass — lint, typecheck, tests
  6. Review — at least one approval required
  7. Merge — squash merge preferred for clean history

PR Checklist

  • Tests added/updated for new functionality
  • pnpm typecheck passes
  • pnpm lint passes
  • pnpm test passes
  • Documentation updated if applicable

Release Process

Releases are handled by maintainers:

npm Packages

# Bump versions (follows semver)
pnpm changeset        # describe your changes
pnpm changeset version # apply version bumps
pnpm build
pnpm publish -r       # publish all changed packages

Python SDK (PyPI)

cd packages/python-sdk
# Update version in pyproject.toml
python -m build
twine upload dist/*

Getting Help

Thank you for contributing! 🔍