Metadata-Version: 2.4
Name: knowhook
Version: 0.1.0
Summary: Compaction-resistant context layer for AI coding agents
Author: adda247
License-Expression: MIT
Project-URL: Homepage, https://github.com/adda247/know
Project-URL: Repository, https://github.com/adda247/know
Keywords: ai,context,claude,compaction,coding-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]
Requires-Dist: rich
Requires-Dist: pyyaml
Requires-Dist: pydantic
Requires-Dist: prompt-toolkit>=3.0
Dynamic: license-file

# 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

```bash
pip install know
```

## Quick Start

```bash
# 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](https://docs.litellm.ai/docs/providers) 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

```yaml
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.
