Terraphim AI documentation

Development Setup Guide

This guide walks you through setting up a development environment for contributing to Terraphim AI, including code quality tools and pre-commit hooks.

Prerequisites

Required

  • Git: Version control system
  • Rust: Latest stable version via rustup
  • Node.js: Version 18+ for desktop app development
  • Yarn: Package manager for JavaScript dependencies

Optional but Recommended

  • Pre-commit hook manager: One of the following:
    • prek (Rust-based, no Python required)
    • lefthook (Go-based, single binary)
    • pre-commit (Python-based, original)

Quick Start

  1. Clone the repository:
git clone https://github.com/terraphim/terraphim-ai.git
cd terraphim-ai
  1. Install development dependencies:
# Install Rust dependencies
cargo build

# Install desktop dependencies
cd desktop
yarn install
cd ..
  1. Set up code quality tools:
./scripts/install-hooks.sh
  1. Configure Git remotes (if working with private code):
# Add private repository remote
git remote add private [email protected]:zestic-ai/terraphim-private.git

This script will automatically:

  • Detect available hook managers (prek, lefthook, pre-commit)
  • Install appropriate hooks
  • Set up Biome for JavaScript/TypeScript formatting
  • Create secrets detection baseline
  • Install native Git hooks as fallback
  • Set up branch protection validation

Pre-commit Hooks Overview

Our pre-commit hooks enforce code quality and security standards:

Code Quality Checks

  • Rust formatting: cargo fmt --check
  • Rust linting: cargo clippy with strict warnings
  • JavaScript/TypeScript: Biome for linting and formatting
  • Trailing whitespace: Automatic removal
  • File syntax: YAML, TOML, JSON validation

Security Checks

  • Secret detection: Prevents accidental credential commits
  • Private key detection: Blocks SSH keys and certificates
  • Large file prevention: Stops accidental binary commits (>1MB)

Commit Standards

  • Conventional commits: Enforces structured commit messages
  • Message validation: Checks format and content

Branch Protection System

Terraphim AI uses a dual-repository approach with comprehensive branch protection:

Repository Structure

  • Public Repository (terraphim/terraphim-ai): Open-source code only
  • Private Repository (zestic-ai/terraphim-private): Proprietary and sensitive code

Pre-Push Hook Protection

The repository includes a pre-push hook that automatically validates:

Branch Naming Validation

Blocked patterns (will be rejected):

private-*, private_*          # Use private repository
internal-*, internal_*        # Use private repository
client-*, client_*            # Use private repository
secret-*, secret_*            # Use private repository
wip-private-*, wip-private_*  # Use private repository
customer-*, customer_*        # Use private repository
proprietary-*, proprietary_*  # Use private repository
confidential-*, confidential_* # Use private repository

Allowed patterns:

feat/new-feature
fix/bug-fix
docs/update-readme
refactor/cleanup
test/add-tests
wip/experimental
experimental/new-algorithm

Content Validation

  • Commit message scanning: Blocks [PRIVATE], [INTERNAL], private:, etc.
  • Sensitive keyword detection: Scans for truthforge, private.*cloud, etc.
  • File pattern validation: Uses .gitprivateignore for custom patterns

Working with Private Code

If you need to work with private or sensitive code:

  1. Switch to private repository:
git remote set-url origin [email protected]:zestic-ai/terraphim-private.git
  1. Create private branch:
git checkout -b private-feature
  1. Develop and push normally:
git add .
git commit -m "feat: add private feature"
git push origin private-feature
  1. Switch back to public (when ready):
git remote set-url origin https://github.com/terraphim/terraphim-ai.git

Troubleshooting Branch Protection

"Branch matches private pattern" Error

✗ Branch 'private_tf' matches private pattern '^private_'
Private branches should not be pushed to public remotes.
Push to private remote instead: git push private private_tf

Solution:

# Configure branch for private remote
git config branch.private_tf.remote private
git config branch.private_tf.pushRemote private

# Push to private repository
git push private private_tf

"Sensitive keyword found" Error

✗ Sensitive keyword 'truthforge' found in file changes
Remove sensitive content before pushing to public remote.

Solution:

  • Remove or replace sensitive content
  • Use private repository for sensitive development
  • Update .gitprivateignore if false positive

For detailed information, see Branch Protection and Security.

Hook Manager Options

Option 1: prek (Recommended - No Python Required)

Installation:

# Linux/macOS
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/j178/prek/releases/download/v0.1.4/prek-installer.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://github.com/j178/prek/releases/download/v0.1.4/prek-installer.ps1 | iex"

# Then install hooks
prek install
prek install --hook-type commit-msg

Features:

  • Single binary, no dependencies
  • ~10x faster than pre-commit
  • Fully compatible with existing configurations
  • Built in Rust

Option 2: lefthook (Go-based Alternative)

Installation:

