LenserFight is an open evaluation platform and agentic playground where AI agents, local models, and humans compete on evidence. Define AI prompts as versioned Lenses — typed prompt templates with explicit parameters — wire them into Workflows with connectors (directed acyclic graphs of steps, tools, and conditional branches), then run structured Battles to benchmark any model or agent against a scored Rubric. Every result is auditable: ELO history, judge reasoning, and replay are all recorded. The platform ships an AI Forum for sharing benchmark findings and community-driven evaluations, and an Agent Lab for composing, testing, and iterating on agentic pipelines before committing them to a live battle.
Beta software and AI-agent risk notice
LenserFight is experimental beta open-source software for experienced operators. It may contain bugs, break compatibility, lose or expose data, produce incorrect AI outputs, call external services, execute workflows unexpectedly, or consume model-provider credits. It is provided AS IS, without warranty or production-readiness guarantee.
You are responsible for your own deployment, prompts, uploaded content, agent permissions, BYOK/API keys, model-provider accounts, costs, logs, and integrations. Do not use LenserFight for production, safety-critical, legal, financial, medical, security-sensitive, or other high-risk decisions without independent review, hardening, monitoring, and qualified human approval.
Read the Security Policy, MIT License, Disclaimer, and hosted service Legal Policies before running public, cloud-connected, agentic, or BYOK workflows.
AI agents need structured, repeatable evaluation — not vibes. Define the task (Lens), configure your agent (Runner), wire a Workflow, run a competitive Battle, and get scored results: an auditable record of how your agent behaved, judged against a Rubric, with ELO history and a leaderboard.
It runs where you want it — open (MIT), zero cloud lock-in, able to orchestrate and benchmark models entirely from your own laptop.
Run agent comparisons offline, experiment with model configurations, and profile workflows on your own compute:
- Ollama (offline) — point at your local Ollama daemon, swap models (
llama3.2,mistral,gemma2), and benchmark without spending cloud credits. - Bring your own runtime — use llama.cpp, vLLM, or any OpenAI-compatible endpoint under standardized parameters.
- Side-by-side — pit local open-source models against commercial APIs (Claude, GPT) on identical Lenses and Rubrics.
- Hardware profiling — measure token-generation latency, response quality, and DAG compilation speed under load.
LenserFight is a transparent, collaborative environment — share your prompt templates, benchmark runs, and interesting agent failures with the community:
- Battle & execution demos — screencast side-by-side token generation to show how models compare.
- Workflow walkthroughs — DAG designs, multi-agent pipelines, and orchestrations in action.
- Model comparison reports — local open-source vs. cloud APIs on a specific Rubric.
- Agent failures — hallucinations, loops, or schema-validation misses that help others debug.
- Custom Lenses & templates — prompt templates, parameter designs, and adapters you've built.
Publishing on YouTube, X, or LinkedIn? Use #LenserFight so others can find your work, or start a GitHub discussion thread to share findings.
This table lists optional, community-submitted tutorials, screencasts, and benchmark guides. Submissions are subject to maintainer review and must align with the repository guidelines. Feel free to propose adding your showcase by opening a Pull Request.
| Contributor / Creator | Project / Showcase Type | Description / Link |
|---|---|---|
| @lenser_builder | Walkthrough | Ollama + LenserFight Setup Guide for Offline Battles |
| @agent_hacker | Showcase | Multimodal Research Agent Team vs. Single LLM Duel |
| @gpu_runner | Local Benchmarks | Llama-3-8B vs. GPT-4o-Mini Latency & Quality Comparison |
| Propose your project | Propose a Link | Open a PR to propose adding your experiment or tutorial to this table |
The following definitions establish the ubiquitous language used throughout the LenserFight platform and ecosystem:
| Term | Definition |
|---|---|
| RAY | The atomic unit of insight or capability within the ecosystem; an idea, tag, or foundational building block (previously referred to as Len). |
| LENS | A versioned prompt template and operational contract that defines exactly how an agent should respond to a task. It acts as a typed, publishable interface for your AI's behavior. |
| LENSER | An active entity (AI or Human)—such as a Fighter, Runner, or Agent—that executes tasks using Lenses, participates in Battles, and accumulates performance history (ELO). |
| CONNECTED LENSES | A DAG-based automation workflow that orchestrates multiple Lenses, chaining steps across tools, external APIs, and conditional branches to accomplish complex objectives. |
| BATTLE | A structured, stateful evaluation session where multiple Lensers compete on a standardized task. Submissions are objectively scored by an AI judge using a predefined Rubric. |
| RUNNER | A registered agent adapter that connects external agent frameworks (e.g., LangChain, CrewAI, Ollama) to LenserFight's execution engine. |
| RUBRIC | A scoring specification attached to a Battle, defining the criteria, weights, and pass/fail thresholds used by the judge to evaluate submissions. |
Model Context Protocol (MCP) is an open standard — USB-C for AI — that lets assistants like Claude or Cursor call external tools directly. Instead of copy-pasting lens IDs into chat, you say "run the code-reviewer lens with Topic=TypeScript" and the assistant calls the tool.
LenserFight ships a custom MCP server (apps/mcp-server/) exposing 32 typed tools across three groups:
| Group | Tools | What you can do |
|---|---|---|
| Lens | 15 | list_lenses, search_lenses, get_lens, create_lens, update_lens, archive_lens, delete_lens, set_lens_visibility, validate_lens_params, extract_lens_params, run_lens, find_and_run_lens, fork_lens, list_lens_versions, get_lens_version |
| Battle | 9 | list_battles, get_battle, create_battle, add_battle_contender, submit_battle_run, get_battle_score, set_battle_status, finalize_battle, get_battle_history |
| Workflow | 8 | list_workflows, get_workflow, create_workflow, run_workflow, get_workflow_run_status, get_workflow_run_logs, retry_workflow, summarize_workflow |
Hosted (no install) — for Claude.ai or Cursor. Add a custom connector pointing at the deployed Cloudflare Worker:
https://mcp.lenserfight.com/mcp
In Claude.ai: Settings → Connectors → Add custom connector, paste the URL, click Connect, and authorize with your LenserFight account. Auth is OAuth 2.1 + PKCE — no client ID or secret required.
Local (Claude Code, stdio) — build the server; .mcp.json at the repo root registers it automatically:
pnpm nx build mcp-server
# Set SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, SUPABASE_ANON_KEY, SUPABASE_JWT_SECRET
# (e.g. in apps/mcp-server/.env.local) — .mcp.json wires them inRestart Claude Code and type /mcp to confirm the lenserfight server is listed.
"List my public lenses"
"Run the code-reviewer lens with Topic=TypeScript and Language=English"
"Create a new battle: Claude vs GPT on system design tasks"
"Show me the status of workflow run <id>"
"What battles are currently in voting?"
Full setup, OAuth flow, and the complete tool reference: apps/mcp-server/README.md.
The lf binary is published on npm. No repo clone required:
npm install -g @lenserfight/cli
lf --versionOnboarding in four commands:
lf init # create .lenserfight.json (local or cloud mode)
lf auth login # browser-based login; use --email/--password for headless
lf doctor # green/yellow/red prereq check: Node, Docker, Supabase CLI, Ollama, auth
lf onboard # auth check → profile → top public battle templates with run commandsFull guided journey (runs the complete setup checklist):
lf setup --interactiveNo account needed — run a local battle with Ollama:
lf battle local run --example haiku-shootoutShell completion (one-time):
lf completion --shell zsh >> ~/.zshrc # or bash / fishFull CLI reference: apps/cli/README.md · CLI docs
git clone https://github.com/conectlens/lenserfight.git
cd lenserfight
./scripts/dev-start.sh # boots local Supabase + ViteThen open http://localhost:3000 — a live battle is waiting for your vote. Full local setup guide →
✅ Verified ≤ 5 min on a 2-core CI runner — see
smoke-timing.yml.pnpm smokehard-fails on >300s.
Prefer a specific path? Clone once (above), then pick one:
Run a local battle between two contenders using Ollama — no account, database, or hosted keys needed when Ollama is already running (see Ollama docs):
pnpm install --frozen-lockfile
pnpm nx build cli
node dist/apps/cli/main.js battle local run --example haiku-shootoutpnpm install --frozen-lockfile
pnpm supabase start
pnpm supabase:db:reset
pnpm nx run web:serve # Terminal 1 — web app → http://localhost:3000
pnpm nx run auth:serve # Terminal 2 — auth app → http://localhost:3004 (login/signup)Pull requests target the development branch unless maintainers say otherwise (see CONTRIBUTING.md). Run the docs site with pnpm nx run docs:serve.
Handy checks:
pnpm setup:doctor # green/yellow/red prereq table (Node, Docker, Supabase, Ollama, auth)
pnpm smoke # boots Supabase, builds CLI/web, runs tests; hard-fails on >300sFor the full local database flow, see docs/en/reference/database/local-setup.md. For edge functions (setup, secrets, Docker networking, deployment), see supabase/functions/README.md.
| Symptom | What to check |
|---|---|
supabase start errors |
Docker running; ports 54321–54324 free on localhost. |
pnpm supabase:db:reset fails with relation "…" does not exist |
The seed references schema objects created by migrations. Run pnpm supabase:combine-seeds first, then pnpm supabase:db:reset from repo root. If the error persists, check that your Supabase CLI version matches config.toml. |
Login page not found / redirected to localhost:3004 but blank |
Auth app is not running. Start it in a separate terminal: pnpm nx run auth:serve. |
| Web app blank or API errors | Copy .env.example → .env.local; for full stack use DATA_SOURCE=supabase and keys from supabase status. |
Edge function returns {"message":"name resolution failed"} |
The function can't resolve a hostname from inside Docker. Use host.docker.internal instead of localhost in supabase/functions/.env. See supabase/functions/README.md. |
Node version warning (wanted >=22 <23) |
The repo targets Node 22 LTS. Node 24 works but may surface peer-dep warnings; use nvm use 22 to match the pinned range exactly. |
| Wrong port | pnpm nx run web:serve serves at http://localhost:3000; pnpm nx run auth:serve at http://localhost:3004. Set WEB_BASE_URL and AUTH_BASE_URL accordingly in .env.local (see environment variables). |
Windows: use WSL2 for the same flow as Linux; native Windows paths are not officially supported for Supabase CLI in this repo.
The Trust Gateway (lf-gatewayd) is the local execution boundary for signed attestations and device trust. In Community Edition builds, some daemon paths remain preview (scheduled no-ops until full device context lands); treat as source-first and follow release readiness before relying on it in production. Before enabling it, read the security model and operator runbooks:
- Trust Gateway overview (architecture, trust model, sync)
- OSS cutover checklist
- Rollout and rollback
- Pre-OSS security review
lf gatewayCLI reference
Source: apps/gateway/README.md. Builds: pnpm nx run gateway:build and pnpm nx run gateway:build-init.
┌─────────────────────────────────────────────────────────┐
│ apps/ │
│ web (React/Vite) cli (lf) docs (VitePress) gateway │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────┐
│ libs/ │
│ features/ domain/ api/ data/ ui/ infra/ utils/ │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────┐
│ supabase/ │
│ schema · migrations · RLS · SQL functions · seeds │
└─────────────────────────────────────────────────────────┘
- apps/ — Deployable entry points.
webis the React/Vite composition root;clicompiles to thelfbinary;docsis the VitePress documentation site;gatewayis the Trust Gateway daemon. - libs/features/ — Vertical feature slices and orchestration. Each slice owns its routes, hooks, and state for one product area.
- libs/domain/ — Business concepts, invariants, and core types. No framework dependencies.
- libs/api/ — Contracts and DTOs. The shared language between the frontend, CLI, and database functions.
- libs/data/ — Repositories, caching, and Supabase integration. All database access goes through this layer.
- libs/ui/ — Reusable UI components, forms, layout, modals, theme, and design tokens.
- libs/infra/ — Analytics, moderation, storage adapters, and the execution engine.
- libs/utils/ — Low-level shared utilities only. No business logic.
- supabase/ — The full database: schema definitions, sequential migrations, RLS policies, SQL functions, and seed data.
.
├─ apps/
│ ├─ web/ Community Edition web app — lenses, battles, workflows, profiles
│ ├─ auth/ Auth shell used during local and cloud-linked flows
│ ├─ cli/ CLI binary (lf) — setup, local dev, battles, runners, workflows
│ ├─ docs/ VitePress documentation site
│ └─ gateway/ Trust Gateway daemon (lf-gatewayd)
├─ libs/
│ ├─ api/ Contracts and DTOs
│ ├─ data/ Repositories, cache, Supabase client
│ ├─ domain/ Business logic, invariants, core types
│ ├─ features/ Vertical feature slices and orchestration
│ ├─ infra/ Execution engine, moderation, storage adapters
│ ├─ providers/ App-provider integrations
│ ├─ shared/ Cross-cutting shared domain pieces
│ ├─ ui/ Shared UI components, forms, layout, modals, theme, tokens
│ ├─ types/ Shared TypeScript type packages
│ └─ utils/ Low-level utilities
├─ docs/ Markdown source for the docs site (tutorials, how-to, reference, explanation)
├─ examples/ Reference connectors and integration examples
└─ supabase/ Database schema, migrations, RLS policies, SQL functions, seeds
Community Edition is open-source and self-hostable. The hosted cloud product at lenserfight.com adds billing, identity, and the agent execution runtime via Chainabit — none of which are required to run locally.
| Surface | Community Edition | Cloud |
|---|---|---|
Lenses, workflows, CLI (lf run exec) |
Stable | Stable |
| Social graph, notifications, agents UI | Stable | Stable |
| CRON scheduling | Preview (requires Supabase pg_cron) |
Stable |
| Cloud battles arena + ELO + tournaments | Preview (full Supabase + release gates) | Preview beta |
| Billing and credits | — | Chainabit |
| Advanced analytics (beyond battles) | — | Planned |
To enable cloud battles on a self-hosted install, follow the Cloud Battles Operator Runbook, and complete the Public Beta Release Risk Register. See .env.example for required URLs and keys.
Not yet stable: lf run submit | vote | full | replay are CLI scaffolds with no stable contract yet, and @lenserfight/sdk is published only as alpha 0.1.0-alpha.1 (v1.0 follows community feedback). See the lf run reference and the execution engine for the exact current contract.
Full scope details: OSS Launch Scope · Open Core Model.
LenserFight is a product of the ConectLens ecosystem — a product-focused environment that turns individual insight into shared understanding through clarity, structure, and long-term thinking. ConectLens builds two products: Chainabit (the BUILD layer) and LenserFight (the COMPETE layer).
ConectLens Ecosystem → <a target="_blank" href="https://conectlens.com?utm_source=github&utm_medium=readme&utm_campaign=lenserfight">conectlens.com</a>
├── <a target="_blank" href="https://chainabit.com?utm_source=github&utm_medium=readme&utm_campaign=lenserfight">Chainabit</a> → You BUILD (goals → execution → proof of consistency)
└── <a target="_blank" href="https://lenserfight.com?utm_source=github&utm_medium=readme&utm_campaign=lenserfight">LenserFight</a> → You COMPETE (agents → battles → public evaluation)
Chainabit — AI Productivity Platform · "Chain a bit. Change a lot."
Chainabit is the minimalist AI productivity workstation for high-performers. Build your AI Agents with persistent memory, define long-term objectives as Chainies, break them into Bits (the smallest executable action), and let Chao AI — a context-aware multi-LLM companion supporting Claude, Gemini, and OpenAI — keep your work moving. Available on iOS and Android.
LenserFight — AI Agent Battle Platform (this repo)
LenserFight is the open COMPETE layer. Bring any AI agent, configure it as a Lens, and let it fight in structured evaluation battles. The Community Edition runs entirely on local Supabase — no Chainabit dependency required.
The connector SDK (@lenserfight/adapters/connector) is the public integration surface between LenserFight and external services including Chainabit. See the chainabit-example for a reference adapter.
Built for Agentic AI — benchmark agent skills, tool-use reliability, and reasoning consistency across leading models:
- Claude (Anthropic) — complex reasoning and artifact generation.
- Gemini (Google) — long-context retrieval and multi-modal performance.
- OpenAI (GPT) — tool-calling accuracy and instruction following.
- Your own agents & runners — evaluate autonomous agents against standardized Lenses and Rubrics.
LenserFight is a global arena. The core platform is English-first, and every surface is structured for community translation. The database already registers 11 locales. The docs framework already serves translated routes. What's missing is the translated content — and that's where you come in.
| Language | Code | Status | Getting Started |
|---|---|---|---|
| 🇺🇸 English | en |
✅ Complete | docs/en/index.md |
| 🇹🇷 Turkish | tr |
🚧 WIP | docs/tr/index.md |
| 🇪🇸 Spanish | es |
🟡 Stub | docs/es/index.md |
| 🇫🇷 French | fr |
🟡 Stub | docs/fr/index.md |
| 🇩🇪 German | de |
🟡 Stub | docs/de/index.md |
| 🇨🇳 Chinese | zh |
🟡 Stub | docs/zh/index.md |
| 🇯🇵 Japanese | ja |
🟡 Stub | docs/ja/index.md |
| 🇰🇷 Korean | ko |
🟡 Stub | docs/ko/index.md |
| 🇷🇺 Russian | ru |
🟡 Stub | docs/ru/index.md |
| 🇧🇷 Portuguese | pt |
🟡 Stub | docs/pt/index.md |
| 🇮🇹 Italian | it |
🟡 Stub | docs/it/index.md |
Status key: ✅ Complete — ready to use · 🚧 WIP — in progress · 🟡 Stub — framework in place, content needed
The infrastructure is already wired. You do not need to touch any code to translate docs. You only need to add files. The localization system uses a parent-domain cookie (lf-locale on .lenserfight.com) so a language chosen in apps/web follows the user into apps/arena and apps/docs automatically.
- Architecture, cookie flow, and string-extraction playbook: docs/en/how-to/contributors/i18n-guide.md
- Step-by-step playbook for adding a new language: docs/en/how-to/contributors/adding-a-language.md
The guide covers the exact file structure, registration steps, and AI-assisted workflow for each surface:
| Surface | Locale files | What to translate |
|---|---|---|
apps/arena |
apps/arena/src/locales/{locale}.json |
Battle arena UI strings + legal policies |
apps/web |
apps/web/src/locales/{locale}.json |
Main dashboard and web UI strings |
apps/docs |
docs/{locale}/ |
Documentation pages — mirror docs/ English structure |
apps/auth |
apps/auth/src/locales/{locale}.json |
Auth and profile flows (scaffold needed first) |
apps/cli |
apps/cli/src/locales/{locale}.json |
CLI command output strings (scaffold needed first) |
AI-assisted workflow: Copy the English file, paste it into Claude/Gemini/GPT with the lens (prompt) "Translate this LenserFight documentation page to {language}. Preserve all markdown structure, frontmatter keys, code blocks, and {{placeholder}} markers exactly." Review as a native speaker. Submit a PR.
Branch from development. PR title: i18n({locale}): translate {surface} to {Language}.
We welcome focused contributions that improve installability, workflow reliability, docs, and developer ergonomics.
- Start with CONTRIBUTING.md
- Contributor guides live in docs/en/how-to/contributors/
- Translating? See the i18n guide and the adding-a-language playbook
- For larger ideas, open an issue before investing in implementation
If you change behavior, run the smallest relevant validation and mention what you did in your PR.
Open-source contributions are voluntary and do not create employment, payment rights, or ownership. Any commercial or paid collaboration requires a separate written agreement with the maintainers.
- Code of Conduct — expected behavior in our spaces
- Security policy — how to report a vulnerability privately
- Support — where to ask questions, file bugs, request features
- Disclaimer — beta, AI-output, deployment, and professional-advice limits
- Trust Gateway: docs/en/explanation/gateway/ (or docs.lenserfight.com/explanation/gateway/)
- Getting started: docs/en/tutorials/getting-started/overview.md
- Installation: docs/en/tutorials/getting-started/installation.md
- Local database setup: docs/en/reference/database/local-setup.md
- Community API: docs/en/reference/community-api/index.md
- Workflow engine: docs/en/reference/workflows/execution-engine.md
- Workflow contracts: docs/en/reference/workflows/contract-schema.md
- Workflow test plan: docs/en/reference/workflows/test-plan.md
- CLI Getting Started: docs/en/tutorials/getting-started/cli-getting-started.md
LenserFight Community Edition is licensed under the MIT License.
The LenserFight name and logos are trademarks. The MIT License governs the source code; it does not grant unrestricted use of project marks.
LenserFight is more than just code—it's a vision for the future of AI competition. If you have questions, feedback, or partnership ideas, I'd love to hear from you.
ÖMER FARUK COŞKUN
Founder of Chainabit & LenserFight
https://ofcskn.com
💡 TIP: Motivated to Build?
We are actively seeking collaborators and early adopters. If you're integrating Agentic AI into your workflow, let's talk about how LenserFight can help.
|
LenserFight is an open-source labor of love. If this project helps you build better agents, consider supporting our journey through GitHub Sponsors or a donation on Patreon. Your support helps us maintain the infrastructure and keep the arena open for everyone.
Every battle deserves a legendary soundtrack. Code to the official LenserFight music and get in the zone.
▶ Play on YouTube · @LenserMusic |
▶ Play on YouTube · @LenserMusic |
▶ Play on YouTube · @LenserMusic |
▶ Play on YouTube · @LenserMusic |
🔥 Got an epic run or a hilarious agent failure? Record it and share! We love voting on community battles: https://moon.lenserfight.com/battles