Alfred

Alfred is a repo-aware Codex companion.

It gives you:

• one global Alfred for your user context and external channels
• one repo Alfred per repository for local execution
• a small CLI to setup, start, inspect, and repair the runtime

Get Started

1. Install prerequisites

Required:

• Node.js >= 22
• npm
• git
• sqlite3
• Codex CLI installed and authenticated

macOS:

brew install node git sqlite
brew install --cask codex

Debian / Ubuntu:

sudo apt-get update
sudo apt-get install -y nodejs npm git sqlite3

Windows native is not supported yet. Use WSL2.

2. Install Alfred

From npm:

npm install -g @ban_/alfred
alfred --version

From source:

git clone <repo-url> alfred
cd alfred
npm install
npm run build
npm link
alfred --version

3. Run first-time setup

Global setup:

alfred setup --global

Non-interactive setup:

alfred setup --global --yes

Alfred will:

• detect codex
• write ~/.alfred/config.json
• create ~/.alfred/user/SOUL.md
• create ~/.alfred/user/MEMORY.md

If a dependency is missing, Alfred prints the install hint for your platform.

4. Setup a repo

Inside a repo:

cd /path/to/repo
alfred setup

Or explicitly:

alfred setup --repo /path/to/repo

This creates the repo Alfred context, including AGENTS.md, MEMORY.md, and the local runtime state.

5. Start working

Inside a repo:

cd /path/to/repo
alfred

Outside any repo:

cd ~
alfred --global

Core Commands

alfred
alfred setup
alfred doctor
alfred status
alfred watch --last 30
alfred ticket --task "Implement the pagination fix"
alfred reset

Useful forms:

alfred doctor --fix
alfred setup --yes
alfred status --global
alfred setup --repo /path/to/repo

WhatsApp

WhatsApp is optional.

Configure and pair:

alfred gateway start
alfred gateway whatsapp config --owner +33612345678 --enable
alfred gateway whatsapp pair
alfred gateway whatsapp status

Reset a broken session:

alfred gateway whatsapp reset
alfred gateway stop
alfred gateway start

Release Checks

Before publishing a new package:

npm run typecheck
npm run build
npm run smoke:npm-install
npm pack --dry-run

More

For deeper onboarding and install notes, see docs/install-and-onboarding.md.