gjalla 0.3.4

Gjalla CLI — architecture guardrails for AI coding agents

Gjalla Pre-commit CLI

Pre-commit analysis CLI for validating changes against team rules.

Installation

pip install -e .

Commands

Command	Description
init	Initialize gjalla in a repository
commit	Analyze staged changes before commit
bypass	Bypass analysis for a commit
status	Show current status
hook	Manage git hooks (install/uninstall)
caps	Show available capabilities
sync	Sync configuration
auth	Authentication management
impact	Show impact analysis
mcp	MCP server mode

---

User Guide

Initial Setup

1. Configure API key:

   gjalla init
   

   • Prompts for API key (or set GJALLA_API_KEY env var)
   • Discovers available projects from API
   • Links current repository to a project

2. Install pre-commit hook (optional):

   gjalla hook install
   

Daily Usage

Automatic (via pre-commit hook):

• Hook runs gjalla commit automatically on each git commit
• Blocks commit if violations are found

Manual:

git add <files>
gjalla commit
git commit -m "message"

Analysis Flow

When gjalla commit runs:

1. Opens WebSocket connection to analysis service
2. Sends staged changes for analysis
3. Executes tool calls from the service (file reads, searches)
4. Displays results: violations, warnings, suggestions
5. Stores analysis receipt on successful analysis

Reading Output

• Violations (red): Must fix before commit proceeds
• Warnings (yellow): Should review, won't block commit
• Suggestions (blue): Optional improvements
• Receipt: Analysis ID stored for audit trail

Bypassing Analysis

When you need to skip analysis:

gjalla bypass -m "reason for bypass"
git commit -m "message"

Logs bypass with timestamp and reason.

Checking Status

gjalla status

Shows: project linkage, hook status, last analysis receipt.

Hook Management

gjalla hook install    # Install pre-commit hook
gjalla hook uninstall  # Remove pre-commit hook
gjalla hook status     # Check hook installation

Configuration

Global config: ~/.gjalla/config.yaml

api_key: "your-api-key"
api_url: "https://api.gjalla.io"
projects:
  /path/to/repo: "project-id"

Project config: .gjalla.yaml (in repo root)

• Project-specific rules and settings

Environment variables:

• GJALLA_API_KEY - Overrides config file api_key
• GJALLA_API_URL - Overrides config file api_url

---

Development Guide

Setup

git clone <repo-url>
cd gjalla-precommit
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pre-commit install  # Install hooks after cloning

Running Tests

python3 -m pytest tests/ -v

Project Structure

gjalla_precommit/
  cli.py              # Entry point, command group
  commands/           # CLI command implementations
    init.py           # gjalla init
    commit.py         # gjalla commit
    bypass.py         # gjalla bypass
    status.py         # gjalla status
    hook.py           # gjalla hook install/uninstall
    caps.py           # gjalla caps
    sync.py           # gjalla sync
    auth.py           # gjalla auth
    impact.py         # gjalla impact
    mcp.py            # gjalla mcp
  config/             # Configuration management
    settings.py       # Settings loading, config paths
  protocol/           # WebSocket protocol handling
  display/            # Terminal output formatting (rich)
  tools/              # Tool implementations for analysis
tests/                # Test suite

Dependencies

• click - CLI framework
• rich - Terminal formatting
• websockets - WebSocket client
• gitpython - Git operations
• pyyaml - Config file parsing
• pydantic - Settings validation
• httpx - HTTP client
• pathspec - Gitignore-style pattern matching

Dev Dependencies

• pytest - Test runner
• pytest-asyncio - Async test support