leerness weekly downloads statistics

leerness

██╗     ███████╗███████╗██████╗ ███╗   ██╗███████╗███████╗
██║     ██╔════╝██╔════╝██╔══██╗████╗  ██║██╔════╝██╔════╝
██║     █████╗  █████╗  ██████╔╝██╔██╗ ██║█████╗  ███████╗
██║     ██╔══╝  ██╔══╝  ██╔══██╗██║╚██╗██║██╔══╝  ╚════██║
███████╗███████╗███████╗██║  ██║██║ ╚████║███████╗███████║
╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝

The AI-coding operations layer that makes "done" require evidence — for any language, any AI agent. leerness does not write code. It gives your AI agent persistent memory, verified completion, and clean handoffs — stored inside your repo as plain files, exposed via CLI + MCP.

· · 0 runtime deps · 0 install scripts · offline-first · Node ≥ 18 · MIT

🇰🇷 한국어 전문: README.ko.md

---

검수 batch의 명시적 로컬 저장 API: 소유권 세대·스냅샷·CAS·복구. 자동 검수/승인과 runtime 전환은 별도 단계입니다.

한국어 설명을 유지하며 새 하네스를 영어로 작성하려면 선택형 작성 언어를 설정할 수 있습니다. 기존 기록은 자동 번역하지 않습니다.

작업자·검수자의 반복 읽기를 줄이는 컨텍스트 읽기 범위는 현재 규칙과 담당 작업을 재사용하도록 안내합니다. 실제 소스·검증 근거 확인은 유지하며, 기존 프로젝트에는 하네스 업데이트가 필요합니다.

개발 중인 CTX-02B는 .leerness/archive/history/index.json으로 보존 task의 ID·상태·원본 digest를 색인해 전체 집계와 ID 예약을 유지하고, 정확한 task 조회·검증·검색 때만 보존 원문을 확인합니다. 보관 적용·복원·자동 정리는 아직 활성화하지 않습니다.

Try it in 30 seconds

npx -y leerness init . --yes   # adds .leerness/ memory + guard files to your project
npx leerness handoff .         # everything your AI should know right now, in one call

handoff is safe to run from several AI sessions at once: by default it does not rewrite Git-tracked harness files and updates only an ignored per-session record under .leerness/cache/sessions/. Use handoff --writeback only when legacy automation explicitly needs refreshed current-state.md, environment.json, last-handoff.json, or generated graph projections.

Existing projects that still use .harness/ are upgraded to .leerness/ transactionally on the first normal command run from that project (or targeted with --path). To inspect first, run leerness migrate-workspace-dir . --dry-run; to migrate an explicit positional project path, omit --dry-run. The migration preserves the byte-for-byte legacy tree by atomically renaming it to the ignored .leerness-backup/ only after canonical copies and hashes verify, preserves an existing structured-state substrate in .leerness/, remaps old observability runs into .leerness/cache/agent-runs/, and rewrites operational path references. It fails closed when both directories contain independently live state, the backup name already exists, or a link/junction could escape the project. Arbitrary path-shaped command text is never treated as a migration target.

For Cursor, run npx leerness adapter cursor --path . once. It preserves existing project hooks and adds a local sessionStart bridge that maps Cursor's session address to LEERNESS_SESSION_ID, so concurrent Cursor/Claude/Codex sessions remain separately traceable. Cursor Cloud currently does not run sessionStart/sessionEnd hooks; in that environment the agent must provide an explicit session address or run handoff itself.

Your project now has agent-independent memory. To see the flagship feature — catching a false "done" claim:

npx leerness task add "Implement payment API"   # prints the new id, e.g. T-0002 — use it below
npx leerness task update T-0002 --status done --evidence "payment.js implemented + tested"
npx leerness verify-claim T-0002   # exit 1 — payment.js does not exist. Claim rejected.

Now write the implementation and record evidence, then run the same verify-claim T-0002 again. A successful check means the applicable evidence checks passed; creating a file alone does not prove that the payment API works.

Tip: test counts are static declaration-pattern heuristics, not execution or coverage proof. Add --run-tests --test-cmd "<your trusted test command>" --json to check the selected command's exit status and supported reporter output. evidenceLevel: "executed" includes failed runs; inspect ok, reasons, and run together. semanticVerified remains false. See verification evidence and runnable examples for skipped runs, unparsed output, and reporting limits.

Want a smaller footprint? leerness init . --minimal installs only the core memory + verification files instead of the full set.

---

No terminal? Let your AI run it

You never have to type a command yourself. Paste this into Claude Code, Cursor, Codex, or any coding agent:

Set up leerness in this project by running npx -y leerness init . --yes. From now on, run leerness handoff . at the start of every session, verify finished work with leerness verify-claim, and run leerness session close . before you finish.

The agent installs and operates it for you — leerness init also writes the instructions into CLAUDE.md / AGENTS.md so future sessions pick them up automatically.

Prefer pure natural language? leerness ships an MCP server with 102 tools (leerness mcp serve). Connect it once to Claude Desktop / Claude Code and just ask: "what was I working on?", "did the AI actually finish T-0001?"

Explicit-input rule applicability advisory: rule assess and leerness_rule_assess. This does not change existing rules or gates.

Unpublished development interface: memory-migration inspect and its MCP tool inspect and recheck bounded legacy migration candidates without writing files.

Unpublished development interface: explicit memory migration retains original Markdown before CLI prepare, apply and rollback steps. Each write command requires --confirm.…