Create Terraphim-tui hook guide for Claude code#303
Merged
AlexMikhalev merged 6 commits intoNov 16, 2025
Conversation
Add comprehensive example and guide for using Terraphim-TUI as a hook for Claude Code CLI to enforce package manager preferences (npm/yarn/pnpm -> bun). Components added: - Hook script (terraphim-package-manager-hook.sh) with 3 modes: replace, suggest, passive - Test suite (test-hook.sh) with 7 automated tests - Example Claude Code configuration (claude-settings-example.json) - Comprehensive README with quick start, examples, and troubleshooting - Validation checklist (VALIDATION.md) for verifying the integration Features: - Knowledge graph-based text replacement using existing bun synonyms - Case-insensitive matching with Aho-Corasick automata - Configurable modes via environment variables - Graceful error handling with fallback to original input - Sub-100ms execution time All 8 existing terraphim_tui replace tests pass: - test_replace_npm_to_bun ✅ - test_replace_yarn_to_bun ✅ - test_replace_pnpm_install_to_bun ✅ - test_replace_yarn_install_to_bun ✅ - test_replace_with_markdown_format ✅ - test_replace_help_output ✅ - test_extract_clean_output_helper ✅ - test_extract_clean_output_multiline ✅ The hook leverages existing knowledge graph files in docs/src/kg/: - bun.md: synonyms for package managers (pnpm, npm, yarn) - bun_install.md: synonyms for install commands This provides a complete, production-ready example of integrating Terraphim's knowledge graph capabilities with Claude Code hooks.
Prevent build artifacts like crates/ directory from being tracked
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+16
to
+20
| if [ -f "$(git rev-parse --show-toplevel 2>/dev/null)/target/release/terraphim-tui" ]; then | ||
| TERRAPHIM_TUI_BIN="$(git rev-parse --show-toplevel)/target/release/terraphim-tui" | ||
| else | ||
| echo "Warning: terraphim-tui not found. Install it or build with: cargo build --release -p terraphim_tui" >&2 | ||
| exit 0 # Don't fail the hook, just pass through |
There was a problem hiding this comment.
The early exit path intended to “pass through” when terraphim-tui cannot be found simply prints a warning and returns without ever reading or echoing stdin. Because the hook outputs nothing, Claude Code will treat the prompt as an empty string whenever the binary is missing or the autodetection fails, effectively dropping the user's request instead of leaving it unchanged. This should read the input and emit it unchanged before exiting, or defer the exit until after the original text has been forwarded.
Useful? React with 👍 / 👎.
Expand the Terraphim-Claude integration with a complete Claude Skills implementation, providing an alternative to hooks for more context-aware package manager replacement. New Components: - Claude Skill definition (SKILL.md) with YAML frontmatter - Helper script (replace.sh) that changes to repo root - Comprehensive skill documentation (README.md) - Example files (package.json, script.sh) - Complete integration guide comparing both approaches Key Features: - Progressive disclosure architecture (metadata → instructions → resources) - Automatic activation based on context - Conversational with explanations - Cross-platform (Claude Code, Claude.ai, Claude API) - Works alongside hooks for maximum flexibility Documentation: - TERRAPHIM_CLAUDE_INTEGRATION.md: Complete comparison guide - Skills vs Hooks decision matrix - Platform-specific notes and best practices - Advanced integration patterns (combining both approaches) Files: - examples/claude-skills/terraphim-package-manager/SKILL.md - examples/claude-skills/terraphim-package-manager/README.md - examples/claude-skills/terraphim-package-manager/replace.sh - examples/claude-skills/terraphim-package-manager/examples/ - examples/TERRAPHIM_CLAUDE_INTEGRATION.md - examples/claude-skills/.gitignore Updated: - examples/claude-code-hooks/README.md: Added reference to skills approach The skill follows Claude's official agent skills format and can be: - Used in Claude Code via ~/.claude/skills/ - Uploaded to Claude.ai as a zip file - Referenced via skill_id in Claude API calls Both hooks and skills use the same terraphim-tui backend and knowledge graph, providing flexible integration options for different use cases.
This commit expands the Terraphim-Claude integration with a second use case: replacing Claude Code attribution with Terraphim AI attribution. Changes: - Fixed docs/src/kg/knowledge-graph-system.md to prevent documentation synonym examples from being parsed as actual KG entries (caused every character to be replaced with "knowledge-graph-system") - Added new KG files for attribution replacement: - terraphim_ai.md - Maps "Claude Code" → terraphim_ai - https___terraphim_ai.md - Maps Claude URLs → Terraphim URLs - generated_with_terraphim.md - Maps generation attribution text - noreply_terraphim.md - Maps email addresses - Updated TERRAPHIM_CLAUDE_INTEGRATION.md with both examples - Documented filename-based replacement limitation (spaces → underscores) Both use cases now work: 1. Package manager: "npm install" → "bun_install" 2. Attribution: "[Claude Code]..." → "[terraphim_ai]..." The replacements use filename stems as replacement text, so spaces become underscores and special characters are converted. This is a fundamental design where filenames serve as normalized terms.
This commit adds a complete framework for evaluating whether AI agents improve or deteriorate codebases using Terraphim's knowledge graph capabilities. Components Added: 1. Design Document (CODEBASE_EVALUATION_DESIGN.md): - Complete evaluation methodology - Step-by-step procedures - Metrics reference and verdict logic - CI/CD integration examples - Firecracker VM integration patterns 2. Evaluation Scripts (examples/codebase-evaluation/scripts/): - baseline-evaluation.sh: Capture initial metrics - post-evaluation.sh: Capture post-change metrics - compare-evaluations.sh: Generate verdict with delta analysis - evaluate-ai-agent.sh: Master workflow script 3. Knowledge Graph Templates (kg-templates/): - code-quality.md: Code smells and technical debt patterns - bug-patterns.md: Common errors and anti-patterns - performance.md: Bottleneck detection patterns - security.md: Vulnerability patterns 4. Documentation: - README.md: Quick start and usage guide - Integration examples for GitHub Actions, GitLab CI - Updated TERRAPHIM_CLAUDE_INTEGRATION.md with evaluation section Key Features: - Deterministic evaluation using Aho-Corasick automata - Role-based perspectives (Code Reviewer, Security Auditor, etc.) - Quantifiable metrics: clippy warnings, anti-patterns, TODOs - Automated verdict generation: Improvement, Deterioration, or Neutral - CI/CD ready with exit code 1 on deterioration - Privacy-first: All evaluation runs locally Use Cases: 1. Evaluate PR from AI agent before merge 2. Continuous quality monitoring in CI/CD 3. Historical trend analysis across evaluations 4. Multi-dimensional evaluation (security + performance + quality) This framework enables objective, repeatable assessment of AI-generated code changes using Terraphim's existing infrastructure.
…ation This commit adds extensive documentation for the new Terraphim-Claude integration features, making them discoverable and easy to adopt. Changes: 1. README.md Updates: - Added new "Claude Code Integration" section before Contributing - Highlighted text replacement (Hooks & Skills) - Featured codebase quality evaluation with examples - Included GitHub Actions integration snippet - Made features discoverable from main README 2. Blog Post (BLOG_POST_CLAUDE_INTEGRATION.md): - Comprehensive 7000+ word blog post - Explains the "why" behind objective AI evaluation - Three pillars: Hooks, Skills, Evaluation - Real-world use cases and examples - Technical deep-dive into Aho-Corasick automata - Step-by-step getting started guide - Future roadmap and community links 3. Announcement (ANNOUNCEMENT.md): - Concise announcement for release notes - Quick start instructions - Key benefits and use cases - CI/CD integration example - Links to all documentation - Community and contribution info Documentation Highlights: - Clear value proposition for each feature - Copy-paste examples for immediate use - Real output demonstrations - Multi-role evaluation examples - CI/CD integration patterns - Privacy and determinism emphasis All documentation cross-references existing guides and examples, creating a cohesive documentation structure for users to explore the new capabilities.
AlexMikhalev
deleted the
claude/terraphim-bun-hook-guide-011CV536xajudBzw8gdSFNV7
branch
AlexMikhalev
pushed a commit
that referenced
this pull request
Apr 5, 2026
…raw dump tool_use messages containing raw file content were being kept as-is by unwrap_opencode_protocol(), causing the heuristic keyword scanner to pick up words like "critical" from source code inside tool payloads and create bogus CRITICAL findings filed as Gitea issues (e.g. #303). Now tool_use and other non-text protocol messages are formatted as brief summaries (e.g. [tool_use: read /path/to/file completed]) instead of dumping the raw JSON payload. Refs #303 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
AlexMikhalev
pushed a commit
that referenced
this pull request
Apr 5, 2026
…raw dump tool_use messages containing raw file content were being kept as-is by unwrap_opencode_protocol(), causing the heuristic keyword scanner to pick up words like "critical" from source code inside tool payloads and create bogus CRITICAL findings filed as Gitea issues (e.g. #303). Now tool_use and other non-text protocol messages are formatted as brief summaries (e.g. [tool_use: read /path/to/file completed]) instead of dumping the raw JSON payload. Refs #303 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
AlexMikhalev
added a commit
that referenced
this pull request
Apr 25, 2026
…e-011CV536xajudBzw8gdSFNV7 Create Terraphim-tui hook guide for Claude code
AlexMikhalev
pushed a commit
that referenced
this pull request
Apr 25, 2026
…raw dump tool_use messages containing raw file content were being kept as-is by unwrap_opencode_protocol(), causing the heuristic keyword scanner to pick up words like "critical" from source code inside tool payloads and create bogus CRITICAL findings filed as Gitea issues (e.g. #303). Now tool_use and other non-text protocol messages are formatted as brief summaries (e.g. [tool_use: read /path/to/file completed]) instead of dumping the raw JSON payload. Refs #303 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
AlexMikhalev
added a commit
that referenced
this pull request
May 1, 2026
…e-011CV536xajudBzw8gdSFNV7 Create Terraphim-tui hook guide for Claude code
AlexMikhalev
pushed a commit
that referenced
this pull request
May 1, 2026
…raw dump tool_use messages containing raw file content were being kept as-is by unwrap_opencode_protocol(), causing the heuristic keyword scanner to pick up words like "critical" from source code inside tool payloads and create bogus CRITICAL findings filed as Gitea issues (e.g. #303). Now tool_use and other non-text protocol messages are formatted as brief summaries (e.g. [tool_use: read /path/to/file completed]) instead of dumping the raw JSON payload. Refs #303 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.