CodeWhale Tools Pack

A portable pack of global CodeWhale commands: //tools, //history, //snapshot, and //teach-me.

Cross-platform — works on Windows, Mac, Linux.

What's inside

tools_for_codewhale/
├── _list_sessions.js       # codewhale-history command (Node.js)
├── package.json            # npm package config
├── tools-install.js        # Cross-platform installer (skills + instructions)
├── skills/
│   ├── history/SKILL.md      # //history — calls codewhale-history
│   ├── snapshot/SKILL.md     # //snapshot — pre-edit file backups
│   ├── teach-me/SKILL.md     # //teach-me — interactive code quiz
│   └── tools/tools-skill/SKILL.md  # //tools — lists all available tools
├── instructions.md         # Trigger config (drop into any .codewhale/)
└── README.md               # This file

Install

npm install -g codewhale.history

Skills install globally, and workspace triggers are set up automatically in the current project. //tools, //history, //snapshot, and //teach-me work immediately.

IMPORTANT

If you already have codewhale.history installed in a folder and want to update to the lastest version in that folder, delete the .codewhale/instructions.md file before running npm install -g codewhale.history

Per-workspace install (add triggers to another workspace)

codewhale-tools-install                          # current workspace
codewhale-tools-install -p <target-path>        # specific workspace

After install

//tools

Lists every tool available in the current session, grouped by category (File I/O, Search, Git, Sub-agents, Shell, Planning, etc.), with a brief description of what each tool does. Read-only — no files touched.

//tools help or //tools readme — displays this full README inside any CodeWhale session, so you can always reference the command docs without leaving the terminal.

//history

Lists all chat sessions for the current workspace. Each session row shows:

• Date/time — when the session was created
• Title — session title
• Messages — message count for that session
• Tokens — tokens consumed (with thousands separators)
• Cost — session cost in USD (to 4 decimal places)
• Model — which model was used

A TOTAL row at the bottom summarizes the number of sessions, total messages, total tokens, and total cost across all sessions.

//snapshot

Toggle pre-edit file backups: //snapshot on, //snapshot off, //snapshot status.

Why you'll want this: Snapshot is designed for folders that are not Git repos — especially folders full of Office documents (.docx, .pptx, .xlsx, .pdf) that an AI agent is about to edit. Before every file modification, snapshot saves a timestamped copy into _snapshots/ so you can always get back to the pre-AI version:

report.docx  →  _snapshots/report.2026-06-21_14-30-00.docx

If the workspace already has a .git directory, snapshot politely declines — Git already has your back.

//teach-me

An interactive code-teaching quiz that randomly selects real snippets from your current project. Two independent dimensions across five difficulty levels:

Response mode (how you answer):

• Passive (default) — Describe your answer in the console.
• Interactive (teach me interactive) — Edit the actual file, say done.

Content theme (what it's about):

• Standard (default) — Code comprehension or line reconstruction.
• SOLID (teach me solid) — Anti-pattern detection and design restoration.
• Spec (teach me spec) — Spec-to-code traceability using office docs as source.
• BA-Gates (teach me ba) — BA documentation quality analysis (ambiguity, AC completeness, edge case coverage).

| Trigger | Response | Theme | What happens | |---------|----------|-------|-------------| | teach me | passive | standard | Present code; you explain it | | teach me interactive | interactive | standard | Lines removed; you restore them | | teach me solid | passive | solid | Degraded code; you describe fixes | | teach me solid interactive | interactive | solid | Degraded code; you edit to fix it | | teach me spec | passive | spec | Spec or code presented; you trace the link | | teach me spec interactive | interactive | spec | Trace spec to code; you edit code to match | | teach me ba | passive | ba-gates | BA doc fragment; you identify quality gate violations | | teach me ba interactive | interactive | ba-gates | BA doc with issues; you edit to fix them |

Triggers: teach me · quiz me · test my knowledge · code quiz · drill me

Modifiers (combine freely):

| Modifier | Example | What it does | |----------|---------|-------------| | Language | teach me python | Restrict to Python, TypeScript, Rust, Go, Java… | | Level | teach me level 3 or teach me l3 | Set difficulty 1–5 (default: 3) | | Response | teach me interactive | Edit the file instead of describing | | Theme | teach me solid | Anti-pattern detection — fix degraded design | | Theme | teach me spec | Spec-to-code traceability via office docs | | Theme | teach me ba | BA documentation quality analysis | | Scope | teach me services/ | Narrow to a specific file or folder | | Concept | teach me decorators | Target: decorators, async, generators, context managers, comprehensions, error handling, type hints, threading |

Difficulty levels:

| Level | Line range | What you'll face | |-------|-----------|------------------| | 1 | 5–15 | Straight-line logic, if/else, basic function calls | | 2 | 8–20 | Loops, list/dict operations, simple try/except | | 3 | 12–30 | Comprehensions, decorators, with statements, multiple branches | | 4 | 18–45 | Generators, async/await, descriptors, threading, closures | | 5 | 25–55 | Metaclasses, complex async patterns, multi-threading, architectural glue |

Mid-round commands: hint (get a nudge) · skip (see the answer) · next (draw a new snippet) · level N · easier · harder · interactive · passive · solid · spec · ba · done (verify work) · stop

At the end you get a session summary: rounds completed, mode, files covered, what you're strong on, what to review, and a suggested next level.

In SOLID theme: the model rewrites code with deliberate anti-patterns (STUPID, WET, god objects, tight coupling), presents the degraded code, and you restore good design. Files are always restored with git checkout after each round.

In Spec theme: the model scans your office documents (.docx, .pptx, .xlsx) and source code, then quizzes you on the correlation between them. Each round randomly picks one direction — either "what code implements this spec?" or "what spec does this code satisfy?" — testing whether you truly understand how requirements map to implementation. In interactive mode, you edit the code to satisfy the spec; in passive mode, you describe the link.

In BA-Gates theme: the model runs a two-pass analysis over your BA documentation files (.docx, .pptx, .xlsx, .md, .feature, .txt). Pass 1 uses regex triage to flag fragments against three quality gates — Ambiguity (unmeasurable terms, passive states), Acceptance Criteria Completeness (missing structure, unverifiable outcomes), and Edge Case Coverage (missing negative scenarios, error states). Pass 2 runs an LLM interpretation per fragment at round time to generate quiz material and concrete improvement options. You identify which gates a fragment triggers and describe the developer impact. On skip or strike-3, the model presents 2–3 domain-specific rewrites per issue with a best-fit recommendation.

Requirements

• Node.js (for the codewhale-history command)
• CodeWhale

Contact Developer

species8472