Took

Took helps engineers and non-technical builders steer AI coding agents through a disciplined workflow — before they create messy code, stale docs, unsafe diffs, weak pull requests, or compliance gaps.

It should feel like a calm senior engineer sitting next to you in the terminal: one who teaches the why, scales how closely it watches to how much help you need, and never ships you into a compliance trap.

Took is a coach, never an agent. It operates in the steering layer — coaching what goes into the loop and reviewing what comes out.

The RePPIT Loop

Every AI-assisted software task benefits from a disciplined spine. Took coaches the RePPIT loop:

Research → Propose → Plan → Implement → Test

And for regulated work, RePPITS — with a mandatory sixth phase:

Research → Propose → Plan → Implement → Test → Secure

| Phase | What Took coaches | |---|---| | Research | Produce a research document before the agent touches code — so planning has something real to reason from | | Propose | Weigh ≥2 solutions; commit to one with a rationale | | Plan | Write a reviewable spec with a verifiable done — not a vibe | | Implement | Right-size delegation; externalize progress on long tasks; watch context budget | | Test | Every behavior change ships with a runnable, automatic test | | Secure | Run HIPAA/SOC2/HITRUST checklists against the diff; loop until clean (Pipp Health only) |

Two cross-cutting disciplines wrap every phase:

• Right-size rigor to the task — don't force the full loop on a one-line fix; don't skip research on a migration.
• Protect the context budget — treat the ~170K "smart" tokens as a finite resource; externalize progress before you hit the dumb zone.

Three Layers

| Layer | For whom | What it adds | |---|---|---| | Took | Engineers | RePPIT coaching, diff/docs/PR checks, agent-readiness audit, XP, git hooks, Claude Code plugin | | Pipp | Non-technical builders | Plain-English narration of every agent action, cited resources, heightened scanning, learning profile | | Pipp Health | Regulated teams (healthcare, etc.) | The Secure phase, HIPAA/SOC2/HITRUST assessment, PHI/PII scanning, code-vs-org control separation, compliance audit trail |

Install

npm install -g took

Requires Node 18+. No account needed.

took init       # scaffold .took/, detect your repo's docs/tests/build
took ready      # agent-readiness report card — what breaks agents first

Command Reference

| Command | What it does | |---|---| | took init | Create .took/config.json, detect repo shape, write AGENTS.md if missing | | took ready | Agent-readiness audit — 0–100 score + highest-leverage fix | | took eval | Account-gated full evaluation — fused Took Score (repo × prompt/coding quality) + ranked improvements, narrated by an LLM | | took prompt "<text>" | Right-size the task and coach the next RePPIT step | | took diff | Review staged diff: scope, missing tests, secrets, slop | | took docs-check | Check README, .env.example, and AGENTS.md for drift | | took pr-ready | PR readiness score + copy-ready next prompt | | took xp | Your XP ledger — judgment earned, not tokens burned | | took guard | Evaluate a tool call for safety (also used by hooks) | | took secure | Secure phase: compliance checklists vs the diff (Pipp Health) | | took scan | Standing scan for secrets and PHI across the repo | | took pipp | Switch to the non-technical register | | took explain <action> | Plain-English narration with cited resources; --deep for fuller Pipp-depth detail (Pipp / Max) | | took stats | Git-derived improvement trends (directional) | | took badge | Print a shields.io endpoint JSON for README badges | | took install-hooks | Install git pre-commit/pre-push and Claude Code hooks | | took hook <event> | Claude Code hook protocol handler (stdin → stdout) |

Scanning and .tookignore

took scan walks the repo for leaked secrets (and PHI/PII with --phi, on by default in the Pipp Health register). It exits non-zero on a blocking exposure, so it can gate a pre-commit hook.

Some "secrets" are deliberate, non-functional fixtures — e.g. detector test files that embed an example AWS key to prove the scanner fires. Exclude those with a gitignore-style .tookignore at the repo root:

