# Winkers

**Architectural context layer for AI coding agents.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/n1cke1/winkers/actions/workflows/ci.yml/badge.svg)](https://github.com/n1cke1/winkers/actions)

Winkers builds a function-level dependency graph via tree-sitter, enriches it
with semantic context via Claude API, and serves both to AI agents via MCP.
The agent gets project structure, constraints, and conventions before writing
any code.

## Quick start

```bash
pipx install winkers              # or: pip install winkers
cd your-project
export ANTHROPIC_API_KEY=sk-ant-...   # optional, for semantic enrichment
winkers init                      # graph + semantic + MCP registration
```

Auto-detects Claude Code or Cursor and registers the MCP server.
Without the API key, the graph still works — semantic enrichment is skipped.

## What it does

**Three-file model** — zero duplication:

| File | Contains | Generated by |
|------|----------|-------------|
| `graph.json` | Files, functions, call edges, import edges, complexity | tree-sitter parse |
| `semantic.json` | Zone intents, data flow, domain context, constraints | Claude API (one call) |
| `rules.json` | Coding conventions with detection + wrong_approach | LLM audit + detectors |

## MCP tools

| Tool | Purpose |
|------|---------|
| `orient(include, zone?, min_callers?)` | Project map: zones, conventions, hotspots, routes, UI map, functions graph |
| `scope(function?, file?)` | Deep context: callers, callees, related rules, semantic context |
| `convention_read(target)` | Zone intent, data flow, domain context, checklist |
| `rule_read(category)` | All rules for a category with wrong_approach |

The agent calls `orient(["map","conventions"])` first, then `scope()` for
files it plans to modify. Token budget (default 2000) prevents context overflow.

## CLI commands

```bash
winkers init                   # build graph + semantic + register MCP
winkers init --no-semantic     # graph only, no API call
winkers init --force           # force semantic re-enrichment
winkers serve                  # MCP server (stdio)
winkers dashboard              # browser graph at localhost:7420
winkers doctor                 # check dependencies, graph, API key
winkers record                 # record agent sessions for learning
winkers analyze                # find knowledge gaps in sessions (Haiku)
winkers improve                # show accumulated insights
winkers improve --apply        # inject insights into semantic.json
winkers protect --startup      # trace startup import chain
winkers hooks                  # install commit format + git hooks
winkers commits --range R      # normalize commit messages
winkers conventions-migrate    # import old conventions to rules.json
```

## Improve loop

Winkers learns from agent sessions:

1. **Record** — `winkers record` parses Claude Code transcripts, scores sessions
2. **Analyze** — `winkers analyze` sends traces to Haiku, finds knowledge gaps
3. **Accumulate** — insights deduplicate (fuzzy match), priority escalates with repetition
4. **Apply** — `winkers improve --apply` injects high-priority insights into semantic.json
5. **Re-enrich** — next `winkers init` feeds insights into the Claude API call

## Dashboard

Interactive Cytoscape.js graph with:
- Zone colors and caller-based sizing
- Tech debt layer (complexity, long functions, monster files)
- Session history and insight viewer
- Right-click to view source

## Languages

Python, TypeScript, JavaScript, Java, Go, Rust, C#

## Installation

```bash
# Core (graph + MCP, no API calls)
pipx install winkers

# With semantic enrichment (Claude API)
pipx install winkers[semantic]

# Development
git clone https://github.com/n1cke1/winkers.git
cd winkers
pip install -e ".[dev]"
pytest tests/ -v
```

## Privacy

- **Local by default.** Graph parsing uses tree-sitter locally. No data leaves
  your machine unless you opt in to semantic enrichment.
- **Semantic enrichment** sends source code to the Anthropic API (one call per
  `winkers init`). Set `ANTHROPIC_API_KEY` to enable. Use `--no-semantic` to
  skip.
- **Session analysis** sends session traces (tool calls, not source code) to
  Haiku via `winkers analyze`. Costs ~$0.01/session.
- **No telemetry.** Winkers does not phone home, collect usage data, or send
  anything anywhere without an explicit command.

## License

MIT
