convez.ai
BomPluginScore · de 0 a 100

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/aegis

1 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

Estrelas
3
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 1 dia
Versão
v0.8.0
Issues abertas
85
Contribuidores
2

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.

CI License: MIT Platform


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"
  • SHELL should point to Aegis
  • AEGIS_REAL_SHELL should point to your real shell, like /bin/zsh or /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:

LevelWhat happensExample
SafeRuns instantly, no questions askedls, echo hello, git status
WarnAegis asks: "Allow this?"git push --force, npm publish
DangerAegis asks, and can snapshot for rollbackrm -rf ./src, DROP TABLE users
BlockRefused, alwaysrm -rf /, mkfs.ext4 /dev/sda

Install behavior

The convenience installer is global-first.

  • Global — installs the aegis binary, 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 / ~/.codex directories 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 on for 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_MODE and AEGIS_SKIP_SHELL_SETUP controls 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


Contributing

Aegis is open source under the MIT license. Contributions, issues, and feature requests are welcome.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados