What Agent Kernel adds

┌───────────────────────────────────────────────────────────────────────────────┐
│                              AGENT KERNEL                                     │
├──────────────────────────┬──────────────────────────┬─────────────────────────┤
│ Reviewed local memory    │ Project Environment Vault│ Architecture Guardian   │
│ Rules and preferences    │ Identity and revisions   │ Policies and contracts  │
│ Approval inbox           │ Safe restore and watcher │ Baselines and reports   │
├──────────────────────────┴──────────────────────────┴─────────────────────────┤
│ Universal Skills · Failure Lessons · Agent integrations · Local dashboard    │
└───────────────────────────────────────────────────────────────────────────────┘

| Recurring problem | Agent Kernel response | |---|---| | Rules are repeated in every prompt | Durable reviewed memory compiled into agent-readable files | | Claude, Codex, Cursor, and Gemini drift from each other | One source distributed to supported agent surfaces | | Local .env files disappear after a fresh clone | Environment Vault with stable identity, revisions, missing-only restore, conflicts, and backups | | Agents need repository-specific operating instructions | Universal Skills copied into supported agent directories | | The same build or test failure returns | Failure Lessons with command, error, cause, fix, and evidence | | AI-generated code creates structural drift | Architecture policies, contracts, baselines, reuse search, and checks | | An agent identifies a useful rule | Proposal inbox with explicit review and publication | | A hosted control plane is unwanted | Local Node CLI, optional hooks, MCP tools, and zero runtime dependencies |

Install

Universal installer

curl -sSL https://raw.githubusercontent.com/imMamdouhaboammar/agent-kernel/master/install.sh | bash

npm

npm install -g @mamdouh-aboammar/agent-kernel
agent-kernel setup

Bun

bun install -g @mamdouh-aboammar/agent-kernel
agent-kernel setup

Run without global installation

npx -y @mamdouh-aboammar/agent-kernel setup

Requires Node.js >=18.18.0 or Bun >=1.0.0

Read docs/INSTALL_AND_AGENT_SETUP.md for agent-specific installation details

⚡ Quick-start prompt — copy and paste into any AI coding agent

Paste the block below into Claude Code, Cursor, Gemini CLI, Codex, or any AGENTS.md-compatible agent. The agent will install or upgrade Agent Kernel, connect your project, activate all tools, save your environment files, and enable the watcher.

You are setting up Agent Kernel in this project. Execute the following steps in order, stopping and reporting any failure before continuing.

## Step 1 — Install or upgrade Agent Kernel

Check if agent-kernel is already installed:

```bash
agent-kernel --version 2>/dev/null || echo "NOT_INSTALLED"
```

If NOT_INSTALLED, install with Bun (preferred) or npm:

```bash
# With Bun (preferred — requires Bun >= 1.0.0)
bun install -g @mamdouh-aboammar/agent-kernel

# Or with npm (requires Node.js >= 18.18.0)
npm install -g @mamdouh-aboammar/agent-kernel
```

If already installed, upgrade to the latest version:

```bash
agent-kernel update
```

Confirm the installed version:

```bash
agent-kernel --version
```

## Step 2 — Initialize and connect this project

Initialize the local Agent Kernel home if this is a fresh machine:

```bash
agent-kernel init --sync
agent-kernel doctor
```

Connect this repository to Agent Kernel:

```bash
agent-kernel project connect --yes
agent-kernel project status --json
```

## Step 3 — Link and activate all agent tools

Compile rules and link generated guidance into all supported agent surfaces (AGENTS.md, CLAUDE.md, Cursor rules, Gemini config):

```bash
agent-kernel compile
agent-kernel-safe-link .
```

Install MCP tools so every connected agent can call Agent Kernel capabilities:

```bash
agent-kernel mcp install claude
agent-kernel mcp install codex
```

Install safety hooks:

```bash
agent-kernel-safe-git-hook .
```

Verify all tools are active:

```bash
agent-kernel status
agent-kernel doctor
```

## Step 4 — Save environment files (Environment Vault)

Discover and link all .env files in this project:

```bash
agent-kernel env link .
```

Push all current .env files to the vault exactly as they are — do NOT modify file contents:

```bash
agent-kernel env push .
```

Confirm the vault is healthy and all files are stored:

```bash
agent-kernel env status . --json
```

## Step 5 — Enable the environment watcher (mirror mode)

Start watching .env files for changes and automatically mirror them to the vault:

```bash
agent-kernel env watch .
```

## Done — confirm the full setup

Run a final health check and report the output:

```bash
agent-kernel doctor
agent-kernel env status . --json
agent-kernel project status --json
```

Report: version installed, number of env files stored, project identity fingerprint, and which agent surfaces received compiled guidance.

Project Environment Vault

Environment Vault stores project environment files only on the current machine under

${AGENT_KERNEL_HOME:-~/.agent-kernel}/vault/env/<full-sha256>/

It derives identity from a canonical Git remote, then the initial commit, with path identity available only through explicit opt-in

SSH and HTTPS forms for the same GitHub repository resolve to one fingerprint

# Discover and link .env files recursively
agent-kernel env link

