# macOS / Linux (recommended)
brew tap thebotclub/tribunal https://github.com/thebotclub/tribunal
brew install tribunal

curl -fsSL https://raw.githubusercontent.com/thebotclub/tribunal/main/install.sh | bash

Requirements

• Node.js (v18+) or Bun — required for the worker service hooks
• Python 3.10+ — required for hook scripts (the install.sh path uses uv to auto-provision Python if needed)
• uv — Python package runner used by hooks

Who is this for?

• Professional developers using Claude Code who want reliable, production-grade output
• Teams that need TDD enforcement, code review, and quality gates automated
• Anyone tired of context degradation on long coding sessions

Before & After

Why This Approach Works

Most AI coding frameworks add complexity — more agents, more scaffolding, more configuration — but the output quality doesn't scale with the machinery. Extra layers burn tokens, increase latency, and introduce new failure modes.

Tribunal optimizes for output quality, not system complexity. No learning curve, no project scaffolding, no state files to manage. Install it, run tribunal, and the quality guardrails are already active — hooks, TDD, type checking, formatting — enforced automatically on every edit.

The system stays fast because it stays focused. Quick mode is direct execution with zero overhead. /spec adds structured planning only when you need it. Both modes share the same quality hooks and hand off cleanly across sessions with Endless Mode.

Getting Started

Prerequisites

An active Claude subscription is required.

Install

Option 1 — Homebrew (macOS / Linux, recommended)

brew tap thebotclub/tribunal https://github.com/thebotclub/tribunal
brew install tribunal

Then cd into your project folder and run tribunal.

Option 2 — Universal installer (macOS, Linux, WSL2)

cd into your project folder, then run:

curl -fsSL https://raw.githubusercontent.com/thebotclub/tribunal/main/install.sh | bash

Choose Local (Homebrew-based, macOS/Linux/WSL2) or Dev Container (isolated, any OS).

To install a specific version (see releases):

export VERSION=1.2.0
curl -fsSL https://raw.githubusercontent.com/thebotclub/tribunal/main/install.sh | bash

First Run

tribunal          # Launch Tribunal
> /sync             # Analyze your codebase, generate project-specific rules and skills

What to expect on first run:

When you type tribunal, the CLI loads your config, starts the MCP server workers, and launches Claude Code with Tribunal's hooks and rules active. You'll see the Tribunal banner, then Claude is ready to chat.

First thing to do: run /sync

This analyzes your project and gets Tribunal ready for your stack:

> /sync
🔍 Analyzing codebase: my-project/
   - Languages: Python, TypeScript
   - Frameworks: FastAPI, React
📦 Building semantic search index...
   - Indexed: 342 files
📝 Generating project-specific rules...
   - Rule: python-type-hints (activated for .py files)
   - Rule: react-best-practices (activated for .tsx files)
✓ Ready to work

Run /sync once after install, then again when your dependencies or architecture change.

→ See docs/EXAMPLES.md for walkthroughs of common workflows.

Team Vault (optional)

Share rules, commands, and skills across your team via a private Git repo:

> /vault            # Push/pull shared assets

Two Modes

Quick Mode — Direct execution

Just chat. No plan file, no approval gate. All quality hooks and TDD enforcement still apply.

tribunal
> Fix the null pointer bug in user.py

/spec — Spec-driven development

For complex features, refactoring, or anything you want to review before implementation:

tribunal
> /spec "Add user authentication with OAuth and JWT tokens"

Plan  →  Approve  →  Implement  →  Verify  →  Done
                         │            ↑        ↓
                         │            └─ Loop──┘
                         ▼
                      Task 1 (TDD)
                         ▼
                      Task 2 (TDD)
                         ▼
                      Task 3 (TDD)

Smart Model Routing

Tribunal automatically selects the right model for each phase — deeper reasoning where it matters, faster execution where it doesn't:

Quality Enforcement

Hooks fire automatically at every stage of development — no manual invocation required:

• File checker — Scans for secrets, runs language-specific linters (Python/TS/Go), auto-fixes formatting on every save
• TDD enforcer — Blocks implementation edits without a prior failing test; uses a dependency graph to suggest the right test file
• Context monitor — Warns at 80% context usage, forces Endless Mode handoff at 90%
• Spec stop guard — Prevents Claude from calling it done while a spec is still in progress
• Tool redirect — Routes web/search calls to MCP alternatives; enforces sub-agent spawn limit (5/session)

4 verification sub-agents (plan-verifier, plan-challenger, spec-reviewer-compliance, spec-reviewer-quality) run automatically during /spec to catch gaps, challenge assumptions, and review code quality independently.

Endless Mode: Monitors context usage in real-time. Saves session state to ~/.tribunal/sessions/ so the next session picks up exactly where you left off. Avoids starting new /spec phases when context is high — hands off cleanly instead.

For the full hooks reference, see docs/FEATURES.md.

What's Included

• 4 slash commands: /spec, /sync, /learn, /vault
• 22 built-in rules across quality enforcement, context & memory, language standards, tool integration, and development workflow
• 13 conditional coding standards — activated by file type, not loaded globally (zero context waste)
• 5 MCP servers pre-configured: Context7, mem-search, web-search, grep-mcp, web-fetch
• 3 language servers (LSP) auto-installed: basedpyright (Python), vtsls (TypeScript), gopls (Go)

→ How it works: docs/ARCHITECTURE.md → Full tables, rule lists, and CLI reference: docs/FEATURES.md

CLI Reference

