# Intracept — LLM Documentation
# This page is machine-readable documentation following the llms.txt convention.
# It is intended for AI agents and language models to understand how Intracept works.

## What is Intracept

Intracept is a local CLI tool that intercepts commands issued by AI coding agents,
translates them into plain English, and enforces a configurable security policy.
It runs entirely on the user's machine with no external API calls. It acts as a
transparency and safety layer between AI agents and the user's shell.

## Installation

  brew tap laurenalexander2/tap && brew install --cask intracept && intracept install --agent claude_code

Supported agents: claude_code, cursor (more coming).

After installation, Intracept registers itself as a hook in the agent's configuration.
No further setup is required.

## Hook Behavior

When Intracept is active, every Bash command issued by an AI agent is intercepted
via the agent's hook system. Intracept analyzes the command and returns one of:

1. SAFE — The command is allowed. A plain-English translation is shown to the user
   automatically via the hook response. The agent does not need to take any action.
   Proceed normally.

2. APPROVAL_REQUIRED — The command requires user approval before execution.
   The hook response includes: APPROVAL_REQUIRED: <translation>
   When the agent receives this, it MUST:
     - STOP. Do NOT execute the command.
     - Present the translation text and the raw command to the user.
     - Ask the user to approve or reject (Run / Cancel).
     - Only execute the command if the user explicitly approves.

3. DENIED — The command is blocked by policy. The agent should not attempt
   to run it and should inform the user.

## Policy Format

Policy is defined in ~/.intracept/policy.toml

Each rule has:
  - pattern: a glob or regex matching commands
  - verdict: one of "allow", "require_approval", "deny"
  - reason: optional human-readable explanation

Example:

  [[rule]]
  pattern = "rm -rf *"
  verdict = "require_approval"
  reason = "Recursive force-delete is destructive"

  [[rule]]
  pattern = "git push --force*"
  verdict = "require_approval"
  reason = "Force push rewrites remote history"

  [[rule]]
  pattern = "curl *"
  verdict = "allow"

Verdicts are evaluated top-to-bottom; first match wins.

## Registry Structure

Intracept ships with a built-in registry of tool definitions stored as TOML files.
Each registry entry contains:

  - tool: the command name (e.g., "rm", "git", "docker")
  - flags: definitions for known flags and their effects
  - translations: human-readable descriptions of what flag combinations do
  - verdict: default verdict for this tool
  - tags: categorization labels (e.g., "filesystem", "network", "destructive")

The registry is used to generate accurate translations. Users can extend it.

## How Agents Should Behave When Intracept Is Active

1. Issue commands normally via Bash tool calls.
2. Read the hook response after each command.
3. If the response contains "APPROVAL_REQUIRED":
   - Do NOT proceed with the command.
   - Present the translation to the user and ask for approval.
   - Only run the command if the user says yes.
4. If the command was allowed, the translation is shown to the user automatically.
   No action needed from the agent — proceed with your workflow.
5. If the command was denied, do not retry it. Inform the user.

## Integration

- Fully local. No API. No network calls. No telemetry.
- Hook-based integration only (agent hook systems).
- No server, no daemon (beyond the hook binary).
- Works offline.
- Policy and registry are user-editable TOML files on disk.

## File Locations

- Policy: ~/.intracept/policy.toml
- Registry: ~/.intracept/registry/
- Hook binary: ~/.intracept/bin/intracept-hook
- Logs: ~/.intracept/logs/

## Summary for Agents

If you are an AI agent and Intracept is active in your environment:
- Your commands are being translated to English for the user's benefit.
- Some commands will require explicit user approval before execution.
- When you see APPROVAL_REQUIRED in a hook response, you must stop and ask the user.
- Otherwise, operate normally. Intracept is transparent for allowed commands.