# Inspect identity, health, conflicts, and permissions
agent-kernel env status

# Store local edits and create revisions
agent-kernel env push

# Restore missing files without overwriting differing local files
agent-kernel env pull

# Force an intentional overwrite after creating a local backup
agent-kernel env pull --force

# Diagnose metadata, missing files, and owner-only permissions
agent-kernel env doctor

# Watch files edited outside Agent Kernel hooks
agent-kernel env watch

Monorepo paths can be selected explicitly

agent-kernel env link \
  --include apps/api/.env \
  --include apps/web/.env.local

unlink retains stored files and revisions

purge --yes performs explicit destructive deletion

Read docs/ENVIRONMENT_VAULT.md for the command contract, storage model, migration, watcher behavior, and threat boundaries

Universal Agent Skills

agent-kernel skills list
agent-kernel skills inspect agent-kernel-ops
agent-kernel skills sync

Agent Kernel ships operational skills and synchronizes them to supported agent directories such as ~/.claude/skills, ~/.codex/skills, ~/.gemini/config/skills, and ~/.agents/skills

Failure Lessons and self-evolve workflows

agent-kernel failure capture
agent-kernel failure list
agent-kernel failure search <query>
agent-kernel evolve generate --title "Full Supabase Setup" --topic "auth"
agent-kernel evolve list
agent-kernel evolve inspect <playbookId>
agent-kernel evolve hooks

Failure Lessons preserve evidence from unsuccessful commands and verified remedies

Self-evolve workflows turn reviewed execution patterns into versioned local playbooks

Architecture Guardian

cd ~/Projects/YourProject

agent-kernel architecture init .
agent-kernel architecture policy validate .
agent-kernel architecture discover . --json
agent-kernel architecture baseline . --json

agent-kernel architecture contract init . \
  --task 'Add subscription cancellation' \
  --owner billing \
  --allow 'src/billing/**,test/billing/**' \
  --expect 'src/billing/cancel-subscription.ts'

agent-kernel architecture reuse 'cancel subscription' . --json
agent-kernel architecture check . --json

Read docs/ARCHITECTURE_GUARDIAN.md and skills/architecture-guardian/

Local Memory Dashboard

agent-kernel dashboard

The dashboard is written atomically to ~/.agent-kernel/reports/dashboard.html, uses no network requests, redacts known credential patterns, and applies a restrictive Content Security Policy

Read docs/STATIC_MEMORY_DASHBOARD.md

Agent integrations

| Agent or surface | Output or integration | |---|---| | Claude Code | CLAUDE.md, context and architecture hooks, MCP config, marketplace plugin, repo-local skills | | Antigravity | .agents/agents.md, .agents/skills/*, hooks | | Cursor | .cursor/rules/00-agent-kernel.mdc | | Codex | AGENTS.md, .codex/AGENTS.md, .codex/config.toml, repo-local skills | | Gemini CLI | GEMINI.md | | OpenCode and OpenClaw | AGENTS.md, hooks | | Kiro and Skills.sh | SKILL.md, skills.sh.json |

Core command reference

agent-kernel setup
agent-kernel env link|status|push|pull|watch|doctor|history|restore|list|unlink|purge
agent-kernel skills list|inspect|sync|install
agent-kernel evolve generate|list|inspect|repair|hooks
agent-kernel init [--sync] [--enforce]
agent-kernel doctor [--runtime]
agent-kernel compile
agent-kernel sync
agent-kernel remember <text> [--type rule] [--publish]
agent-kernel propose --from <agent> --text <text> --reason <reason>
agent-kernel inbox
agent-kernel approve <id> [--publish]
agent-kernel reject <id>
agent-kernel dashboard [--out file.html] [--json]
agent-kernel architecture init|discover|baseline|check|reuse|contract
agent-kernel failure capture|learn|list|search|show|propose
agent-kernel retention status|prune
agent-kernel export <file.json>
agent-kernel import <file.json>

Documentation

Start with docs/README.md

| Need | Read | |---|---| | Install and connect agents | docs/INSTALL_AND_AGENT_SETUP.md | | Complete command reference | docs/COMMAND_REFERENCE.md | | Project Environment Vault | docs/ENVIRONMENT_VAULT.md | | Environment variables | docs/ENVIRONMENT_VARIABLES.md | | Skill contract and synchronization | docs/SKILL_CONTRACT.md | | Secure runtime and release operations | docs/SECURE_RUNTIME_AND_RELEASES.md | | Failure Lessons protocol | docs/FAILURE_LESSONS_PROTOCOL.md | | Architecture checks | docs/ARCHITECTURE_GUARDIAN.md | | Local memory dashboard | docs/STATIC_MEMORY_DASHBOARD.md | | Trusted CLI updates | docs/UPDATES.md | | Safe project linking | docs/SAFE_LINKING.md | | Safe Git hook installation | docs/SAFE_GIT_HOOKS.md | | Troubleshooting | docs/TROUBLESHOOTING.md |

Development and verification

git clone https://github.com/imMamdouhaboammar/agent-kernel
cd agent-kernel
npm ci
npm run verify:release
npm run docs:check

License

MIT © Mamdouh Aboammar