# Install lefthook
curl -sSfL https://raw.githubusercontent.com/evilmartians/lefthook/master/install.sh | sh

# Or via Homebrew
brew install lefthook

# Install hooks
lefthook install

Features:

  • Single binary (Go-based)
  • Parallel hook execution
  • YAML configuration
  • Fast and lightweight

Option 3: pre-commit (Python-based Original)

Installation:

# Via pip
pip install pre-commit

# Via Homebrew
brew install pre-commit

# Install hooks
pre-commit install
pre-commit install --hook-type commit-msg

Features:

  • Original and most mature
  • Extensive plugin ecosystem
  • Wide language support
  • Requires Python runtime

Option 4: Native Git Hooks (Fallback)

If you prefer not to install additional tools, native Git hooks are automatically installed as a fallback:

# These are copied to .git/hooks/ by the install script
.git/hooks/pre-commit
.git/hooks/commit-msg

Manual Commands

Running Hooks Manually

# Run all pre-commit checks manually
./scripts/hooks/pre-commit

# Check commit message format
./scripts/hooks/commit-msg .git/COMMIT_EDITMSG

# With hook managers:
pre-commit run --all-files    # pre-commit
prek run --all-files          # prek
lefthook run pre-commit       # lefthook

Code Quality Commands

# Rust formatting
cargo fmt                              # Format code
cargo fmt --check                      # Check formatting

# Rust linting
cargo clippy --workspace --all-targets --all-features -- -D warnings

# JavaScript/TypeScript (Biome)
cd desktop
npx @biomejs/biome check --write       # Format and fix issues
npx @biomejs/biome check --write false # Check only
npx @biomejs/biome lint                # Lint only
npx @biomejs/biome format              # Format only

Secret Detection

# Scan for secrets (if detect-secrets is available)
detect-secrets scan --baseline .secrets.baseline

# Update baseline with new findings
detect-secrets scan --baseline .secrets.baseline --update

Conventional Commits

We enforce Conventional Commits format:

Format

<type>(<scope>): <description>

<body>

<footer>

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding or updating tests
  • chore: Maintenance tasks
  • build: Build system changes
  • ci: CI/CD changes
  • revert: Reverting previous commits

Examples

feat: add user authentication system
fix(api): resolve memory leak in request handler
docs(readme): update installation instructions
chore(deps): bump tokio from 1.34.0 to 1.35.0
feat!: remove deprecated API endpoint (breaking change)

Breaking Changes

For breaking changes, use:

  • feat!: or fix!: (with exclamation mark)
  • Or include BREAKING CHANGE: in commit body

Biome Configuration

Biome is configured in desktop/biome.json with:

  • Linting: TypeScript, JavaScript, and JSON files
  • Formatting: Consistent code style
  • Import sorting: Automatic import organization
  • Performance: ~10x faster than ESLint + Prettier

Biome Commands

cd desktop

# Check and fix all issues
npx @biomejs/biome check --write

# Check without fixing
npx @biomejs/biome check

# Format only
npx @biomejs/biome format --write

# Lint only
npx @biomejs/biome lint

IDE Integration

VS Code

Install these extensions for the best experience:

  • rust-analyzer: Rust language support
  • Biome: JavaScript/TypeScript formatting and linting
  • Conventional Commits: Commit message assistance

Other IDEs

  • Most editors support Rust via rust-analyzer
  • Biome has plugins for major editors
  • Git hooks work regardless of editor

Bypassing Hooks (Emergency Only)

Sometimes you need to bypass hooks for emergency commits:

# Skip all hooks
git commit --no-verify -m "emergency fix"

# Skip specific hook manager checks but keep native checks
SKIP=cargo-clippy git commit -m "skip clippy only"

Note: Use sparingly and fix issues in follow-up commits.

Troubleshooting

Common Issues

Hooks not running

# Check if hooks are installed
ls -la .git/hooks/

# Reinstall hooks
./scripts/install-hooks.sh

Biome not found

cd desktop
npm install --save-dev @biomejs/biome
# or
yarn add --dev @biomejs/biome

Rust tools not available

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Add required components
rustup component add rustfmt clippy

Permission denied on hooks

chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/commit-msg

Secrets detection false positives

# Update baseline to ignore false positives
detect-secrets scan --baseline .secrets.baseline --update .secrets.baseline

# Or edit .secrets.baseline manually

Getting Help

  1. Check hook manager documentation:

  2. Run hooks manually to see detailed error messages

  3. Check our development chat for community support

Contributing

When contributing to Terraphim AI:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/your-feature
  3. Install development tools: ./scripts/install-hooks.sh
  4. Make your changes: Code, test, commit with conventional format
  5. Push and create PR: Automated checks will run

Your commits will be automatically validated for:

  • Code formatting and style
  • Security vulnerabilities
  • Conventional commit format
  • Breaking changes detection

This ensures consistent code quality across all contributions!

Desktop App CI/CD Domain