Tirith
A pre-execution security layer that checks suspicious URLs, pipe-to-shell commands, terminal injection, data exfiltration, and malicious agent configuration through shell hooks, host hooks, or an MCP gateway.
Project overview
Tirith is a terminal security CLI with integrations for AI coding agents. It analyzes command structure and configuration before execution, then connects to supported hosts through shell hooks, native agent hooks, or an MCP gateway. The repository is unusually explicit about enforcement boundaries: adding an MCP server does not by itself force an agent to consult it, and an ordinary shell hook is not a general runtime sandbox.
Core capabilities
Pre-execution command and URL analysis
The stable check command reports allow, block, warn, or acknowledgement-required outcomes for command structures and URLs, including homographs, unsafe pipelines, deceptive Unicode, and selected supply-chain patterns.
Agent hooks and MCP gateway
Documented setup targets connect Tirith to multiple coding agents. The gateway can enforce policy only for calls routed through it, while host hooks cover host-specific execution paths when they are loaded and effective.
Configuration and directory scanning
The scan surface inspects files, repositories, agent configurations, and CI material for hidden content, configuration poisoning, workflow hazards, and related evidence. The compatibility matrix currently marks scan as Experimental.
Policy, trust, and audit controls
User, project, and organization policy layers can tune actions; repository policy can tighten but not weaken a trusted baseline. Trust entries are narrow and expiring by default, and local audit records redact full commands.
Signed threat data and offline operation
Tirith can refresh a signed threat database and use optional online enrichment. Offline mode disables check-path HTTP and DNS producers rather than silently turning an unavailable lookup into a clean result.
Installation and usage
Install Tirith from a documented package channel, run the health check, preview host changes, then configure and verify each execution path you expect it to protect.
Let an AI Agent install it
Send this prompt to Codex, Claude Code, or another AI agent that can work with your local environment.
Help me install and configure Tirith for OpenAI Codex.
Project: https://github.com/sheeki03/tirith
Read the README, mcp/clients/codex.md, SECURITY.md, and both license files first. Confirm the platform, current shell, installation owner, Codex configuration path, and whether I want the optional ~/.zshenv guard. Preview changes with tirith setup codex --dry-run before writing anything. Keep existing configuration, credentials, and private paths out of logs. After installation, run tirith doctor, verify tirith-gateway registration, and follow the documented upgrade smoke test. Explain which execution paths are protected and which are not. Ask before overwriting configuration or enabling networked enrichment.- A supported macOS, Linux, or Windows installation path from the repository
- Homebrew for the example installation
- Tirith and Codex CLI available on PATH for the Codex integration
- Permission to update user-level Codex configuration and, if selected, ~/.zshenv
brew install tirith- 1Review the trust and license boundaries
Read the security policy, threat model, compatibility matrix, and AGPL/commercial terms. Decide whether local audit logging and optional network enrichment fit the environment.
- 2Install the CLI and check health
On a Homebrew-managed machine, run brew install tirith, then run tirith doctor. Use the same package manager for future upgrades.
- 3Preview Codex configuration changes
Run tirith setup codex --dry-run. Review the user-level MCP registration, gateway file, and the optional ~/.zshenv modification before applying them.
- 4Configure both Codex execution paths
Run tirith setup codex --install-zshenv when you need MCP gateway coverage plus the documented non-interactive zsh guard for native Codex shell execution.
- 5Verify after setup and upgrades
Confirm registration with codex mcp get tirith-gateway, run the repository's upgrade smoke script where available, and use the documented direct-shell test in a disposable context.
Run tirith doctor, confirm the gateway with codex mcp get tirith-gateway, and perform the repository's direct-shell blocked-command check in a disposable shell. Do not assume that the presence of a configuration file proves the host loaded it.
- MCP-only registration does not cover Codex native shell execution
- Restart protected shells and agent hosts after upgrades so they load the new binary and regenerated hooks
- Use --offline or TIRITH_OFFLINE=1 when runtime enrichment must make no network request
- Review AGPL obligations or obtain a commercial license before organizational deployment
Use cases
Guard AI-generated shell commands
Add a pre-execution decision point for coding-agent commands that may contain deceptive URLs, unsafe pipelines, hidden controls, or sensitive-data sinks.
Govern routed MCP execution
Place a policy gateway in front of an upstream MCP server so guarded tool calls and bounded output pass through a documented enforcement boundary.
Scan repositories before agent use
Inspect agent instructions, skills, MCP configuration, CI workflows, and other files for configuration poisoning or hidden-content indicators before trusting a repository.
Operate with explicit offline constraints
Use the documented offline mode when local analysis is required and network enrichment must be suppressed, while preserving incomplete-verification signals.
Assessment
Tirith clears the catalog bar because the public repository contains a substantial Rust implementation, tests, detailed host guides, a security policy, a threat model, signed release artifacts, and unusually candid enforcement limitations. v0.4.1 was published one day before this review and the repository remains active. The trade-off is material: much of the broader surface is still Experimental, MCP registration alone is not enforcement, and AGPL obligations need deliberate review. No installation or functional test is claimed here.
Why it may be useful
- Explicit separation between detection, enforcement, containment, and attestation
- Documented setup and verification paths for many coding agents
- Clear offline behavior, audit logging, security reporting, and signed releases
- Real source, tests, packaging, CI, and host-specific integration files
What to know first
- Automatic protection depends on effective host hooks, shell gates, or gateway routing
- Several hosts may fail open when hooks crash or time out
- General enforcing containment is limited to x86_64 Linux
- Most advanced commands remain Experimental or Preview
- AGPL-3.0-only may not fit every deployment without a commercial agreement
README
Tirith
Overview
A pre-execution security layer that checks suspicious URLs, pipe-to-shell commands, terminal injection, data exfiltration, and malicious agent configuration through shell hooks, host hooks, or an MCP gateway. Terminal security for developers and AI agents. Intercepts homograph URLs, pipe-to-shell, ANSI injection, obfuscated payloads, data exfiltration, and malicious AI skills/configs before they execute.
Getting started
- Install Tirith from a documented package channel, run the health check, preview host changes, then configure and verify each execution path you expect it to protect.
- Tirith analyzes commands, URLs, pasted text, files, directories, and selected agent or MCP configuration for deceptive Unicode, pipe-to-shell patterns, prompt injection, suspicious execution shapes, data exfiltration, and supply-chain indicators.
- Its integration model has distinct boundaries. Shell and host hooks can run checks before execution, while the MCP gateway can inspect routed requests and sanitize bounded output. Plain MCP registration remains cooperative and cannot prove automatic enforcement.
- Run tirith doctor, confirm the gateway with codex mcp get tirith-gateway, and perform the repository's direct-shell blocked-command check in a disposable shell. Do not assume that the presence of a configuration file proves the host loaded it.
Configuration
brew install tirith