Using with AI Assistants
Install the codeknit plugin in Claude Code, Codex, or Kiro, keep it current, and ask the assistant structural and duplicate-code questions. The plugin contains one skill, codeknit. The skill tells the assistant when to run codeknit parse, codeknit graph analyze, and codeknit fingerprint, and how to read the .skt output.
You don’t need to install the codeknit binary yourself. The first time the skill runs, it runs its bundled scripts/install-codeknit.sh, which does the following:
- Exits immediately if
codeknitis already on yourPATHor in~/.local/bin. - Otherwise, downloads the latest GitHub release for your OS and architecture.
- Verifies the download against the release
checksums.txt. - Installs the binary to
~/.local/binand prints its absolute path on the last line of output.
If ~/.local/bin is not on your PATH, the assistant calls codeknit by that full path for the rest of the session.
To control the install, set these environment variables:
| Variable | Effect |
|---|---|
CODEKNIT_VERSION |
Pins a release, for example 0.6.0. |
CODEKNIT_INSTALL_DIR |
Changes the install location. |
To install the binary yourself instead, see Installation.
Install the plugin
Section titled “Install the plugin”Pick the section for your assistant.
Claude Code
Section titled “Claude Code”Run these commands in your shell. Inside a Claude Code session, run the same commands as /plugin ....
claude plugin marketplace add awslabs/codeknit --sparse .claude-plugin skillsclaude plugin install codeknit@codeknitcodex plugin marketplace add awslabs/codeknit --sparse .agents --sparse .codex-plugin --sparse skillscodex plugin add codeknit@codeknitKiro IDE
Section titled “Kiro IDE”- Open the Powers panel.
- Choose Add Custom Power, then Import power from GitHub.
- Enter
https://github.com/awslabs/codeknit.
Kiro CLI
Section titled “Kiro CLI”The Kiro CLI installs from a local path, so clone the repository first:
git clone --depth 1 --filter=blob:none --sparse https://github.com/awslabs/codeknit ~/.codeknit-powergit -C ~/.codeknit-power sparse-checkout set skillskiro-cli powers install ~/.codeknit-powerAbout --sparse
Section titled “About --sparse”The --sparse option is optional. It limits the clone to the plugin manifests and skills/ instead of the whole source tree.
Install the skill by hand
Section titled “Install the skill by hand”If your assistant reads Agent Skills but has no plugin support, copy skills/codeknit/ into the skills directory for your assistant:
~/.claude/skills/~/.codex/skills/~/.kiro/skills/
Update the plugin
Section titled “Update the plugin”| Assistant | Command or action |
|---|---|
| Claude Code | claude plugin marketplace update codeknit |
| Codex | codex plugin marketplace upgrade |
| Kiro IDE | Choose Check for updates in the Powers panel. |
| Kiro CLI | Run git -C ~/.codeknit-power pull, then run kiro-cli powers install ~/.codeknit-power again. |
Updating the plugin does not update a binary that is already installed. To change the binary version, set CODEKNIT_VERSION as described above.
If you upgrade codeknit and the extraction changes, symbol IDs can change too. Ask the assistant to regenerate all output rather than mixing chunks from different runs.
What the skill teaches the assistant
Section titled “What the skill teaches the assistant”The skill gives the assistant these rules, so you don’t have to repeat them in every request:
- Pick the command by question.
parseanswers what exists, where it is, and what calls, inherits, or contains what.graph analyzefinds cycles, hubs, dead code, god classes, and bottlenecks.fingerprintfinds copy-paste and refactor candidates.
- Default to
directory-flatoutput. The assistant writes chunked files to./skeleton/and reads only the chunks it needs. It usesinlineoutput only for a single file or a handful of files, becauseinlinedumps everything into the context window. - Read
.sktoutput, not raw source, for structural questions. The assistant opens source files only to inspect or change implementation details, using the line spans from the output. The skill’sreferences/output-format.mdholds the full format. See also the output format reference. - Choose similarity ranges and treat matches as signals. Fingerprints compare structural shape, not intent. The assistant reads both symbols of a pair before proposing a refactor.
Ask for a structural analysis
Section titled “Ask for a structural analysis”- Ask the assistant to analyze your codebase structure. For example: “Map the structure of
./srcand tell me which modules depend on the auth package.” - The assistant ensures the binary is installed, then runs
codeknit parsewith edges enabled and reads the.sktoutput. - Ask follow-up questions about dependencies, call chains, or dead code. The assistant answers from the output.
- For deeper analysis, ask for a structural review. For example: “Find cyclic dependencies and god classes in
./src.” The assistant runscodeknit graph analyzeand reads the report.
Relationships marked [unresolved] or [ambiguous] in the output are uncertain, not confirmed dependencies. Treat answers that rest on them as candidates to verify.
For the commands behind these requests, see the parse command guide and the graph commands guide.
Ask for duplicate detection
Section titled “Ask for duplicate detection”- Ask the assistant to find duplicated code. For example: “Find copy-pasted functions in
./src.” - The assistant runs
codeknit fingerprintand reads the[duplicates]section of./skeleton/fingerprints.skt. - The assistant opens both symbols of each flagged pair, then proposes a refactor.
- If the results are noisy, ask it to adjust the similarity range or to add semantic reranking. Reranking requires a local Ollama server with an embedding model pulled.
For the options behind these requests, see the fingerprint command guide.
- Remind the assistant to read
.sktfiles, not raw source, for structural questions. This keeps context small, since the format is compact and holds symbols, relationships, and line spans. - Use
graph analyzefor code quality insights. Findings are review candidates, because external callers and dynamic dispatch can change the result. - Run fingerprint before a large refactor to spot copy-paste that should be consolidated.
- If the assistant re-runs
parseinto a directory that already holds.sktoutput, codeknit refuses to write. Ask it to pass--cleanto replace the earlier output. - If the binary download fails (offline or unsupported platform), get a release manually from the releases page, or see Installation.
- If a run reports partial results, check stderr and the
[errors]section. See analysis reliability for the details.