Configuration

Kalami stores all state in the .kalami/ directory at your project root.

File structure

.kalami/
  index.md          # Experience database — all learned rules
  state.json        # Session counter, budget, stats, hardened rules
  config.json       # Detection results (language, framework, PM)
  profile.json      # Project stack profile and conventions
  progress.md       # Session history for continuity
  statusline.txt    # Generated statusline for harness delivery
  plans/            # Active plans
  backup/           # Original CLAUDE.md backup

config.json

Created during npx kalami init. Contains detection results.

{
  "language": "typescript",
  "framework": "nextjs",
  "pm": "npm",
  "dirs": ["./", "src/", "app/"],
  "manifest": "package.json",
  "verify": {
    "typecheck": "npx tsc --noEmit",
    "lint": "npm run lint",
    "test": "npm test",
    "build": "npm run build"
  }
}

The verify object defines commands used by the verify chain. Kalami auto-detects these from your package.json scripts and project structure.

state.json

Tracks session-level state and learning progress.

{
  "version": 1,
  "sessions": 12,
  "exp": 25,
  "lastSession": "2026-03-19T10:00:00Z",
  "budget": {
    "rules": 800,
    "available": 2000
  },
  "hardened": {
    ".env": {
      "since": "2026-03-15",
      "deny": ["Read(.env)", "Read(.env.*)", "Edit(.env)"]
    }
  },
  "diagnosis": {
    "score": 95,
    "issues": []
  }
}

index.md

The experience database. Each entry is a learned rule with metadata.

NEVER use `any` type in TypeScript — always define proper interfaces
src/
(verified 3, added: 2026-03-10, s:5)

ALWAYS run `npm test` before committing changes
./
(verified 7, added: 2026-03-08, s:2)

Rule format:

• Line 1: NEVER/AVOID/ALWAYS/PREFER/MUST {rule text}
• Line 2: Module path (e.g., src/auth/)
• Line 3: Metadata — (verified {count}, added: {date}, s:{session})

Rules are ranked by verification count. Top rules get priority in the context budget.

profile.json

Project identity and learned conventions.

{
  "name": "my-project",
  "since": "2026-03-10",
  "sessions": 12,
  "stack": {
    "framework": "Next.js",
    "frameworkVersion": "14.1.0",
    "router": "app",
    "language": "typescript",
    "pm": "npm"
  },
  "dirs": ["./", "src/", "app/"],
  "conventions": ["path_alias_at", "cn_classnames", "use_client"],
  "commands": {
    "detected": { "dev": "npm run dev", "test": "npm test" },
    "learned": {}
  }
}

Convention signals tracked:

Signal	Meaning
path_alias_at	Uses @/ import aliases
cn_classnames	Uses cn() for Tailwind class merging
zod_api_validation	Uses Zod validation in API routes
css_modules	Uses *.module.css imports
use_client	Uses "use client" directive
barrel_exports	Uses components/*/index.ts barrel pattern

Rule files

Kalami generates two rule files in .claude/rules/:

• kalami-workflow.md — Universal rules (always active). Commit format, branch naming, coding standards.
• kalami-rules.md — Learned rules (path-scoped). Generated from index.md, updated each session.

Hook scripts

Deployed to .claude/hooks/:

Hook	Trigger	Purpose
kalami-session.sh	SessionStart, PreCompact	Runs learning loop
kalami-userprompt.sh	UserPromptSubmit	Detects corrections
kalami-postedit.sh	PostToolUse (Edit/Write)	Tracks modules, conventions, scope
kalami-postbash.sh	PostToolUse (Bash)	Detects errors
kalami-verify.sh	PreToolUse (git commit/push)	Verify chain gate
kalami-stop.sh	Stop	Report card, verified counting
loop.sh	Internal	Loop engine
loop-functions.sh	Internal	Shared functions for loop

Skills

Deployed to .claude/skills/:

Skill	Purpose
kalami-commit	Atomic commit with verify chain
kalami-push	Push with full test suite
kalami-release	Version bump + changelog + tag
kalami-review	Code review checklist
kalami-plan	Multi-file planning workflow