Agent Aspect

English | 简体中文

Before, around, and after hooks for AI coding agents.

Agent Aspect is a local runtime control plane for AI coding agents. It sits in front of tools such as Claude Code, Codex CLI, and Kimi Code, observes tool calls, applies local policy, records an audit trail, and gives the user a control plane for approvals, conversations, jobs, and learned-rule suggestions.

What It Does

• Policy enforcement: intercepts risky tool calls through agent hook systems and returns allow / ask / deny decisions.
• Unified audit trail: stores events, decisions, conversations, jobs, feedback, and device attribution in SQLite.
• Bridge control center: exposes a token-protected local HTTP UI for Home, Conversations, Audit, and Run workflows.
• Remote job runner: submits whitelisted local jobs or provider prompts, with cancellation, log streaming, and stale-job recovery.
• Conversation overview: imports provider titles and transcripts, then groups chat messages and tool activity by provider and project.
• Runtime guardrails: binds continue actions to provider/runtime identity and surfaces model, permission, or path drift before a resume goes wrong.
• Learn Mode: suggests future auto-allow rules from real ask-to-allow patterns, while keeping explicit deny rules authoritative.
• Multi-device attribution: records which browser or local hook made a decision using layered device IDs.
• Relay mobile control (optional): pairs a phone browser through a user-owned relay so approvals, conversations, and jobs can continue away from the Mac.

Architecture

AI Agents
  ├─ Claude Code hooks
  ├─ Codex CLI hooks / transcripts
  └─ Kimi Code hooks
        │
        ▼
agent-aspect-hook ── Unix socket ── agent-aspectd
        │                           │
        │                           ├─ Rule engine
        │                           ├─ Learned-rule fallback
        │                           └─ SQLite audit.db
        │
        ▼
agent-aspect-bridge ── HTTP + token ── Web / mobile browser
        │
        └──── WSS ── agent-aspect-relay ── Phone browser  (optional)

Core product rule:

Express mechanisms exhaustively, expose policy gradually, and make trust traceable.

Recommended Deployment

Path	When to use
Local only	Default. Daemon + bridge run on your Mac. Phone accesses bridge over LAN.
LAN / Tailscale	Phone and Mac on the same network or Tailscale mesh. No relay needed.
Self-hosted relay	Phone is on a different network (e.g. mobile data). You run agent-aspect-relay on a VPS you control.

Relay is an optional remote phone channel. It is not a default dependency, not cloud sync, not an account system, and not a multi-tenant SaaS. See docs/relay.md for details.

Quickstart

Prerequisites

• macOS (Apple Silicon)
• Rust toolchain (rustup)
• Claude Code, Codex CLI, or Kimi Code installed

Build

cargo build --release

Install and run

# Install the CLI, daemon, hook, and bridge binaries
cargo install --path crates/cli
cargo install --path crates/daemon
cargo install --path crates/hook-cli
cargo install --path crates/bridge

# Initialize config
agent-aspect init

# Run the doctor to verify your setup
agent-aspect doctor

# Start the daemon (background, listens on Unix socket)
agent-aspect daemon start

# Start the bridge (token-protected HTTP UI)
agent-aspect bridge start

# Get the bridge token for browser access
agent-aspect bridge token

# Open the bridge UI in your browser
open http://127.0.0.1:7676

Set your enforcement mode

# Observer: log everything, block nothing
agent-aspect mode observer

# Autonomous: auto-allow safe calls, ask on risky ones
agent-aspect mode autonomous

# Guard: ask before most write operations
agent-aspect mode guard

# Paranoid: ask before everything
agent-aspect mode paranoid

Build and run the relay (optional)

# Build the relay binary
cargo install --path crates/relay

# Run on your VPS (or locally for testing)
agent-aspect-relay

See docs/relay.md for pairing and deployment.

Development

cargo fmt --check
cargo test
scripts/smoke_test.sh
scripts/bridge_smoke_test.sh
scripts/relay_smoke_test.sh

Useful local commands:

agent-aspect doctor
agent-aspect mode guard
agent-aspect bridge start
agent-aspect bridge status
agent-aspect bridge token

Repository Layout

crates/
  core/       Shared types, SQLite audit store, rule engine, normalization, transcripts
  daemon/     Unix-socket daemon that evaluates hook requests
  hook-cli/   Agent hook entrypoint
  cli/        agent-aspect command-line management tool
  bridge/     Token-protected HTTP bridge and embedded web UI
  relay/      User-owned VPS relay for phone access to the Mac bridge
  shared_ui/  Shared frontend primitives used by bridge and relay

docs/         Public configuration, relay, security, and scope docs
scripts/      Smoke tests for core and bridge flows

Supported Agents

Agent	Status
Claude Code	Supported
Codex CLI	Supported
Kimi Code	Supported
Gemini CLI	Candidate (no runtime experiments, not claimed as supported)

What It Does Not Do

• Not a system sandbox. Agent Aspect intercepts tool calls at the agent hook layer. It does not sandbox the OS.
• Not a cloud service. No accounts, no cloud sync, no hosted dashboard. Everything runs on your Mac.
• Not an agent itself. It does not write code, run prompts, or replace your coding tools.
• Relay is optional. The default path is local-only. Relay exists solely for remote phone access.
• Device IDs are not authentication. They record which browser made a decision, for audit purposes only.
• Learned rules cannot override deny. Explicit deny rules are always authoritative.
• Gemini CLI is not supported. It is a candidate with scaffolding only, no proven end-to-end flow.

Security Model

• Trust anchor is your Mac. The daemon, rule engine, and audit store all run locally.
• The bridge token is generated locally and stored under ~/.agent-aspect/bridge.token.
• All bridge API endpoints require Bearer token auth except GET /health.
• Bridge CORS is intentionally not enabled by default.
• Jobs are restricted to whitelisted kinds and known project paths.
• Device IDs are for audit attribution, not user authentication.
• Learned rules never override explicit deny rules. Deny is always authoritative.
• If you run a relay on the public internet, it must use HTTPS/WSS. Do not use an untrusted relay.

See docs/security.md for the full security model.

Docs

• docs/config.md -- Configuration reference
• docs/relay.md -- Relay deployment guide
• docs/security.md -- Security model
• docs/open-source-scope.md -- What is and is not in scope

License

Licensed under the Apache License, Version 2.0. See LICENSE.