https://github.com/lioneltchami/superwarp-toolkit
Superwarp Toolkit: macOS-first Warp terminal toolkit for install, permissions, tab configs, and workflow automation to make Warp smarter.
https://github.com/lioneltchami/superwarp-toolkit
ai ai-tools automation cli developer-tools macos productivity shell terminal toolkit warp warp-terminal workflows zsh
Last synced: 28 days ago
JSON representation
Superwarp Toolkit: macOS-first Warp terminal toolkit for install, permissions, tab configs, and workflow automation to make Warp smarter.
- Host: GitHub
- URL: https://github.com/lioneltchami/superwarp-toolkit
- Owner: lioneltchami
- License: mit
- Created: 2026-06-04T17:31:22.000Z (28 days ago)
- Default Branch: main
- Last Pushed: 2026-06-04T18:20:25.000Z (28 days ago)
- Last Synced: 2026-06-04T21:10:33.336Z (28 days ago)
- Topics: ai, ai-tools, automation, cli, developer-tools, macos, productivity, shell, terminal, toolkit, warp, warp-terminal, workflows, zsh
- Language: Shell
- Size: 82 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🚀 Superwarp Toolkit
**A polished Warp terminal toolkit for macOS with install, uninstall, doctor, permissions, search, automation, and local AI helpers.**
> **macOS-first refresh:** this repo keeps the best parts of the original Warp AI idea, but reshapes them into a tighter, cleaner, more honest toolkit for real macOS Warp workflows.
## 🎯 What This Is
Superwarp Toolkit is a **macOS-first helper layer for the Warp terminal**.
It gives you:
- **⚡ Faster setup** with an installer, uninstall script, and permission helper
- **🩺 Better trust** with `warpai-doctor` for runtime checks
- **🧠 Useful terminal helpers** for calculation, search, image prompting, and Warp pane control
- **📝 Lightweight session logging** and startup context
- **🎛️ Optional AI integrations** through Gemini CLI, Grok CLI, Codex CLI, and Ollama
This branch is intentionally **smaller and cleaner** than the old Windows-heavy version. It is not trying to be an “everything platform.” It focuses on being a solid macOS Warp toolkit you can install, validate, and use.
## ✨ Highlights
- **`install.sh`**
Installs the suite into `~/.superwarp-toolkit` and wires it into `~/.zshrc`.
Legacy `~/.warp-ai-enhancement` installs are migrated automatically for compatibility.
- **`uninstall.sh`**
Cleanly removes the managed loader block and installed toolkit files.
- **`warpai-doctor`**
Checks shell loading, key binaries, and likely GUI permission readiness.
- **`warpai-permissions`**
Reopens the relevant macOS Privacy & Security panes for:
- `Accessibility`
- `Automation`
- `Screen Recording`
- **`warpai-search`**
Uses Gemini CLI when available, then Grok CLI, then DuckDuckGo when web tools are unavailable.
- **`warpai-grok`**
Directs a prompt to Grok for headless research or coding-style assistance.
- **`warpai-calc`**
Uses a restricted AST-based numeric evaluator rather than unsafe `eval`.
- **`warpai-image`**
Runs a local Ollama multimodal model against an image path and prompt.
- **`warpai-cmd`**
Supports:
- `split right`
- `split down`
- `close panel`
- `screenshot`
- **`warpai-usage` / `warpai-quick`**
Read-only Warp usage helpers that summarize local SQLite history and the current quota snapshot from Warp's preference plist.
- **`warpai-layout-install`**
Installs bundled Warp Tab Configs into the active Warp tab config directory for a more native session bring-up flow.
- **`warpai-open`**
Opens the bundled Superwarp Tab Configs or the macOS permission panes.
- **`warpai-codex`**
Sends prompts to your local Codex CLI for faster triage, planning, and repo-aware suggestions.
## 🛠️ What’s Included
Core files:
- `install.sh`
- `uninstall.sh`
- `warp-ai-enhancement-profile.zsh`
- `scripts/warp-ai-toolkit.sh`
- `tests/smoke.sh`
- `WARP.md`
- `.agents/skills/`
- `.warp/workflows/`
Core commands:
- `warpai-search`
- `warpai-calc`
- `warpai-image`
- `warpai-cmd`
- `warpai-doctor`
- `warpai-permissions`
- `warpai-usage`
- `warpai-quick`
- `warpai-layout-install`
- `warpai-open`
- `warpai-codex`
- `warpai-grok`
Warp-native repo assets:
- `.agents/skills/suite-maintainer`
- `.agents/skills/tab-config-installer`
- `.agents/skills/warp-permission-doctor`
- `.agents/skills/usage-session-analyst`
- `.agents/skills/codex-command-assistant`
- `.warp/workflows/suite-health-check.yaml`
- `.warp/workflows/permission-readiness-check.yaml`
- `.warp/workflows/usage-snapshot.yaml`
- `.warp/workflows/install-suite-safely.yaml`
- `.warp/workflows/install-uninstall-validation.yaml`
- `.warp/workflows/install-tab-configs.yaml`
- `.warp/workflows/bootstrap-superwarp.yaml`
- `.warp/workflows/codex-assistant.yaml`
## 🍏 Requirements
Required:
- macOS
- `zsh`
- `bash`
Installed automatically if missing:
- `python3`
Optional companion tools:
- **Gemini CLI** for better search and web-grounded responses
- **Grok CLI** for direct headless prompts and alternative model routing
- **Ollama** for local image analysis and multimodal workflows
- **Codex CLI** for repo-aware agent-style breakdowns and coding suggestions
## 🚀 Installation
```bash
git clone https://github.com/lioneltchami/superwarp-toolkit.git
cd superwarp-toolkit
chmod +x ./install.sh
./install.sh
```
### Use on another Mac
On another machine, run:
```bash
git clone https://github.com/lioneltchami/superwarp-toolkit.git
cd superwarp-toolkit
git checkout main
chmod +x ./install.sh
./install.sh
```
To sync future updates later:
```bash
cd superwarp-toolkit
git pull origin main
./install.sh --no-permission-panes
```
### Fresh machine verification
After cloning + install, run:
```bash
source ~/.zshrc
warpai-doctor
```
You should see at least:
- `python3: ok`
- `toolkit file: ok`
Optional quick smoke validation:
```bash
./tests/smoke.sh
```
### GitHub Actions validation
This repository runs GitHub Actions on every push and pull request to `main`:
- syntax and shell checks
- install smoke path (`./install.sh --no-permission-panes`)
- full suite smoke tests (`./tests/smoke.sh`)
It helps keep the toolkit safe to clone on a fresh Mac and quickly update via git.
If you want a quick command-surface check:
```bash
warpai-grok "Summarize recent macOS automation gotchas"
warpai-calc "2 + 2"
warpai-codex "Summarize this session setup"
```
`warpai-codex` is optional; run this command only after you have installed and authorized Codex.
If you're working inside Warp and want a practical, screen-by-screen setup flow, see:
- [Warp Usage Guide](./WARP-INSIDE.md)
## 🚀 Releases
This repo can publish GitHub Releases automatically when you push a version tag.
Use:
```bash
git tag v1.0.0
git push origin v1.0.0
```
The release workflow will:
- build a `tar.gz` artifact from the tagged commit
- attach a `sha256` checksum file
- generate release notes automatically
Then users can install from source as usual:
```bash
git clone https://github.com/lioneltchami/superwarp-toolkit.git
cd superwarp-toolkit
git checkout
./install.sh
```
For production-style sharing, you can also download the release asset directly from GitHub Releases.
### What the installer does
- installs the suite into `~/.superwarp-toolkit`
- parses command-line flags and, when no optional install flags are passed, prompts for optional components
- appends a managed loader block to `~/.zshrc`
- installs `python3` automatically if needed
- uses Homebrew for `python3`, and bootstraps Homebrew first if necessary
- optionally installs Gemini CLI, Grok CLI, Ollama, and Codex
- opens the relevant macOS Privacy & Security panes during interactive installs
### Installer options
```bash
./install.sh --no-shell-hook
./install.sh --no-permission-panes
./install.sh --accept-defaults
WARP_AI_ACCEPT_DEFAULTS=1 ./install.sh
./install.sh --install-gemini
./install.sh --install-ollama
./install.sh --install-codex
./install.sh --install-grok
./install.sh --install-gemini --install-ollama
./install.sh --install-codex --no-permission-panes
./install.sh --install-grok --no-permission-panes
./install.sh --accept-defaults --no-permission-panes
./install.sh --help
```
If you run `./install.sh` with no install flags in an interactive terminal, it now prompts for each optional component.
Press Enter for “yes” to install or `n` to skip.
If run non-interactively, it skips optional prompts and only installs required files unless you pass explicit flags or enable defaults via `--accept-defaults` / `WARP_AI_ACCEPT_DEFAULTS` / `.superwarp-toolkit.env`.
You can also control this via environment:
```bash
export WARP_AI_ACCEPT_DEFAULTS=1
./install.sh
```
Accepted values: `1`, `true`, `yes`, `on`, `enabled`.
If you want this behavior to persist for this repository, set it in:
```text
.superwarp-toolkit.env
```
Or point to a custom defaults file with `WARP_AI_INSTALL_DEFAULTS_FILE`:
```bash
export WARP_AI_INSTALL_DEFAULTS_FILE="/path/to/custom.defaults"
./install.sh
```
### `--install-grok` setup example
Grok is installed with the official xAI installer by default, or a custom command path:
```bash
export WARP_AI_GROK_INSTALL_COMMAND="curl -fsSL https://x.ai/cli/install.sh | bash"
export WARP_AI_GROK_BIN="grok"
export WARP_AI_GROK_MODEL="grok-4"
./install.sh --install-grok
```
For non-browser / CI sessions, export an API key before launching `warpai-grok`:
```bash
export XAI_API_KEY="xai-..."
```
If your Grok binary is not on PATH, set `WARP_AI_GROK_BIN` to the exact executable path.
### `--install-codex` setup example
Codex is optional and intentionally explicit. Choose one of these installer options before running `--install-codex`:
```bash
export WARP_AI_CODEX_INSTALL_COMMAND="npm install -g @openai/codex"
# Or:
export WARP_AI_CODEX_NPM_PACKAGE="@openai/codex"
# Optional: if codex is not on PATH, set the explicit executable path:
export WARP_AI_CODEX_BIN="/full/path/to/codex"
./install.sh --install-codex
```
## 🧪 Quick Start
```bash
warpai-doctor
warpai-grok "Summarize Warp permission behavior for macOS"
warpai-search "latest AI developments"
warpai-calc "1024 * 768 / 2"
warpai-image /absolute/path/to/image.png "Describe this image"
warpai-cmd split right
warpai-cmd split down
warpai-cmd close panel
warpai-cmd screenshot
warpai-cmd screenshot /tmp/warp-shot.png
warpai-permissions
warpai-layout-install
warpai-open toolkit
warpai-open doctor
warpai-codex "Summarize the next safe rollout steps for this repo"
```
## 🧠 Startup Experience
When loaded in Warp, the toolkit can show a lightweight startup banner with recent session context.
That startup behavior is intentionally tuned to be friendlier now:
- **Warp-first** by default
- **rate-limited** so quick pane and tab creation does not keep replaying the full banner
- **quieter outside Warp**, unless you explicitly opt in with:
```bash
export WARP_AI_ALWAYS_SHOW_WELCOME=1
```
## 🔐 macOS Permissions
For `warpai-cmd`, macOS may require:
- `Accessibility`
- `Automation`
- `Screen Recording`
The suite can **open the correct System Settings panes**, but macOS still requires **manual user approval** for those permissions.
Use:
```bash
warpai-permissions
```
if you want to reopen those panes later.
## 📋 Behavior Notes
- `warpai-cmd` assumes the current default Warp macOS pane shortcuts.
- If you remap Warp shortcuts, pane automation may stop matching your setup.
- Warp Tab Configs are a better fit for repeatable workspace layouts than simulated keystrokes.
- Gemini/Grok-free search falls back to DuckDuckGo Instant Answer and may return sparse summaries.
- Image analysis depends on a locally installed Ollama multimodal model.
- Codex commands depend on your local Codex auth/session and network access.
- `warpai-grok` runs headless Grok prompts and supports `WARP_AI_GROK_MODEL`.
## 🚀 Tab Configs
The suite now includes a native bridge into Warp Tab Configs.
Run:
```bash
warpai-layout-install
```
This installs two Tab Config files into:
```text
~/.warp/tab_configs
```
or, on Warp Preview:
```text
~/.warp-preview/tab_configs
```
- **Superwarp Toolkit**
Opens a practical toolkit workspace with the install directory and log directory ready to go.
- **Superwarp Doctor**
Opens a doctor-oriented workspace with a pane that runs `warpai-doctor` on startup.
You can open them from Warp's `+` menu or from the terminal:
```bash
warpai-open toolkit
warpai-open doctor
```
This is the cleanest way to make repeatable Warp sessions feel native on macOS without relying on brittle pane-keystroke simulation alone.
The helper auto-detects Warp Preview when `~/.warp-preview` exists and `~/.warp` does not, and it switches the URI scheme to `warppreview://...` in that case.
## 🦾 Warp-Native Superwarp Layer
This repository now includes a real **Warp-native layer** on top of the shell toolkit.
When you open the repo root in Warp, it can discover:
- **repo-local skills** under `.agents/skills/`
- **repo-local workflows** under `.warp/workflows/`
That means this project is not only a set of commands you install into your shell. It is also becoming a **Warp-aware workspace toolkit** that teaches the agent how to maintain, validate, and troubleshoot the suite from inside Warp itself.
### Included skills
- **`suite-maintainer`**
Keeps changes aligned with the repo boundary, docs, tests, and macOS-only scope.
- **`warp-permission-doctor`**
Helps diagnose pane split, close-panel, and screenshot issues tied to macOS permissions.
- **`usage-session-analyst`**
Interprets local usage state from Warp's plist snapshot, SQLite history, and toolkit logs.
- **`tab-config-installer`**
Installs or opens the bundled Superwarp Tab Configs for a native Warp session layout.
- **`codex-command-assistant`**
Suggests repo-aware coding strategies, risk checks, and decomposition steps via Codex.
### Included workflows
- **`Suite Health Check`**
Runs `warpai-doctor` plus the smoke suite.
- **`Permission Readiness Check`**
Checks automation and screenshot readiness, with an option to reopen the relevant permission panes.
- **`Usage Snapshot`**
Shows both the quick quota summary and the deeper local usage report.
- **`Install Suite Safely`**
Runs the installer with optional extra flags.
- **`Install Uninstall Validation`**
Proves the installer and uninstall path in a temporary `HOME`.
- **`Install Tab Configs`**
Copies the bundled Tab Config files into Warp's user-level tab configuration directory.
- **`Bootstrap Superwarp`**
Installs Tab Configs, runs the doctor, and prints the current quick usage snapshot in one shot.
- **`Codex Assistant`**
Sends a structured prompt to `warpai-codex` for local rollout guidance and triage.
In practice, this is the core of the Superwarp idea: Warp-native skills for agent behavior, Warp-native workflows for repeatable actions, and shell helpers for real local execution.
## ⚠️ Limitations
- `zsh` is the supported startup shell.
- GUI automation depends on a live Warp window and granted macOS permissions.
- `--install-gemini`, `--install-grok`, and `--install-ollama` make real system-wide dependency changes.
- `--install-codex` is optional and requires an explicit install command or npm package export.
- This repo does **not** directly hook into Warp’s internal agent runtime or automatically capture Warp AI prompts and responses.
- `warpai-codex` needs an authenticated Codex session and valid CLI credentials.
## 🧭 Rename Notes (2026-06-04)
This repository is now branded as **Superwarp Toolkit** and the local folder is now:
- `superwarp-toolkit`
For users from older local checkouts:
- The rename is intentionally lightweight: install paths are now centered on `~/.superwarp-toolkit`, with `~/.warp-ai-enhancement` migration support for existing users.
- Existing installations continue to work.
- If you want the local checkout to reflect the new name, clone or `cd` from the new folder path shown in the instructions below.
- Remote is now: `https://github.com/lioneltchami/superwarp-toolkit`
## ✅ Validation Status
This macOS branch has been checked across:
- installer behavior
- uninstall behavior
- doctor command behavior
- smoke tests
- real Warp startup loading
- live pane splitting
- live screenshot capture
It does not mean every machine is identical, but it does mean the branch is in much better shape than a raw concept repo.
## 🧼 Uninstall
```bash
./uninstall.sh
```
That removes:
- the managed loader block from `~/.zshrc`
- the installed suite in `~/.superwarp-toolkit`
Logs are intentionally left behind at `~/Library/Logs/WarpAI` unless you remove them manually.
## 🔮 Future Improvements
- **Better `warpai-cmd` diagnostics** with more specific permission failure guidance
- **More Tab Config variants** tuned for different kinds of setups
- **Optional model bootstrap helpers** for recommended Ollama vision models
- **Public maintenance workflow** with a release checklist and GitHub Actions smoke job
- **Cleaner upgrade flow** for existing installs when installer behavior changes
- **More first-run guidance** for people setting up Gemini CLI and Ollama on a fresh Mac
- **Codex workflow presets** for command safety checks, execution planning, and staged rollback guidance
For repo-local agent guidance, see [WARP.md](./WARP.md).
## 🤝 Contributing
If you want to extend it, the most natural areas are:
- better Warp-native workflow support
- richer doctor diagnostics
- cleaner optional dependency installation
- sharper local AI ergonomics
- better release automation
## 📜 License
MIT. See [LICENSE](./LICENSE).