AI-CLI Commands Reference

Command Overview

The AI-CLI integration provides commands for both manual and automated memory management. Commands fall into three categories:

Integration Management

setup

Auto-detect and configure AI CLI hooks.

# 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

Options:

• --provider <name> - Specify provider: claude-code or gemini-cli
• --claude - Shorthand for --provider claude-code
• --gemini - Shorthand for --provider gemini-cli
• --global - Install globally (default: true)
• --force - Force reinstall, overwriting existing hooks

status

Check integration configuration and hook installation status.

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

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

Options:

• --provider <name> - Check specific provider
• --claude - Check Claude Code CLI only
• --gemini - Check Gemini CLI only

remove

Remove Trix hooks from 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

Options:

• --provider <name> - Remove from specific provider
• --claude - Remove from Claude Code CLI only
• --gemini - Remove from Gemini CLI only

process-session

Process an AI CLI session transcript, analyze its importance, and optionally store it as a memory.

Basic Usage

# Process a session transcript
trix process-session --file session.jsonl

# Auto-stores if importance >= 6.0
# Output shows:
# - Importance score
# - Key topics extracted
# - Whether it was stored

The command analyzes the session and outputs an importance score (0-10). Sessions with scores ≥ 6.0 are automatically stored by default.

Options

Required:

• --file <path> - Path to session transcript (JSONL format)

Optional:

• --session-id <id> - Explicit session identifier
• --space <name> - Store in specific space (default: default space)
• --auto-store - Enable auto-storage for important sessions (default: true)
• --verbose - Show detailed scoring breakdown and reasoning

Examples

With Session ID

# Process with explicit session ID
trix process-session --session-id "chat_123" --file session.jsonl

With Space

# Process and store in specific space
trix process-session --file session.jsonl --space "project_alpha"

Verbose Output

# Process with verbose output
trix process-session --file session.jsonl --verbose

# Shows:
# - Full transcript analysis
# - Importance calculation details
# - Extracted entities and topics
# - Storage decision reasoning

Auto-Store Control

# Process with auto-store enabled (default)
trix process-session --file session.jsonl --auto-store

# Disable auto-store for scoring only
trix process-session --file session.jsonl --auto-store=false

Output Format

The command outputs JSON with:

{
  "importance_score": 7.5,
  "recommendation": "store",
  "components": {
    "novelty": 8,
    "technical_depth": 7,
    "actionable": 9,
    "completeness": 6
  },
  "topics": ["authentication", "JWT", "security"],
  "entities": ["Express.js", "bcrypt"],
  "stored": true,
  "memory_id": "mem_abc123xyz"
}

inject-context

Search your memory library and inject relevant context formatted for AI consumption.

Basic Usage

# Inject relevant context for a query
trix inject-context "How do I implement authentication?"

# Searches memories and returns:
# - Top 5 most relevant memories
# - Formatted for AI consumption
# - Within 2000 token budget

Options

Required:

• <query> - Search query (semantic search)

Optional:

• --space <name> - Search in specific space
• --max-tokens <n> - Maximum tokens for context (default: 2000)
• --max-memories <n> - Maximum number of memories (default: 5)
• --verbose - Show memory metadata and search details

Examples

Custom Token Budget

# Inject with custom token budget
trix inject-context "database schema design" --max-tokens 4000

# Returns more context within 4000 tokens

Limit Memories

# Limit number of memories
trix inject-context "API endpoints" --max-memories 10

# Returns up to 10 relevant memories

Space-Specific

# Inject from specific space
trix inject-context "bug fix" --space "project_alpha"

Verbose Output

# Inject with verbose output
trix inject-context "authentication" --verbose

# Shows:
# - Semantic search results
# - Memory metadata
# - Token usage details

Output Format

The command outputs formatted context ready for AI injection:

# Relevant Context from Memory

## Authentication implementation (similarity: 0.92)
User implemented JWT authentication using Express.js middleware...

## Security best practices (similarity: 0.87)
Always use bcrypt for password hashing, never store plaintext...

---
Retrieved 2 memories (estimated 487 tokens)

Hook Commands

These commands are called automatically by AI CLI hooks. You typically don't run them manually, but they can be useful for testing.

capture-session-hook

Called automatically after an AI CLI session ends. Reads transcript from stdin.

# Customize hook behavior with flags
# For capture session hook:
trix capture-session-hook --async --verbose

# For context injection hook:
trix inject-context-hook --max-tokens 4000 --max-memories 10

Stdin Input: JSON object with session metadata and transcript path

Default Behavior:

• Runs asynchronously in background (non-blocking)
• Auto-stores sessions with importance ≥ 6.0
• Errors are logged but don't crash the CLI

inject-context-hook

Called automatically at AI CLI session start. Reads session context from stdin.

Stdin Input: JSON object with working directory, git context, and query

Default Behavior:

• Detects git repository automatically
• Searches for relevant memories (semantic search)
• Returns formatted context to stdout
• Returns empty string on errors (graceful degradation)

Exit Codes

Error Handling

Common Errors

File not found

Error: Session transcript file not found: session.jsonl

Solution: Check the file path is correct and file exists

Invalid transcript format

Error: Failed to parse transcript: invalid JSON on line 12

Solution: Ensure transcript is valid JSONL (one JSON object per line)

API authentication failed

Error: Invalid API key or unauthorized access

Solution: Check your API key with trix auth status

Rate limit exceeded

Error: Rate limit exceeded. Please try again in 60 seconds

Solution: Wait and retry, or upgrade your plan for higher limits

Next Steps

• Advanced Usage - Customize configuration, troubleshoot issues, and optimize performance
• Setup & Configuration - Return to setup documentation
• CLI Reference - Explore other Trix CLI commands