# iliasalmerekov/aegis-shellguard architecture

> Architecture diagram of the GitHub repository iliasalmerekov/aegis-shellguard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iliasalmerekov/aegis-shellguard
- Repository: https://github.com/iliasalmerekov/aegis-shellguard

## Overview

Aegis is a Rust CLI that proxies agent shell commands, assesses risk, asks for approval when needed, and may capture recovery snapshots before execution. The main flow runs from the shell or agent hook through command analysis and planning to a decision, then execution or refusal. Supporting branches include audit, watch mode, installation, and opt-in update notices. The excerpts show selected orchestration and worker details; other links below rely on explicit README descriptions or SOURCE INDEX references, so unsampled implementation details are not inferred.

Main entry points: [`src/execution/mod.rs`](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/execution/mod.rs) (Command execution), [`src/analysis/orchestrate.rs`](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/analysis/orchestrate.rs) (Command analysis), [`src/main.rs`](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/main.rs) (CLI dispatch), [`src/planning/core.rs`](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/planning/core.rs) (Interception planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_cli["CLI dispatch<br/>[main.rs]"]
  node_shell_proxy["Shell proxy<br/>[shell_wrapper.rs]"]
  node_agent_hooks["Agent hooks<br/>[hook.rs]"]
  node_watch["Watch mode<br/>[runner.rs]"]
end

subgraph group_analysis["Command analysis"]
  node_command_analysis["Command analysis<br/>[orchestrate.rs]"]
  node_shell_routing["Shell routing<br/>[router.rs]"]
  node_source_read["Script source reader<br/>[source_reader.rs]"]
  node_language_worker["Language worker<br/>[worker.rs]"]
  node_language_adapters["Language adapters"]
  node_command_parser["Command parser"]
  node_risk_scanner["Risk scanner<br/>[lib.rs]"]
end

subgraph group_decision["Policy and recovery"]
  node_planning["Interception planning<br/>[core.rs]"]
  node_policy["Policy engine<br/>[engine.rs]"]
  node_config["Configuration<br/>[model.rs]"]
  node_snapshots["Snapshot providers<br/>[lib.rs]"]
  node_snapshot_state[("Snapshot state<br/>[sqlite.rs]")]
end

subgraph group_runtime["Execution and records"]
  node_execution["Command execution<br/>[mod.rs]"]
  node_sandbox["Sandbox confinement<br/>[lib.rs]"]
  node_audit[("Audit logging<br/>[logger.rs]")]
  node_explanations["Decision explanations<br/>[formatter.rs]"]
end

subgraph group_support["User integrations"]
  node_tui["Approval interface<br/>[confirm_screen.rs]"]
  node_rollback["Rollback command<br/>[rollback.rs]"]
  node_installer["Shell and hook setup<br/>[mod.rs]"]
  node_updates["Update notices<br/>[mod.rs]"]
  node_registry["npm registry"]
end

node_user(("User or agent"))

node_user -->|"runs command"| node_shell_proxy
node_user -->|"configures hooks"| node_agent_hooks
node_user -->|"starts watch"| node_watch
node_shell_proxy -->|"invokes binary"| node_cli
node_agent_hooks -->|"invokes command"| node_cli
node_cli -->|"starts analysis"| node_command_analysis
node_watch -->|"plans commands"| node_planning
node_command_analysis -->|"routes targets"| node_shell_routing
node_shell_routing -->|"reads scripts"| node_source_read
node_command_analysis -->|"requests analysis"| node_language_worker
node_language_worker -->|"parses source"| node_language_adapters
node_shell_routing -->|"resolves commands"| node_command_parser
node_command_analysis -.->|"assesses risk"| node_risk_scanner
node_command_analysis -->|"supplies assessment"| node_planning
node_planning -.->|"evaluates policy"| node_policy
node_planning -.->|"uses settings"| node_config
node_planning -->|"authorizes execution"| node_execution
node_execution -->|"requests approval"| node_tui
node_execution -->|"creates snapshots"| node_snapshots
node_snapshots -.->|"stores metadata"| node_snapshot_state
node_execution -->|"confines process"| node_sandbox
node_execution -->|"records decision"| node_audit
node_execution -->|"renders rationale"| node_explanations
node_rollback -->|"restores snapshot"| node_snapshots
node_cli -->|"dispatches setup"| node_installer
node_cli -->|"dispatches update"| node_updates
node_updates -->|"checks versions"| node_registry

click node_cli "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/main.rs"
click node_shell_proxy "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/shell_wrapper.rs"
click node_agent_hooks "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/install/hook.rs"
click node_watch "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/watch/runner.rs"
click node_command_analysis "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/analysis/orchestrate.rs"
click node_shell_routing "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/analysis/router.rs"
click node_source_read "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/analysis/source_reader.rs"
click node_language_worker "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-language/src/worker.rs"
click node_language_adapters "https://github.com/iliasalmerekov/aegis-shellguard/tree/main/crates/aegis-language/src/languages"
click node_command_parser "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-parser/src/embedded_scripts.rs"
click node_risk_scanner "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-scanner/src/lib.rs"
click node_planning "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/planning/core.rs"
click node_policy "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-policy/src/engine.rs"
click node_config "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-config/src/model.rs"
click node_snapshots "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-snapshot/src/lib.rs"
click node_snapshot_state "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-snapshot/src/sqlite.rs"
click node_execution "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/execution/mod.rs"
click node_sandbox "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-sandbox/src/lib.rs"
click node_audit "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-audit/src/logger.rs"
click node_explanations "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/explanation/formatter.rs"
click node_tui "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-tui/src/confirm_screen.rs"
click node_rollback "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/rollback.rs"
click node_installer "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/install/mod.rs"
click node_updates "https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/update/mod.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_shell_proxy,node_agent_hooks,node_watch,node_user toneBlue
class node_command_analysis,node_shell_routing,node_source_read,node_language_worker,node_language_adapters,node_command_parser,node_risk_scanner toneAmber
class node_planning,node_policy,node_config,node_snapshots,node_snapshot_state toneMint
class node_execution,node_sandbox,node_audit,node_explanations toneRose
class node_tui,node_rollback,node_installer,node_updates,node_registry toneIndigo
```

## Components

### Command entry

- [CLI dispatch](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/main.rs): `src/main.rs`
- [Shell proxy](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/shell_wrapper.rs): `src/shell_wrapper.rs`
- [Agent hooks](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/install/hook.rs): `src/install/hook.rs`
- [Watch mode](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/watch/runner.rs): `src/watch/runner.rs`

### Command analysis

- [Command analysis](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/analysis/orchestrate.rs): `src/analysis/orchestrate.rs`
- [Shell routing](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/analysis/router.rs): `src/analysis/router.rs`
- [Script source reader](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/analysis/source_reader.rs): `src/analysis/source_reader.rs`
- [Language worker](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-language/src/worker.rs): `crates/aegis-language/src/worker.rs`
- [Language adapters](https://github.com/iliasalmerekov/aegis-shellguard/tree/main/crates/aegis-language/src/languages): `crates/aegis-language/src/languages`
- [Command parser](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-parser/src/embedded_scripts.rs): `crates/aegis-parser/src/embedded_scripts.rs`
- [Risk scanner](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-scanner/src/lib.rs): `crates/aegis-scanner/src/lib.rs`

### Policy and recovery

- [Interception planning](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/planning/core.rs): `src/planning/core.rs`
- [Policy engine](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-policy/src/engine.rs): `crates/aegis-policy/src/engine.rs`
- [Configuration](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-config/src/model.rs): `crates/aegis-config/src/model.rs`
- [Snapshot providers](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-snapshot/src/lib.rs): `crates/aegis-snapshot/src/lib.rs`
- [Snapshot state](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-snapshot/src/sqlite.rs): `crates/aegis-snapshot/src/sqlite.rs`

### Execution and records

- [Command execution](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/execution/mod.rs): `src/execution/mod.rs`
- [Sandbox confinement](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-sandbox/src/lib.rs): `crates/aegis-sandbox/src/lib.rs`
- [Audit logging](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-audit/src/logger.rs): `crates/aegis-audit/src/logger.rs`
- [Decision explanations](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/explanation/formatter.rs): `src/explanation/formatter.rs`

### User integrations

- [Approval interface](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/crates/aegis-tui/src/confirm_screen.rs): `crates/aegis-tui/src/confirm_screen.rs`
- [Rollback command](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/rollback.rs): `src/rollback.rs`
- [Shell and hook setup](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/install/mod.rs): `src/install/mod.rs`
- [Update notices](https://github.com/iliasalmerekov/aegis-shellguard/blob/main/src/update/mod.rs): `src/update/mod.rs`
- **npm registry**

### Other components

- **User or agent**

## Connections

- User or agent → Shell proxy: runs command (evidence: `README.md`)
- User or agent → Agent hooks: configures hooks (evidence: `README.md`)
- User or agent → Watch mode: starts watch (evidence: `README.md`)
- Shell proxy → CLI dispatch: invokes binary (evidence: `README.md`)
- Agent hooks → CLI dispatch: invokes command (evidence: `README.md`)
- CLI dispatch → Command analysis: starts analysis (evidence: `src/main.rs`)
- Watch mode → Interception planning: plans commands (evidence: `src/watch/runner.rs`)
- Command analysis → Shell routing: routes targets (evidence: `src/analysis/orchestrate.rs`)
- Shell routing → Script source reader: reads scripts (evidence: `src/analysis/router.rs`)
- Command analysis → Language worker: requests analysis (evidence: `src/analysis/orchestrate.rs`)
- Language worker → Language adapters: parses source (evidence: `crates/aegis-language/src/worker.rs`)
- Shell routing → Command parser: resolves commands (evidence: `src/analysis/router.rs`)
- Command analysis → Risk scanner: assesses risk
- Command analysis → Interception planning: supplies assessment
- Interception planning → Policy engine: evaluates policy
- Interception planning → Configuration: uses settings
- Interception planning → Command execution: authorizes execution (evidence: `README.md`)
- Command execution → Approval interface: requests approval (evidence: `README.md`)
- Command execution → Snapshot providers: creates snapshots (evidence: `src/execution/mod.rs`)
- Snapshot providers → Snapshot state: stores metadata (evidence: `crates/aegis-snapshot/src/lib.rs`)
- Command execution → Sandbox confinement: confines process (evidence: `src/execution/mod.rs`)
- Command execution → Audit logging: records decision (evidence: `README.md`)
- Command execution → Decision explanations: renders rationale
- Rollback command → Snapshot providers: restores snapshot (evidence: `README.md`)
- CLI dispatch → Shell and hook setup: dispatches setup (evidence: `src/main.rs`)
- CLI dispatch → Update notices: dispatches update (evidence: `src/main.rs`)
- Update notices → npm registry: checks versions (evidence: `src/update/mod.rs`)
