Documentation
Get started in 5 minutes
Took is a local CLI. No account, no cloud, no API keys required for the free tier. Install, initialise, and you're coaching your first prompt.
getting started
# 1. Install the global CLI
$ npm install -g @gettook/took
✓ took@0.9.1 installed · try: took --version
# 2. Initialise in your repo
$ cd my-project && took init
✓ Created .took/ · .took/config.json · .took/rules.json
Detected: Jest tests ✓ · ESLint ✓ · README ✓ · AGENTS.md ✗
# 3. Run an agent-readiness report
$ took ready
Agent-readiness score: 6 / 10
⚠ Missing: AGENTS.md · .env.example · hermetic test runner
✓ Passing: tests · lint · README · gitignore
# 4. Install git + agent hooks
$ took install-hooks
✓ pre-commit hook · registered ✓
✓ pre-push hook · registered ✓
$
Claude Code plugin
Install in Claude Code
The Claude Code plugin installs Took's hooks directly into your agent session — coaching prompts, guarding tool calls, reviewing diffs, and protecting context budget.
claude-code — plugin install
$ /plugin marketplace add gettook/took
✓ Found gettook/took@0.9.1
$ /plugin install took@took
✓ UserPromptSubmit · PreToolUse · PostToolUse · PreCompact · all registered
Took is watching. Coach mode enabled.
$
Command table
| Command | Description | Tier |
|---|---|---|
took init | Initialise .took/ in your repo. Detects tests, docs, build, gitignore, AGENTS.md. | free |
took ready | Agent-readiness report. Scores the repo against the agent-ready checklist. | free |
took prompt"<task>" | Right-size a task. Returns a coaching response + copy-ready prompt for the appropriate RePPIT phase. | free |
took diff | Review the current diff: scope, missing tests, risky edits, out-of-scope files. | free |
took docs-check | Check for README, .env.example, and AGENTS.md drift vs the current diff. | free |
took pr-ready | PR readiness score — evidence, risk notes, rollback plan, test coverage. | free |
took xp | View your local XP ledger. Categories: Research, Plan, Guard, Test, Docs, Judgment. | free |
took install-hooks | Install pre-commit and pre-push git hooks. Also installs agent hooks for Claude Code. | free |
took stats | Git-derived improvement trends: scoped-diff rate, test co-change, revert rate. | v1 |
took badge | Generate a Took Score or Agent-Ready README badge (shields.io endpoint). | v1 |
took pipp | Toggle the Pipp education register. Narrates agent actions in plain English. | Pro |
took explain<action> | Plain-English explanation of a specific agent action with cited resources. | Pro (Pipp) |
took scan | Heightened security, secrets, and PHI scan across the current diff. | v1 / Pipp |
took learn | Show your Pipp learning profile — mastered concepts, streak, growing edges. | Pro (Pipp) |
took secure | Run the Secure phase against the current diff. HIPAA/SOC2/HITRUST checklists. | Pipp Health |
took health init | Scaffold HIPAA/SOC2/HITRUST checklists for your workspace. | Pipp Health |
Hook architecture
Took operates through hooks — intercepting key events in the agent lifecycle to coach, guard, and review without replacing the agent itself.
UserPromptSubmitBefore agent receives your prompt
Right-sizes the task; coaches Research-first for non-trivial tasks; Pipp translates to plain language.
PreToolUseBefore each tool call
Guards scope blowouts, dangerous commands (file delete, deploy, migration), context budget warnings. Pipp: default Guard/Strict.
PostToolUseAfter each tool call
Diff review: missing tests, out-of-scope edits, docs drift. Pipp: narrates every action.
PreCompactBefore context compaction
Encourages caching progress to an artifact before context is lost. Protects the context budget.
Pre-CommitGit pre-commit hook
Docs/playbook drift, secrets, test gaps, PHI scan (Pipp Health).
Pre-PushGit pre-push hook
PR readiness score before the branch is pushed.
Secure gateAfter Test in regulated mode
Compliance checklists vs diff. Loops until clean. Pipp Health only.
Modes
Coach
Warn-only. Default for engineers.
Guard
Confirm on risky actions. Pipp default.
Strict
Block high-risk. Pipp option.
Team
Shared rules from .took/rules.json.
Regulated workflow setup
Pipp Health requires a separate add-on subscription. Once enabled, scaffold your compliance checklists and the Secure phase activates automatically after Test.
pipp health — setup
$ took health init
✓ Scaffolded .took/checklists/hipaa.json
✓ Scaffolded .took/checklists/soc2.json
Edit to enable/disable controls for your workspace
# run standalone compliance scan anytime
$ took secure
Scanning diff against HIPAA + SOC2 checklists...
$
Disclaimer: Pipp Health assesses and surfaces compliance signals. It does not certify compliance with HIPAA, SOC 2, HITRUST, or any other framework. It is not a substitute for qualified legal counsel or a security auditor. Learn more →