Metadata-Version: 2.4
Name: cross-ai
Version: 0.5.0
Summary: Agent monitoring proxy and session manager — PTY wrapping, network interception, Slack relay, and gating
Project-URL: Homepage, https://github.com/rfdearborn/cross
Project-URL: Repository, https://github.com/rfdearborn/cross
Project-URL: Issues, https://github.com/rfdearborn/cross/issues
Author: Cross Attention Labs
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,gating,monitoring,oversight,proxy,safety
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: starlette>=0.52.0
Requires-Dist: uvicorn[standard]>=0.41.0
Requires-Dist: websockets>=13.0
Provides-Extra: dev
Requires-Dist: anyio[trio]>=4.0; extra == 'dev'
Requires-Dist: mitmproxy>=12.0.0; extra == 'dev'
Requires-Dist: pytest-anyio>=0.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: slack
Requires-Dist: aiohttp>=3.9.0; extra == 'slack'
Requires-Dist: slack-sdk>=3.0.0; extra == 'slack'
Description-Content-Type: text/markdown

# cross

**Configurable Runtime Oversight and Safety Standard**

cross makes AI agents more trustworthy *and* more capable with lightweight gating and monitoring.

> **Not sure you need this?** Ask your agent to explain why you do.

## Why cross

Your agents are overeager. They're so locked in on your task that they'll `rm -rf` an errant directory or push your credentials public without a second thought.

cross is a minimal-friction harness of deterministic and LLM checking layers to guard against errors and misalignment. It pairs agents with spotters which screen actions and monitor sessions with separate context and fresh eyes. It expands the capability-safety frontier and relieves the pit that's been growing in your stomach since you stopped reviewing tool calls.

**New:** cross supports gate and sentinel screening via Claude Code, and so adds no cost at the margin for Claude subscribers!

## Quick Start

```bash
pip install cross-ai               # or: pip install cross-ai[slack] for Slack integration
cross setup                        # interactive setup wizard (starts daemon automatically on macOS)
```

Or install from source:

```bash
git clone https://github.com/rfdearborn/cross && cd cross
pip install -e ".[dev]"
```

Then point your agent's API traffic through cross. For Claude Code, add a shell wrapper:

```bash
# In your .zshrc / .bashrc
claude() { cross wrap -- claude "$@"; }
```

`cross wrap` does two things: wraps the agent in a PTY for I/O control, and routes API traffic through the local proxy (`ANTHROPIC_BASE_URL=http://localhost:2767`) for structured monitoring and gating.

## How It Works

cross evaluates every tool call through a 3-layer pipeline:

```
Tool call arrives
       |
       v
 +-----------+     no match     +----------+
 |  Denylist  | --------------> |  ALLOW   |
 |   Gate     |                 +----------+
 +-----------+
       | match
       v
 +-----------+     false pos    +----------+
 |  LLM Gate  | --------------> |  ALLOW   |
 |  (review)  |                 +----------+
 +-----------+
       | confirmed
       v
  BLOCK / ESCALATE
  (feedback to agent / human review)

       --- meanwhile, in the background ---

 +-----------+
 | Sentinel  |  periodic review of all activity
 +-----------+
```

**Layer 1: Denylist gate** -- Fast deterministic pattern matching against YAML rules. Sub-millisecond, zero cost. Default rules cover destructive commands, dangerous git operations, credential exfiltration, reverse shells, system path writes, process termination, privilege escalation, mutating HTTP requests, container destruction, and more. Intentionally broad -- it's a triage filter, not a final judge.

**Layer 2: LLM gate** -- Only invoked when the denylist flags a call. Reviews the tool call with full context (user intent, recent tool history, why it was flagged) and renders a verdict: ALLOW (false positive), BLOCK (confirmed dangerous), or ESCALATE (needs human review). This is why the denylist can be aggressive without generating noise -- the LLM catches false positives.

**Layer 3: Sentinel** -- Async periodic reviewer that watches the full event stream over time. Detects patterns that per-call evaluation misses: tool calls that don't match user intent, suspicious sequences (read credentials then network call), escalating privilege patterns, and agents working around restrictions. Reports to the dashboard and Slack.

Blocked tool calls are suppressed from the API response stream. The proxy automatically retries with the block reason injected, so the agent self-corrects without user intervention. For critical threats (credential exfiltration, reverse shells), the session is halted entirely until a human intervenes.

## Supported Agents

- **Claude Code** -- validated, full PTY + proxy + tool-level gating
- **OpenClaw** -- validated, PTY + tool-level gating via `beforeToolCall` hook. `cross wrap -- openclaw` automatically injects a Node.js hook that gates every tool call through the cross daemon
- **Any CLI agent** -- `cross wrap -- <agent-command>` provides PTY wrapping and API proxy for any CLI agent
- **Any agent using Anthropic APIs** -- set `ANTHROPIC_BASE_URL=http://localhost:2767`

## Daemon Management

```bash
cross start                    # start the daemon (backgrounds automatically)
cross stop                     # stop the running daemon
cross restart                  # stop + start (picks up code/config changes)
cross start --foreground       # run in foreground (for development/debugging)
```

`cross daemon` is an alias for `cross start`.

## Dashboard

cross ships with a built-in web dashboard at `http://localhost:2767`. No dependencies, no setup -- it's always active when the daemon is running.

The dashboard shows:
- **Pending approvals** -- escalated tool calls waiting for human review, with Approve/Deny buttons
- **Live event feed** -- real-time stream of tool calls, gate decisions, and sentinel reviews (persists across daemon restarts)

