chameleon

chameleon

"Code that blends in."

chameleon learns your repo's actual conventions and injects archetype-aware guidance on every edit, so AI-generated code matches your existing style on the first try. It supports TypeScript/JavaScript, Ruby, and Python as first-class languages — framework-agnostic by default (it learns your repo's own conventions, so any framework works), with deeper awareness where a framework's conventions are strong: Rails for Ruby, and Django, DRF, Flask, and FastAPI for Python.

Every Edit/Write gets a block like this: the matched archetype, the canonical witness to mirror, and (when your team has taught a competing import) the real off-pattern line not to copy. Measured to lift first-try wrapper adoption by +100pp in both TypeScript and Ruby.

Quickstart

Before you start, you need uv and Node.js 20+ on your PATH. Ruby 3.0+ is also needed if you edit Ruby repos. (Python repos need nothing extra — chameleon parses them with its own bundled libcst.) On a fresh machine, docs/install.md has copy-paste setup for macOS, Linux, and Windows, plus a check for each tool. Skip ahead if you already have them.

1. Install the plugin. In any Claude Code session:

/plugin marketplace add crisnahine/chameleon
/plugin install chameleon@chameleon

Restart Claude Code. Confirm it loaded by asking "What chameleon tools do you have?"

2. Profile a repo. Open any TypeScript/JavaScript, Ruby, or Python repo — any framework works, with deeper awareness for Rails (Ruby) and Django / DRF / Flask / FastAPI (Python) — then:

/chameleon-init    # build a profile (a few seconds for repos under 5k files)
/chameleon-trust   # approve it for your user

After that, every Edit/Write in that repo gets archetype-aware context automatically.

Why

AI-generated code in established codebases routinely violates local conventions: wrong file location, off-pattern naming, missed team idioms, divergent error handling. Reviewer time gets spent on style and shape instead of logic and security.

chameleon clusters your actual code patterns (AST plus statistical analysis), captures team-specific idioms (/chameleon-teach), and injects archetype-keyed guidance per edit so the model writes code that fits.

How it works

1. Bootstrap. /chameleon-init locks the repo's production branch (auto-detected from the origin default branch; you are asked only when the signal is ambiguous), materializes that branch's tree from local git objects, runs an AST scan over it, clusters files into archetypes by their structural signature, picks a canonical example per archetype, and writes the .chameleon/ profile, committed to git and team-shared. The profile reflects the production line no matter which feature branch you happen to have checked out.

2. Trust. /chameleon-trust is a per-user, per-repo approval gate. Same mental model as git config --get user.signingkey: the profile lives in the repo, the trust grant lives on your machine.

3. Per-edit context. Before every Edit/Write/NotebookEdit, the PreToolUse hook asks the chameleon MCP server for the matched archetype's canonical excerpt, rules, and idioms, then injects them as a <chameleon-context> block.

4. Teach. /chameleon-teach captures idioms an AST cannot infer: banned imports, mandatory wrappers, custom HTTP clients, internal conventions. They persist to .chameleon/idioms.md and surface through the trust gate so reviewers see them before granting trust.

5. Drift detection. Per-edit confidence is tracked in ~/.local/share/chameleon/<repo_id>/drift.db. When the profile no longer matches reality, or the locked production branch's tip moves past the commit the profile was derived from, /chameleon-status escalates and recommends /chameleon-refresh.

Because the skills trigger automatically, you do not need to do anything special after install. Edits in a trusted, profiled repo just blend in.

Install

The Quickstart above has the two commands for Claude Code. For the full guide (per-OS prerequisite setup for macOS, Linux, and Windows, verification, updating, uninstall, and troubleshooting) see docs/install.md.

Workflow

1. /chameleon-init bootstraps a profile. It runs the AST scan, clusters files into archetypes, selects canonical examples, and writes the .chameleon/ profile. Commit the result.