Metadata-Version: 2.4
Name: winkers
Version: 0.7.5
Summary: Architectural context layer for AI coding agents — function-level dependency graph via MCP
Project-URL: Homepage, https://github.com/n1cke1/winkers
Project-URL: Repository, https://github.com/n1cke1/winkers
Project-URL: Issues, https://github.com/n1cke1/winkers/issues
Author: n1cke1
License: MIT
License-File: LICENSE
Keywords: ai,code-analysis,dependency-graph,mcp,tree-sitter
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: click>=8.1.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tree-sitter-c-sharp>=0.23.0
Requires-Dist: tree-sitter-go>=0.23.0
Requires-Dist: tree-sitter-java>=0.23.0
Requires-Dist: tree-sitter-javascript>=0.23.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: tree-sitter-rust>=0.23.0
Requires-Dist: tree-sitter-typescript>=0.23.0
Requires-Dist: tree-sitter>=0.23.0
Provides-Extra: dev
Requires-Dist: anthropic>=0.40.0; extra == 'dev'
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: semantic
Requires-Dist: anthropic>=0.40.0; extra == 'semantic'
Description-Content-Type: text/markdown

# 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
