tribunal 1.2.3

Tribunal — Enterprise-grade Claude Code enhancement layer. TDD enforcement, quality gates, and a shared vault of rules, agents, and hooks.

   _____ __   _ _________      __    __   ______          __
  / ___// /__(_) / / __(_)__  / /___/ /  / ____/___  ____/ /__
  \__ \/ //_/ / / / /_/ / _ \/ / __  /  / /   / __ \/ __  / _ \
 ___/ / ,< / / / / __/ /  __/ / /_/ /  / /___/ /_/ / /_/ /  __/
/____/_/|_/_/_/_/_/ /_/\___/_/\__,_/   \____/\____/\__,_/\___/

Claude Code is powerful. Tribunal makes it reliable.

Start a task, grab a coffee, come back to production-grade code.
Tests enforced. Context preserved. Quality automated.

Website · License

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

Or via the universal installer:

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

Works on macOS, Linux, and Windows (WSL2).

---

Requirements

• Node.js (v18+) or Bun — required for the worker service hooks
• Python 3.12 — required for hook scripts
• 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

Without Tribunal	With Tribunal
Writes code, skips tests	TDD enforced — RED, GREEN, REFACTOR on every change
No quality gates	Hooks auto-lint, format, and type-check on every file edit
Context degrades mid-task	Endless Mode preserves state across automatic session handoffs
Every session starts cold	Persistent memory carries knowledge between sessions
Hope it works	4 verification sub-agents perform independent code review
No codebase understanding	Production-tested rules loaded into every session
One-size-fits-all advice	Coding standards activated conditionally by file type
Changes mixed into branch	Isolated worktrees — review and squash merge when verified
Manual tool wiring	5 MCP servers + 3 language servers pre-configured
Requires constant oversight	Start a task, walk away, come back to verified results

---

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 koshaji/tribunal https://github.com/koshaji/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/koshaji/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/koshaji/tribunal/main/install.sh | bash

What the installer does

8-step installer with progress tracking, rollback on failure, and idempotent re-runs:

1. Prerequisites — Checks Homebrew, Node.js, Python 3.12+, uv, git
2. Dependencies — Installs Vexor, playwright-cli, mcp-cli, Claude Code
3. Shell integration — Auto-configures bash, fish, zsh with tribunal alias
4. Config & Claude files — Sets up .claude/ plugin, rules, commands, hooks, MCP servers
5. VS Code extensions — Installs recommended extensions for your stack
6. Dev Container — Auto-setup with all tools pre-configured
7. Automated updater — Checks for updates on launch with release notes and one-key upgrade
8. Cross-platform — macOS, Linux, Windows (WSL2)

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)

Plan Phase

1. Explores codebase with semantic search (Vexor)
2. Asks clarifying questions before committing to a design
3. Writes spec to docs/plans/ with scope, tasks, and definition of done
4. plan-verifier + plan-challenger sub-agents independently validate the plan
5. Auto-fixes issues found by verifiers
6. Waits for your approval — you can edit the plan first

Implement Phase

1. Creates an isolated git worktree on a dedicated branch (optional — main branch stays clean)
2. Implements each task with strict TDD (RED → GREEN → REFACTOR)
3. Quality hooks auto-lint, format, and type-check every file edit
4. Runs full test suite after each task to catch regressions

Verify Phase

1. Runs full test suite — unit, integration, and E2E
2. Type checking and linting across the entire project
3. Executes actual program to verify real-world behavior
4. spec-reviewer-compliance + spec-reviewer-quality sub-agents perform independent code review
5. Auto-fixes all findings, then re-verifies until clean
6. Loops back to implementation if structural issues remain
7. On success, shows diff summary and offers to squash merge worktree back to main

Smart Model Routing

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

Phase	Model	Why
Planning	Opus	Deep reasoning for architecture and spec design
Plan Verification	Opus	Catching gaps and requirement mismatches before implementation
Implementation	Sonnet	Fast, cost-effective code generation guided by a clear spec
Code Verification	Opus	Independent review requires the same reasoning depth as planning

---

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 proprietary software owned by Tribunal Pty Ltd. See the LICENSE file for full terms.

---

Claude Code is powerful. Tribunal makes it reliable.

---

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.