winkers 0.8.0

Architectural context layer for AI coding agents — function-level dependency graph via MCP

Winkers

Architectural context layer for AI coding agents.

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

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

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

# 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