opentuple

OpenTuple

Automatic style intelligence for AI coding agents.

OpenTuple indexes a repository, statistically mines its coding conventions, and serves them to AI agents (Claude Code, Cursor, Codex) over MCP — so generated code matches how the codebase is actually written.

The problem

Every AI coding tool now reads a hand-written convention file — CLAUDE.md, AGENTS.md, .cursorrules. Someone has to write it, keep it current, and hope it covers the conventions that matter. A typical hand-written file captures 20–30 rules for an entire repository.

OpenTuple discovers conventions automatically, with statistical evidence, scoped to each subsystem.

What it finds

Pointed at Kubernetes (105,715 functions across 10,869 files), OpenTuple indexes the full repo in 28 seconds and mines 27,812 patterns. Examples of real conventions it discovered, with no human input:

• Lock/Unlock pairing at 100% co-occurrence in dynamic-resource-allocation/internal/workqueue — a mutex-heavy subsystem where every lock has an unlock
• fmt.Errorf absent from client-go typed clients — 11% of functions repo-wide call Errorf, 0% in that layer; it returns structured errors, never formats strings. An architectural boundary, discovered statistically
• CreateTemp → CloseAndRemove pairing at 100% in client-go/tools/clientcmd — a temp-file lifecycle convention
• Per-subsystem numeric profiles: average function length, parameter counts, nesting depth, error-handling style — different for every one of 2,929 subsystems

Quickstart

go install github.com/CtrlAltDelete-Ops/opentuple/cmd/opentuple@latest

# Index a repository (interactive speed-mode selector)
opentuple index ./my-project

# Check what was indexed
opentuple status ./my-project

# Serve style context to AI agents over MCP
opentuple serve ./my-project

Hooking up an AI agent

OpenTuple exposes one MCP tool: get_style_context. The agent calls it with a file path; OpenTuple resolves the most specific subsystem and returns rules, tendencies, example functions, project vocabulary, and subsystem conventions in a single round-trip.

Claude Code (.mcp.json in your project, or claude mcp add):

{
  "mcpServers": {
    "opentuple": {
      "command": "opentuple",
      "args": ["serve", "/absolute/path/to/your/repo"]
    }
  }
}

Cursor (Settings → MCP → Add server): same command/args shape.

Index the repo first (opentuple index); serve refuses to start on an unindexed repo.

How it works

A concurrent pipeline (gitignore-aware walker → tree-sitter parser pool → batched SQLite writer) extracts every function with a 19-field behavioral fingerprint, a name-resolution call graph, and project vocabulary. Post-processing builds per-directory subsystem profiles and mines six pattern types:

Patterns at ≥95% confidence are served as rules; 75–95% as tendencies. Every pattern carries support counts, evidence examples, and counter-examples.

Throughput: ~3,800 functions/second (Apple Silicon, balanced mode). fzf: 1.3s · gh-cli: 1.8s · Kubernetes: 28s.

Accuracy, honestly

Pattern mining is statistical. In a manual audit of 30 sampled patterns against Kubernetes source, 83% validated as real or substantially real; call-graph-based patterns (helper usage/pairing) validated at 100%. Fingerprint-derived patterns are weaker and improving — known issues are tracked in the issues tab. Treat tendencies as suggestions, rules as strong signals, and neither as ground truth.

Languages

Go, C, Python, JavaScript, TypeScript, Rust — via tree-sitter. Language-agnostic fingerprint fields work everywhere; language-specific fields (error style, cleanup patterns, allocation counting) are deepest for Go.

Roadmap

• opentuple generate — emit an AGENTS.md / CLAUDE.md from mined patterns, so the output works with every tool, no MCP required
• Semantic example retrieval via local embeddings (Ollama + jina-code-embeddings)
• Self-linter: validate agent-generated code against mined patterns
• Incremental re-indexing

License

Apache-2.0