You can also manage pending escalations from the CLI:

```bash
cross pending                          # list pending escalations
cross pending approve <tool_use_id>    # approve
cross pending deny <tool_use_id>       # deny
```

## Notifications

cross delivers notifications through two layers:

- **Native desktop notifications** (macOS) -- via `terminal-notifier`. Clicking a notification opens the dashboard. Enabled during `cross setup` or by setting `CROSS_NATIVE_NOTIFICATIONS_ENABLED=true`. When the dashboard tab is open, browser notifications take priority to avoid opening duplicate tabs.
- **Browser notifications** -- fired from the dashboard tab when it's open. Click to focus the tab. Enable via the button in the dashboard header.
- **Slack** (optional) -- gate decisions, sentinel reviews, and interactive approval buttons. Configure with `CROSS_SLACK_BOT_TOKEN` and `CROSS_SLACK_APP_TOKEN`. Install the `slack` extra: `pip install cross-ai[slack]`.

## Configuration

### LLM Providers

cross uses LLMs for the gate reviewer and sentinel. The default is `claude` (`cli/claude`), which uses your existing Claude Code subscription -- no API key needed. You can also use any other supported provider:

| Provider | Model format | API key env var | Notes |
|----------|-------------|-----------------|-------|
| Claude Code | `cli/claude` (or just `claude`) | (none needed) | Default. Uses your Claude subscription via `claude -p` |
| Google Gemini | `google/gemini-3-flash-preview` | `GOOGLE_API_KEY` | Free tier available |
| Anthropic | `anthropic/claude-haiku-4-5` | `ANTHROPIC_API_KEY` | |
| OpenAI | `openai/gpt-4o` | `OPENAI_API_KEY` | |
| Ollama | `ollama/llama3` | (none needed) | Local models |

Configure via environment variables (all prefixed `CROSS_`):

```bash
# LLM gate (default uses Claude Code, no key needed)
CROSS_LLM_GATE_MODEL=cli/claude

# Or use an API provider
CROSS_LLM_GATE_MODEL=google/gemini-3-flash-preview
CROSS_LLM_GATE_API_KEY=...          # or set GOOGLE_API_KEY

# Sentinel
CROSS_LLM_SENTINEL_MODEL=cli/claude
CROSS_LLM_SENTINEL_INTERVAL_SECONDS=60
```

Or use `cross setup` for guided interactive configuration.

### Denylist Rules

Default rules ship with cross and escalate to LLM review. They cover destructive commands, dangerous git operations (force push, reset --hard, push to main), credential exfiltration, reverse shells, system path writes, process termination, privilege escalation (sudo), mutating HTTP requests, Docker destruction, package management, and shell config edits. Customize with YAML files in `~/.cross/rules.d/`:

```yaml
# ~/.cross/rules.d/my-rules.yaml
rules:
  - name: no-docker-push
    tools: [Bash]
    field: command
    action: escalate
    description: Prevent pushing Docker images
    patterns:
      - 'docker\s+push\b'

# Disable a default rule by name
disable:
  - destructive-rm
```

Rules support `patterns` (regex, case-insensitive) and `contains` (substring matching), and can target specific tools and input fields. Actions: `escalate` (LLM review), `block` (immediate block), `alert` (log only), `halt_session` (freeze session).

### Updating

```bash
cross update                   # latest from PyPI
cross update --path            # install from local source (current directory)
cross update --path /some/dir  # install from a specific local path
cross update --head            # install from main branch on GitHub
```

### All Settings

Settings can be set via environment variables (`CROSS_` prefix) or `.env` files. cross loads `~/.cross/local.env` (personal overrides, survives `cross setup`), then `~/.cross/.env` (generated by setup), then `.env` in the working directory:

| Setting | Default | Description |
|---------|---------|-------------|
| `listen_port` | 2767 | Proxy listen port |
| `gating_enabled` | true | Enable the denylist gate |
| `llm_gate_enabled` | true | Enable LLM review of flagged calls |
| `llm_gate_shadow` | false | Shadow mode: LLM decides but human makes the final call |
| `llm_gate_threshold` | escalate | Min denylist action to trigger LLM review |
| `llm_sentinel_enabled` | true | Enable periodic LLM sentinel reviews |
| `llm_sentinel_interval_seconds` | 60 | Seconds between sentinel review cycles |
| `gate_approval_timeout` | 300 | Seconds to wait for human approval on escalation |
| `native_notifications_enabled` | false | Enable native desktop notifications (macOS) |
| `rules_dir` | ~/.cross/rules.d | Custom rules directory |

## Architecture

cross uses two complementary interception layers:

**PTY wrapper** (`cross wrap`) -- Wraps any CLI agent in a pseudo-terminal for full I/O control. Enables bidirectional messaging relay (Slack/dashboard to agent), terminal-to-phone handoff, and session management. Agent-agnostic.

**Network proxy** -- Intercepts API traffic via `ANTHROPIC_BASE_URL` redirect. Parses streaming SSE responses, buffers tool_use blocks for gate evaluation, and suppresses blocked calls from the response stream. Provides structured monitoring with zero agent modification.

Both layers are coordinated by the daemon (`cross start`), which runs the proxy, gate chain, sentinel, dashboard, and optional Slack and notification plugins as a single process.

## Development

```bash
git clone https://github.com/rfdearborn/cross
cd cross
pip install -e ".[dev,slack]"
python -m pytest tests/
```

Ruff for linting (`ruff check`).

## License

MIT