tribunal          # Launch Tribunal (alias: sfc)
tribunal status   # Show access and session status
tribunal activate <key>  # Activate on this machine

All commands support --json for structured output. For the full command reference (skills, worktrees, context, Endless Mode), see docs/FEATURES.md.

Tribunal Console

Access the web-based console at http://localhost:41777 for a real-time view of persistent memory, session tracking, and observation history across sessions.

Privacy

Your code never leaves your machine through Tribunal. All development tools — vector search (Vexor), persistent memory (Tribunal Console), session state, hooks — run entirely locally. No code, filenames, or project content is transmitted.

The only external calls are for access verification and Claude Code's own communication with Anthropic's API using your subscription.

For the full data flow diagram, auth token storage details, and responsible disclosure contact, see docs/SECURITY.md.

Acknowledgments

Tribunal builds on the foundation laid by two projects:

• Claude Pilot by Max Ritter — the open-source project that pioneered the spec-driven development workflow, TDD enforcement hooks, Endless Mode, and the quality automation architecture that Tribunal inherits and extends. Tribunal started as a fork of Claude Pilot and has since evolved with its own features, but the core ideas — /spec, /sync, worktree isolation, verification sub-agents, persistent memory — originated there.

• SummonAI Kit — a toolkit for enhancing AI coding agents with codebase-aware skills and subagents. SummonAI Kit's approach to analyzing codebases and generating tailored configurations helped shape early ideas behind Tribunal's conditional coding standards and skill system.

Both projects sit on top of Claude Code by Anthropic — the agentic coding tool whose hooks, commands, and plugin architecture make everything possible.

License

Tribunal is open-source software licensed under the MIT License. See the LICENSE file for full terms.

CI/CD Integration

Tribunal ships as a first-class GitHub Action — add quality gates to any repo in one line.

Quick Start

# .github/workflows/tribunal.yml
- uses: thebotclub/tribunal@main

That's it. Tribunal installs itself, scans changed files, and fails the job if quality gates block.

GitHub Action Reference

Action: thebotclub/tribunal@main

Inputs

Outputs

SARIF / GitHub Code Scanning

Tribunal outputs SARIF 2.1.0 compatible with GitHub Code Scanning. Results appear inline on pull requests and in the Security → Code Scanning tab.

- name: Run Tribunal
  id: tribunal
  uses: thebotclub/tribunal@main
  with:
    sarif-output: tribunal-results.sarif

- name: Upload to Code Scanning
  uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: ${{ steps.tribunal.outputs.report-path }}

SARIF rule IDs:

Example Workflows

Ready-to-use workflow files are in .github/examples/:

tribunal ci CLI

Run the same checks locally or in any CI environment without installing the full Tribunal suite:

pip install tribunal
tribunal ci                             # scan git-changed files
tribunal ci --sarif results.sarif       # write SARIF output
tribunal ci --json                      # machine-readable JSON
tribunal ci --coverage-threshold 80     # fail if coverage < 80%
tribunal ci src/app.py src/utils.py     # explicit file list

Exit codes: 0 = all pass · 1 = one or more failures · 2 = warnings only

GitLab CI

tribunal:
  image: python:3.12-slim
  script:
    - pip install tribunal
    - tribunal ci --sarif tribunal-results.sarif
  artifacts:
    reports:
      sast: tribunal-results.sarif

Jenkins

stage('Quality Gates') {
    steps {
        sh 'pip install tribunal'
        sh 'tribunal ci --json > tribunal-report.json'
    }
    post {
        always {
            archiveArtifacts artifacts: 'tribunal-report.json'
        }
    }
}

Badge

Add a Tribunal CI badge to your README by copying the shields.io snippet:

[![Tribunal CI](https://img.shields.io/badge/Tribunal%20CI-passing-brightgreen?logo=github)](https://github.com/YOUR_ORG/YOUR_REPO/actions)

Replace YOUR_ORG/YOUR_REPO with your GitHub repository path. Once you have a live Actions workflow, you can also use a live workflow status badge:

![Tribunal CI](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/tribunal.yml/badge.svg)

Enterprise Installation

Docker

# Pull and run the latest release
docker pull ghcr.io/thebotclub/tribunal:latest

# Run with your project mounted
docker run -it --rm \
  -v ~/.claude:/root/.claude \
  -v ~/.tribunal:/root/.tribunal \
  -v $(pwd):/workspace \
  -w /workspace \
  ghcr.io/thebotclub/tribunal

Or build locally:

docker build -t tribunal .
docker run -it --rm -v $(pwd):/workspace -w /workspace tribunal

.deb Package (Ubuntu/Debian)

Download the .deb from the latest release:

wget https://github.com/thebotclub/tribunal/releases/latest/download/tribunal-tribunal_<version>_amd64.deb
sudo dpkg -i tribunal-tribunal_<version>_amd64.deb
tribunal --help

Self-contained Tarball

wget https://github.com/thebotclub/tribunal/releases/latest/download/tribunal-<version>-linux-x86_64.tar.gz
tar xzf tribunal-*.tar.gz
cd tribunal-*/
./tribunal --help

Air-gapped Deployment

For environments without internet access, use the bundle command:

tribunal bundle --output tribunal-bundle.tar.gz
# Transfer bundle to air-gapped machine, then:
tar xzf tribunal-bundle.tar.gz
cd tribunal-bundle/
bash offline-install.sh

See docs/ENTERPRISE_INSTALL.md for full air-gapped installation instructions.