AI-CLI Setup & Configuration

Prerequisites

Before setting up AI-CLI integration, ensure you have:

• Trix CLI installed - Installation guide
• Trix API key configured - Authentication guide
• AI CLI installed - Either Claude Code CLI or Gemini CLI

Automatic Setup

The easiest way to get started is with automatic detection and setup:

# Auto-detect and setup both Claude Code and Gemini CLI
trix integrations ai-cli setup

# Setup will:
# 1. Detect installed AI CLIs (Claude Code, Gemini CLI)
# 2. Configure session capture hooks
# 3. Configure context injection hooks
# 4. Test the integration

This command will:

1. Detect installed AI CLIs (Claude Code, Gemini CLI)
2. Locate their configuration files
3. Install session capture hooks (SessionEnd/session_end)
4. Install context injection hooks (SessionStart/session_start)
5. Verify the integration is working

Provider-Specific Setup

Claude Code CLI

To set up only for Claude Code CLI:

# Setup Claude Code CLI specifically
trix integrations ai-cli setup --provider claude-code

# Or use shorthand flag
trix integrations ai-cli setup --claude

Claude Code hooks are configured in ~/.config/claude/config.json (global) or .claude/config.json (project-level).

Gemini CLI

To set up only for Gemini CLI:

# Setup Gemini CLI specifically
trix integrations ai-cli setup --provider gemini-cli

# Or use shorthand flag
trix integrations ai-cli setup --gemini

Gemini hooks are configured in ~/.gemini/config.yaml (global) or .gemini/config.yaml (project-level).

Configuration Options

Global vs. Project-Level

By default, hooks are installed globally (affecting all sessions). For project-specific configurations:

# Setup for global configuration (default)
trix integrations ai-cli setup --global

# Setup for project-level configuration
trix integrations ai-cli setup --global=false

Force Reinstall

To overwrite existing Trix hooks (useful after updates):

# Force reinstall (overwrites existing hooks)
trix integrations ai-cli setup --force

Verification

After setup, verify the integration is configured correctly:

# Check integration status for all providers
trix integrations ai-cli status

# Check status for specific provider
trix integrations ai-cli status --provider claude-code

The status command shows:

• Which AI CLIs are detected
• Hook installation status for each provider
• Configuration file locations
• Recent session captures (if any)

Hook Configuration Details

Claude Code CLI Hooks

The setup command adds the following to your Claude Code configuration:

{
  "hooks": {
    "SessionStart": {
      "command": "trix",
      "args": ["inject-context-hook", "--max-tokens", "2000", "--max-memories", "5"],
      "timeout": 3000
    },
    "SessionEnd": {
      "command": "trix",
      "args": ["capture-session-hook", "--async"],
      "timeout": 3000
    }
  }
}

Gemini CLI Hooks

For Gemini CLI, hooks are configured in YAML format:

hooks:
  session_start:
    command: trix
    args:
      - inject-context-hook
      - --max-tokens
      - "2000"
      - --max-memories
      - "5"
    timeout: 3000
  session_end:
    command: trix
    args:
      - capture-session-hook
      - --async
    timeout: 3000

Hook Parameters Explained

Environment Variables

You can customize integration behavior with environment variables:

# Environment variables for AI-CLI integration
export TRIX_API_KEY="your_api_key"
export TRIX_DEFAULT_SPACE="my_project"

# Optional: customize defaults
export TRIX_AI_CLI_TOKEN_BUDGET=4000
export TRIX_AI_CLI_MAX_MEMORIES=10

Manual Setup (Advanced)

For advanced users who want complete control, you can manually edit hook configurations:

1. Locate configuration file:
   • Claude Code: ~/.config/claude/config.json
   • Gemini CLI: ~/.gemini/config.yaml
2. Add hooks section using the examples above
3. Customize parameters to your needs
4. Test by running a session and checking trix recall

Uninstallation

To remove Trix hooks from your AI CLI configuration:

# Remove all AI-CLI hooks
trix integrations ai-cli remove

# Remove for specific provider
trix integrations ai-cli remove --provider claude-code

This removes:

• SessionStart/SessionEnd hooks (Claude Code)
• session_start/session_end hooks (Gemini CLI)
• Empty hook sections if no other hooks remain

Troubleshooting

Hooks not triggering

• Verify hooks are installed: trix integrations ai-cli status
• Check AI CLI configuration file has correct syntax (JSON/YAML)
• Ensure trix command is in your PATH
• Test manually: trix inject-context-hook

Setup command fails

• Ensure Trix CLI is installed: trix --version
• Check you have write permissions to config directories
• Verify AI CLI is installed: which claude or which gemini
• Try with --verbose flag for detailed output

Sessions not being stored

• Check importance score with --verbose flag
• Lower threshold: Sessions must score ≥ 6.0 to auto-store
• Verify API key: trix auth status
• Check logs: ~/.trix/logs/ai-cli.log

Next Steps

• Commands Reference - Learn about process-session, inject-context, and hook commands
• Advanced Usage - Customize thresholds, troubleshoot issues, and optimize performance
• CLI Reference - Explore other Trix CLI commands