# paths the standing scan should skip — globs: * ** ?, # comments
tests/**
*.fixture.*

Use it sparingly: anything matched is invisible to the scan, so a real leak in those paths won't be caught. (took diff still scans every added line.)

Scanning earns no XP — resolving an exposure does. took scan grants security XP only when a finding flagged by the previous scan is gone now, whether remediated or deliberately suppressed via .tookignore. A clean-stays-clean (or dirty-stays-dirty) scan earns nothing, and the daily security cap holds across runs.

The Typical Workflow

npm install -g took
took init                            # one-time per repo
took ready                           # see what an agent has to work with

took prompt "Migrate users table to add a profile_image column"
# → sizes the task, recommends Research → Plan before implementation

# ... agent works; PreToolUse hook intercepts risky or out-of-scope calls ...

took diff                            # scope check, test gaps, secrets
took docs-check                      # README / .env.example / AGENTS.md drift
took pr-ready                        # readiness score + next prompt to close the gap
took xp                              # XP earned for quality workflow decisions

took install-hooks                   # add git + Claude Code hooks permanently

Local-First / Privacy

Took is local-first by design. By default:

• Everything stays on your machine. The event log and config live in .took/.
• No account, no telemetry, no code or diffs leave your machine.
• XP and analytics are computed locally from your own git history and Took events.

There are three explicit privacy tiers — local-only (default), sync (opt-in derived metrics only, never raw code), and public (only what you publish). You control every tier transition.

LLM Narration (optional)

Took's brain is deterministic and rules-first. An LLM is an optional narration layer that turns derived scores into plain-English coaching (used by took eval and took explain). It only ever receives derived data — scores, counts, improvement titles — never your source code, diffs, or prompts.

Configure the provider in .took/config.json under llm:

| provider | Behaviour | |---|---| | stub (default) | Deterministic templated text, fully offline. Auto-detects a local claude CLI and uses it when present (see below). | | claude-cli | Shell your own installed claude CLI (claude -p) — runs on your Claude subscription, no API key, no token handling. | | anthropic | Call the Anthropic API directly with a BYO key (apiKeyEnv names the env var that holds it). |

Auto-detection. With the default stub provider, if a claude binary is on your PATH, Took uses it automatically (your subscription) and prints a one-line notice the first time. To keep the offline stub instead, set "autoDetect": false in the llm config, or export TOOK_NO_AUTO_LLM=1.

Shelling your own claude CLI is the supported way to run on a Claude subscription: Took invokes the official binary and never extracts or replays its token. (The claude-cli provider requires the claude CLI to be installed and logged in.)

Billing (Stripe)

Paid plans are Pro ($9/dev/mo) and Max ($15/dev/mo — adds the Pipp + Pipp Health registers), billed per active seat with graduated volume discounts (1–5 / 6–25 / 26+) and ~2 months off annually. Free stays free; Enterprise is sales-assisted. Billing runs on Took's own Stripe account.

Flow. The marketing pricing CTAs link to app.tookbot.com/billing?plan=…, which signs the user in (GitHub) and calls the backend:

| Route | Auth | Purpose | |---|---|---| | POST /billing/checkout | JWT | Create a subscription Checkout Session for {plan, period, seats} | | POST /billing/webhook | Stripe signature | checkout.session.completed + customer.subscription.* → write plan onto the profile |

The CLI caches that plan on took sync and gates paid features locally (took eval needs Pro; the Pipp / Pipp Health registers need Max).

Backend secrets (SSM SecureString, never in code):

| Param / env | Holds | |---|---| | /took/stripe/secret_key | Stripe secret key (sk_live_…) | | /took/stripe/webhook_secret | Webhook signing secret (whsec_…) | | STRIPE_PRICE_{PRO,MAX}_{MONTH,YEAR} | Price IDs (deploy-time env — not secrets) |

One-time setup

# 1. Create products "Took Pro"/"Took Max" + 4 graduated tiered prices
#    (1–5 / 6–25 / 26+ seats) on the Took account, tagging each price with
#    metadata[plan]=pro|max. Run once; set STRIPE_PRICE_* from the printed IDs.

# 2. Seed secrets in SSM (real secret key; placeholder whsec until step 4):
AWS_PROFILE=widal aws ssm put-parameter --region us-east-1 \
  --name /took/stripe/secret_key --type SecureString --value 'sk_live_…' --overwrite
AWS_PROFILE=widal aws ssm put-parameter --region us-east-1 \
  --name /took/stripe/webhook_secret --type SecureString --value 'whsec_placeholder' --overwrite

# 3. Deploy (price IDs from the env):
STRIPE_PRICE_PRO_MONTH=price_… STRIPE_PRICE_PRO_YEAR=price_… \
STRIPE_PRICE_MAX_MONTH=price_… STRIPE_PRICE_MAX_YEAR=price_… \
  AWS_PROFILE=widal npm --prefix backend run deploy

# 4. In Stripe, add a webhook endpoint at …/billing/webhook (events:
#    checkout.session.completed, customer.subscription.created|updated|deleted),
#    copy the whsec_… into SSM (step 2), and redeploy.

Claude Code Plugin

The Took plugin gives Claude Code native /took:* slash commands and background hooks that run took automatically on key events.

Install via the Marketplace

# In Claude Code:
/plugin marketplace add https://github.com/gettook/took
/plugin install took@took

This adds:

• Slash commands — /took:research, /took:propose, /took:plan, /took:implement, /took:test, /took:secure, /took:prompt, /took:diff, /took:docs-check, /took:pr-ready, /took:ready, /took:pipp, /took:explain, /took:xp
• Subagents — took-coach (RePPIT orchestrator), researcher (pre-build research document), reviewer (diff/PR lens)
• Hooks — UserPromptSubmit (prompt coaching), PreToolUse (guard), PostToolUse (action retrospective — what you did · what you should have done · how to improve, surfaced as a can't-miss note and earned as XP on a real course-correction), PreCompact (cache-to-artifact nudge), Stop (background sync — on by default once you're logged in, so the dashboard stays current without a manual sync; opt out with took sync --auto off)

Background sync also fires right after took ready and took eval (same login + opt-out gate), so an evaluated repo shows up on the dashboard immediately instead of waiting for the session-end Stop hook.

Or install hooks directly

took install-hooks   # writes .git/hooks/pre-commit, pre-push + Claude settings

Status line

Add a one-line Claude Code status line that surfaces the otherwise-invisible right-sizing of your last prompt (size · delegation · risk flags) plus your live XP total and streak:

// .claude/settings.json
{ "statusLine": { "type": "command", "command": "took statusline" } }

It renders e.g. ⬡ took · last: ▲ large (research-then-plan) · auth, payments · 70 XP · 2-day streak, reading entirely from your local .took/ log — no network, no LLM.

Agent-Ready Badge

Add a live badge to your repo after running took badge:

![Agent-Ready](https://shields.io/badge/Agent--Ready-%E2%9C%93-brightgreen)

The badge is backed by the took ready score — an honest signal, not ceremony.

License

MIT — see LICENSE.

Built with the methodology from AI Software Development: From First Prompt to Production Code (themodernsoftware.dev) and Cara's RePPIT Health (for the regulated layer). Took is a coach, not a certification authority.