knowhook 0.1.1

Compaction-resistant context layer for AI coding agents

know

AI-powered context drift detector for coding projects. Watches git diffs and uses an LLM to detect when code changes diverge from the planned task.

Installation

pip install know

Quick Start

# Launch the interactive TUI
know

# Or use one-shot CLI commands
know init            # Create .context.yaml
know status          # Check for context drift
know update --task "Implement auth"
know hook install    # Auto-check on commits

Interactive TUI

Running know with no arguments opens an interactive dashboard with slash commands:

know> /help

Commands

Command	Description
/status	Run drift check against current changes
/init	Create a .context.yaml in current dir
/update	Interactively update task, goals, rules
/key	Set or view API keys
/model	Switch LLM model
/settings	Show current configuration
/hook	Install/uninstall git pre-commit hook
/help	Show all available commands
/quit	Exit the TUI

Tab-completion and command history are built in.

API Keys

know ships with a built-in Gemini API key so it works out of the box. To use your own key:

know> /key gemini
API key (input hidden): ****

Keys are stored in ~/.know/config.yaml (permissions: owner-only read/write).

Using Other Providers

know> /model gpt-4o
know> /key openai

know> /model claude-sonnet-4-20250514
know> /key anthropic

know> /model ollama/llama3

Any model supported by LiteLLM can be used.

You can also set keys via environment variables (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY) — these take priority over stored keys.

.context.yaml Schema

project_name: my-project
goals:
  - Define project goals
current_task:
  id: "1"
  description: Initial setup
  status: active        # active | skipped | completed
tech_stack:
  - python
  - fastapi
rules:
  - No print statements in production code

CLI Commands

know init [DIRECTORY]

Create a default .context.yaml in the specified directory (defaults to current directory).

know status [--fail-on-drift]

Analyze git changes against your active context. Shows a MATCH (green) or DRIFT (red) panel. Use --fail-on-drift to exit with code 1 on drift (useful in CI/hooks).

know update

Quick-edit your .context.yaml from the command line:

• --task TEXT — set current task description
• --task-id TEXT — set task ID
• --task-status [active|skipped|completed] — set task status
• --add-rule TEXT — append a rule
• --add-goal TEXT — append a goal

know hook install

Install a git pre-commit hook that runs know status --fail-on-drift before each commit.

know hook uninstall

Remove the pre-commit hook. Restores any backed-up hook.