<div align="center">

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

### Claude Code is powerful. Tribunal makes it reliable.

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

[Website](https://thebotclub.ai) · [License](LICENSE)

<br>

<p align="center">
  <img src="demo.gif" alt="Tribunal Demo" width="800">
</p>

<br>

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

Or via the universal installer:

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

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

</div>

---


## 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

| 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)

```bash
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:

```bash
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](https://github.com/thebotclub/tribunal/releases)):

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

<details>
<summary><b>What the installer does</b></summary>

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

1. **Prerequisites** — Checks Homebrew, Node.js, Python 3.10+, 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)

</details>

### First Run

```bash
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](docs/EXAMPLES.md) for walkthroughs of common workflows.

### Team Vault (optional)

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

```bash
> /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.

```bash
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:

```bash
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)
```

<details>
<summary><b>Plan Phase</b></summary>

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

</details>

<details>
<summary><b>Implement Phase</b></summary>

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

</details>

<details>
<summary><b>Verify Phase</b></summary>

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

</details>

### 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](docs/FEATURES.md#quality-enforcement-hooks).

---

## 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](docs/ARCHITECTURE.md)**
→ Full tables, rule lists, and CLI reference: **[docs/FEATURES.md](docs/FEATURES.md)**

---

## CLI Reference

```bash
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](docs/FEATURES.md#cli-reference).

---

## 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](docs/SECURITY.md).

---

## Acknowledgments

Tribunal builds on the foundation laid by two projects:

- **[Claude Pilot](https://github.com/maxritter/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](https://summonaikit.com/)** — 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](https://github.com/anthropics/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](LICENSE) file for full terms.

---

<div align="center">

**Claude Code is powerful. Tribunal makes it reliable.**

</div>

---

## Enterprise Installation

### Docker

```bash
# 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:
```bash
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](https://github.com/thebotclub/tribunal/releases/latest):

```bash
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

```bash
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:

```bash
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](docs/ENTERPRISE_INSTALL.md) for full air-gapped installation instructions.
