npm package: @kalamiai/kalami
Description: Learning layer for AI coding — every session gets smarter
Latest version: 0.1.3
Deprecated: Use 'kalami' instead: npx kalami

# Kalami

One command to install. Every session gets smarter.

Kalami is a learning layer for Claude Code. It turns AI coding mistakes into rules that prevent them from happening again — automatically, mechanically, every session.

## Install

```bash
npx kalami
```

No config. No wizard. Kalami detects your project, sets up framework-specific rules and learning hooks. Under 0.5 seconds, pure bash, no AI in the critical path.

## How It Works

```
AI makes mistake → Kalami records it → next session, mistake becomes a rule
→ AI reads rule → doesn't repeat mistake
```

**Init** (first run) — Detects your project (language, framework, package manager), generates rule files with curated seed rules.

**Loop** (every session after) — Analyzes the previous session's transcript for mistakes, generates new rules, updates the rules file.

Kalami captures three types of learning signals:
- **User corrections** — you say "no, do it this way" → highest quality signal
- **Error-fix pairs** — command fails, AI fixes code, command passes → includes WRONG/RIGHT code
- **AI self-recorded** — AI voluntarily records a lesson

Rules that get verified float to the top. Rules with zero verification after 5 sessions fade out. Contradicted rules are immediately excluded.

## Seed Rules

Every seed rule is validated by RED/GREEN testing across 9 models (3 providers x 3 tiers). Only rules that prevent real mistakes are shipped.

| Framework | Rules | Validated on |
|-----------|:-----:|-------------|
| Go | 2 | 5/9 models (universal) |
| Python | 3 | Claude + GPT + Gemini |
| Next.js | 2 | 5/9 models |
| Next.js 15 | 1 | Flash-specific |
| React | 1 | Claude 4.6 specific |
| Rust | 1 | 4/9 models |
| FastAPI | 1 | Cross-provider |
| Vue | 1 | Claude-specific |
| Nuxt | 2 | Claude-specific |
| Svelte | 1 | Pro + Claude |
| SvelteKit | 1 | Pro + Claude |
| Express | 3 | Community patterns |

19 rules total. No framework match? Kalami still works — it learns from your sessions.

Detection also supports: TypeScript, PHP, Ruby, Dart, Elixir, Swift, Angular, Astro, Vite, NestJS, Fastify, Electron, Tauri, Expo, React Native, Flask, Gin, Fiber, Actix, Rocket, Laravel, Rails, Flutter.

## What Gets Created

```
.claude/rules/
  kalami-workflow.md     # universal rules (always active)
  kalami-rules.md        # framework + learned rules (path-scoped)

.claude/hooks/
  kalami-session.sh      # SessionStart + PreCompact
  kalami-postedit.sh     # PostToolUse (Edit|Write)
  kalami-stop.sh         # Stop

.kalami/
  index.md               # experience database
  state.json             # session counter, budget
  config.json            # detection results
```

## CLAUDE.md Handling

| Your project | What Kalami does |
|---|---|
| No CLAUDE.md | Generates reference (commands, stack, architecture) |
| Small CLAUDE.md (≤30 lines) | Fixes wrong package manager commands only |
| Large CLAUDE.md (>30 lines, >10 rules) | Extracts instructions to path-scoped rule files |
| Symlink | Skips |

Original CLAUDE.md backed up to `.kalami/backup/CLAUDE.md`. Fully reversible.

## Commands

```bash
npx kalami                  # Install
npx kalami status           # Show rules, budget, activity
npx kalami --force          # Reinstall (refresh seed bank)
npx kalami --uninstall      # Remove everything, restore CLAUDE.md
npx kalami --dry-run        # Preview without writing
npx kalami --no-refactor    # Skip CLAUDE.md refactoring
```

## Requirements

- Node.js 18+
- `jq` (recommended; degrades gracefully without it)
- Git (optional, improves signal quality)

## License

MIT