aegis
IliasAlmerekov/aegis
Shield your terminal from AI agents. Aegis intercepts every shell command, auto-snapshots your data before dangerous operations, and asks before anything destructive runs. Works with Claude Code, Codex, Cursor, and any agent that uses $SHELL.
Instalação
npx convez-ai IliasAlmerekov/aegis1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Aegis
A simple safety layer for AI agents. It sits between the agent and your terminal, and asks before dangerous commands run.
What Aegis does
AI agents are fast. Sometimes too fast.
One bad command can:
- delete files,
- reset a repo,
- drop a database,
- or push something dangerous.
Aegis adds one small safety step.
It checks the command first:
- safe commands run right away,
- risky commands ask for confirmation,
- the worst commands are blocked.
Install Aegis
Works on:
- Linux
- macOS
- Windows with WSL2
native Windows shells like PowerShell and cmd.exe are not supported.
Step 1: run the installer
curl -fsSL https://raw.githubusercontent.com/IliasAlmerekov/aegis/main/scripts/install.sh | sh
Step 2: reload your shell
source ~/.bashrc # bash
# or
source ~/.zshrc # zsh
Or open a new terminal window — either works.
Step 3: confirm the binary is on your PATH
aegis --version
If you see a version number, the install worked and the aegis binary is available.
Check that Aegis is really working
Run these two commands:
# This should show a confirmation prompt. Press n.
aegis -c 'rm -rf /tmp/aegis-test'
# This should run immediately.
aegis -c 'echo hello'
If the second command shows a prompt and the third prints hello right away, Aegis is working.
Optional: check shell routing
echo "$SHELL"
echo "$AEGIS_REAL_SHELL"
SHELLshould point to AegisAEGIS_REAL_SHELLshould point to your real shell, like/bin/zshor/bin/bash
What happens when a command is checked?
When an AI agent runs a shell command, Aegis intercepts it and decides what to do:
| Level | What happens | Example |
|---|---|---|
| Safe | Runs instantly, no questions asked | ls, echo hello, git status |
| Warn | Aegis asks: "Allow this?" | git push --force, npm publish |
| Danger | Aegis asks, and can snapshot for rollback | rm -rf ./src, DROP TABLE users |
| Block | Refused, always | rm -rf /, mkfs.ext4 /dev/sda |
Install behavior
The convenience installer is global-first.
- Global — installs the
aegisbinary, writes the managed shell-integration block, and then auto-attempts Claude Code / Codex hook setup through the installed binary.- Supported agent directories that already exist are updated automatically.
- Missing
~/.claude/~/.codexdirectories are skipped instead of being created just for hook installation.
- Local — the old project-only shell mode has been removed from the
convenience installer. Use
aegis off/aegis onfor a temporary local workflow change without uninstalling the shell wrapper, or configure a manual shell path only for the agent you care about. - Binary — the old binary-only installer mode has been removed. If you only want the binary, use the verification-first manual path or the source install path below.
- The installer rejects the removed
AEGIS_SETUP_MODEandAEGIS_SKIP_SHELL_SETUPcontrols instead of silently ignoring them.
Automatic shell setup currently recognizes bash and zsh.
If you use another shell or a custom rc file, set:
AEGIS_SHELL_RC=/path/to/your/rcfile
and run the installer again.
If you are already inside an Aegis shell, also set:
AEGIS_REAL_SHELL=/path/to/your/real/shell
When disabled, Aegis behaves as though it is not installed for ordinary local
shell and supported agent usage. By default, detected CI environments ignore
the local disabled flag and continue enforcing policy. AEGIS_CI can
explicitly override CI detection.
If automatic agent setup did not run
If Claude Code or Codex was not installed yet, start the agent once so its config directory exists, then run:
aegis install-hooks --all
This installs supported hooks for Claude Code and Codex when their config folders already exist, and skips any agent directory that is still absent.
If you have not opened a new shell yet, you can also use the absolute path that the installer printed, such as:
$HOME/.local/bin/aegis install-hooks --all
Alternative: install from source
If the pre-built binary is not available for your platform:
cargo install --git https://github.com/IliasAlmerekov/aegis aegis
Windows
Aegis works on Windows through WSL2 (Windows Subsystem for Linux).
Open a WSL2 terminal and run the install command there.
native Windows shells like PowerShell and cmd.exe are not supported.
Turn it off and on again
If you want to pause Aegis for a moment:
aegis off
To turn it back on:
aegis on
To see the current state:
aegis status
If Aegis is disabled locally, detected CI environments still enforce policy by default.
Connect to your AI agent
Claude Code
In many setups, Claude Code will automatically use Aegis because $SHELL already points to it.
If you need to set it manually:
command -v aegis
Then paste that path into the shell field.
Codex, Cursor, and other agents
If the agent respects $SHELL — it works automatically.
If the agent has its own shell setting, find the shell field and set it to:
command -v aegis
# e.g. /usr/local/bin/aegis
For Codex, optional hooks can also add startup guidance and block Bash commands that are not wrapped through aegis --command.
Useful commands
aegis status # show current state
aegis off # disable temporarily
aegis on # enable again
aegis audit --last 20 # last 20 entries
aegis audit --risk Danger # only dangerous commands
aegis audit --format json # export as JSON
aegis audit --verify-integrity # verify audit chain
aegis config init # create .aegis.toml in the current directory
aegis config show # print the active config
aegis config validate # validate merged config
aegis rollback '<snapshot-id>'
Snapshots
For dangerous commands, Aegis can take best-effort snapshots with configured providers such as:
- Git
- Docker
- PostgreSQL
- MySQL / MariaDB
- SQLite
- Supabase
Add your own rules
Add to ~/.config/aegis/config.toml or .aegis.toml:
[[custom_patterns]]
id = "USR-001"
risk = "Danger"
pattern = "my-nuke-script\\.sh"
description = "Internal teardown script"
safe_alt = "my-nuke-script.sh --dry-run"
Limitations
Aegis is a heuristic text filter, not a sandbox. It will not catch:
- Obfuscated or encoded commands
eval "$(something)"— commands assembled at runtime- Indirect execution: write a script first, run it later
Full details: Threat model
Uninstall
curl -fsSL https://raw.githubusercontent.com/IliasAlmerekov/aegis/main/scripts/uninstall.sh | sh
Docs
- Architecture decisions
- Changelog
- Current release line
- Config schema
- Release readiness
- Threat model
- Platform support
- CI and releases
- Troubleshooting and recovery
Contributing
Aegis is open source under the MIT license. Contributions, issues, and feature requests are welcome.
License
MIT — see LICENSE.