{"id":50578234,"url":"https://github.com/lioneltchami/superwarp-toolkit","last_synced_at":"2026-06-05T00:01:10.229Z","repository":{"id":362542432,"uuid":"1259619833","full_name":"lioneltchami/superwarp-toolkit","owner":"lioneltchami","description":"Superwarp Toolkit: macOS-first Warp terminal toolkit for install, permissions, tab configs, and workflow automation to make Warp smarter.","archived":false,"fork":false,"pushed_at":"2026-06-04T18:20:25.000Z","size":84,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T21:10:33.336Z","etag":null,"topics":["ai","ai-tools","automation","cli","developer-tools","macos","productivity","shell","terminal","toolkit","warp","warp-terminal","workflows","zsh"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lioneltchami.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-04T17:31:22.000Z","updated_at":"2026-06-04T20:16:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lioneltchami/superwarp-toolkit","commit_stats":null,"previous_names":["lioneltchami/warp-ai-enhancement-suite"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/lioneltchami/superwarp-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lioneltchami%2Fsuperwarp-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lioneltchami%2Fsuperwarp-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lioneltchami%2Fsuperwarp-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lioneltchami%2Fsuperwarp-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lioneltchami","download_url":"https://codeload.github.com/lioneltchami/superwarp-toolkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lioneltchami%2Fsuperwarp-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33924832,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-tools","automation","cli","developer-tools","macos","productivity","shell","terminal","toolkit","warp","warp-terminal","workflows","zsh"],"created_at":"2026-06-05T00:00:56.409Z","updated_at":"2026-06-05T00:01:10.220Z","avatar_url":"https://github.com/lioneltchami.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Superwarp Toolkit\n**A polished Warp terminal toolkit for macOS with install, uninstall, doctor, permissions, search, automation, and local AI helpers.**\n\n![Status](https://img.shields.io/badge/Status-macOS%20Ready-brightgreen)\n![AI Collaboration](https://img.shields.io/badge/AI%20Collaboration-Claude%20%2B%20Gemini%20%2B%20Grok%20%2B%20Codex%20%2B%20Ollama-blue)\n![Platform](https://img.shields.io/badge/Platform-macOS-lightgrey)\n![Shell](https://img.shields.io/badge/Shell-zsh-black)\n![License](https://img.shields.io/badge/License-MIT-success)\n![CI](https://github.com/lioneltchami/superwarp-toolkit/actions/workflows/ci.yml/badge.svg)\n\n\u003e **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.\n\n## 🎯 What This Is\n\nSuperwarp Toolkit is a **macOS-first helper layer for the Warp terminal**.\n\nIt gives you:\n\n- **⚡ Faster setup** with an installer, uninstall script, and permission helper\n- **🩺 Better trust** with `warpai-doctor` for runtime checks\n- **🧠 Useful terminal helpers** for calculation, search, image prompting, and Warp pane control\n- **📝 Lightweight session logging** and startup context\n- **🎛️ Optional AI integrations** through Gemini CLI, Grok CLI, Codex CLI, and Ollama\n\nThis 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.\n\n## ✨ Highlights\n\n- **`install.sh`**  \n  Installs the suite into `~/.superwarp-toolkit` and wires it into `~/.zshrc`.\n  Legacy `~/.warp-ai-enhancement` installs are migrated automatically for compatibility.\n\n- **`uninstall.sh`**  \n  Cleanly removes the managed loader block and installed toolkit files.\n\n- **`warpai-doctor`**  \n  Checks shell loading, key binaries, and likely GUI permission readiness.\n\n- **`warpai-permissions`**  \n  Reopens the relevant macOS Privacy \u0026 Security panes for:\n  - `Accessibility`\n  - `Automation`\n  - `Screen Recording`\n\n- **`warpai-search`**  \n  Uses Gemini CLI when available, then Grok CLI, then DuckDuckGo when web tools are unavailable.\n\n- **`warpai-grok`**  \n  Directs a prompt to Grok for headless research or coding-style assistance.\n\n- **`warpai-calc`**  \n  Uses a restricted AST-based numeric evaluator rather than unsafe `eval`.\n\n- **`warpai-image`**  \n  Runs a local Ollama multimodal model against an image path and prompt.\n\n- **`warpai-cmd`**  \n  Supports:\n  - `split right`\n  - `split down`\n  - `close panel`\n  - `screenshot`\n\n- **`warpai-usage` / `warpai-quick`**\n  Read-only Warp usage helpers that summarize local SQLite history and the current quota snapshot from Warp's preference plist.\n\n- **`warpai-layout-install`**\n  Installs bundled Warp Tab Configs into the active Warp tab config directory for a more native session bring-up flow.\n\n- **`warpai-open`**\n  Opens the bundled Superwarp Tab Configs or the macOS permission panes.\n\n- **`warpai-codex`**\n  Sends prompts to your local Codex CLI for faster triage, planning, and repo-aware suggestions.\n\n## 🛠️ What’s Included\n\nCore files:\n\n- `install.sh`\n- `uninstall.sh`\n- `warp-ai-enhancement-profile.zsh`\n- `scripts/warp-ai-toolkit.sh`\n- `tests/smoke.sh`\n- `WARP.md`\n- `.agents/skills/`\n- `.warp/workflows/`\n\nCore commands:\n\n- `warpai-search`\n- `warpai-calc`\n- `warpai-image`\n- `warpai-cmd`\n- `warpai-doctor`\n- `warpai-permissions`\n- `warpai-usage`\n- `warpai-quick`\n- `warpai-layout-install`\n- `warpai-open`\n- `warpai-codex`\n- `warpai-grok`\n\nWarp-native repo assets:\n\n- `.agents/skills/suite-maintainer`\n- `.agents/skills/tab-config-installer`\n- `.agents/skills/warp-permission-doctor`\n- `.agents/skills/usage-session-analyst`\n- `.agents/skills/codex-command-assistant`\n- `.warp/workflows/suite-health-check.yaml`\n- `.warp/workflows/permission-readiness-check.yaml`\n- `.warp/workflows/usage-snapshot.yaml`\n- `.warp/workflows/install-suite-safely.yaml`\n- `.warp/workflows/install-uninstall-validation.yaml`\n- `.warp/workflows/install-tab-configs.yaml`\n- `.warp/workflows/bootstrap-superwarp.yaml`\n- `.warp/workflows/codex-assistant.yaml`\n\n## 🍏 Requirements\n\nRequired:\n\n- macOS\n- `zsh`\n- `bash`\n\nInstalled automatically if missing:\n\n- `python3`\n\nOptional companion tools:\n\n- **Gemini CLI** for better search and web-grounded responses\n- **Grok CLI** for direct headless prompts and alternative model routing\n- **Ollama** for local image analysis and multimodal workflows\n- **Codex CLI** for repo-aware agent-style breakdowns and coding suggestions\n\n## 🚀 Installation\n\n```bash\ngit clone https://github.com/lioneltchami/superwarp-toolkit.git\ncd superwarp-toolkit\nchmod +x ./install.sh\n./install.sh\n```\n\n### Use on another Mac\n\nOn another machine, run:\n\n```bash\ngit clone https://github.com/lioneltchami/superwarp-toolkit.git\ncd superwarp-toolkit\ngit checkout main\nchmod +x ./install.sh\n./install.sh\n```\n\nTo sync future updates later:\n\n```bash\ncd superwarp-toolkit\ngit pull origin main\n./install.sh --no-permission-panes\n```\n\n### Fresh machine verification\n\nAfter cloning + install, run:\n\n```bash\nsource ~/.zshrc\nwarpai-doctor\n```\n\nYou should see at least:\n\n- `python3: ok`\n- `toolkit file: ok`\n\nOptional quick smoke validation:\n\n```bash\n./tests/smoke.sh\n```\n\n### GitHub Actions validation\n\nThis repository runs GitHub Actions on every push and pull request to `main`:\n\n- syntax and shell checks\n- install smoke path (`./install.sh --no-permission-panes`)\n- full suite smoke tests (`./tests/smoke.sh`)\n\nIt helps keep the toolkit safe to clone on a fresh Mac and quickly update via git.\n\nIf you want a quick command-surface check:\n\n```bash\nwarpai-grok \"Summarize recent macOS automation gotchas\"\nwarpai-calc \"2 + 2\"\nwarpai-codex \"Summarize this session setup\"\n```\n\n`warpai-codex` is optional; run this command only after you have installed and authorized Codex.\n\nIf you're working inside Warp and want a practical, screen-by-screen setup flow, see:\n\n- [Warp Usage Guide](./WARP-INSIDE.md)\n\n## 🚀 Releases\n\nThis repo can publish GitHub Releases automatically when you push a version tag.\n\nUse:\n\n```bash\ngit tag v1.0.0\ngit push origin v1.0.0\n```\n\nThe release workflow will:\n\n- build a `tar.gz` artifact from the tagged commit\n- attach a `sha256` checksum file\n- generate release notes automatically\n\nThen users can install from source as usual:\n\n```bash\ngit clone https://github.com/lioneltchami/superwarp-toolkit.git\ncd superwarp-toolkit\ngit checkout \u003ctag-or-branch\u003e\n./install.sh\n```\n\nFor production-style sharing, you can also download the release asset directly from GitHub Releases.\n\n### What the installer does\n\n- installs the suite into `~/.superwarp-toolkit`\n- parses command-line flags and, when no optional install flags are passed, prompts for optional components\n- appends a managed loader block to `~/.zshrc`\n- installs `python3` automatically if needed\n- uses Homebrew for `python3`, and bootstraps Homebrew first if necessary\n- optionally installs Gemini CLI, Grok CLI, Ollama, and Codex\n- opens the relevant macOS Privacy \u0026 Security panes during interactive installs\n\n### Installer options\n\n```bash\n./install.sh --no-shell-hook\n./install.sh --no-permission-panes\n./install.sh --accept-defaults\nWARP_AI_ACCEPT_DEFAULTS=1 ./install.sh\n./install.sh --install-gemini\n./install.sh --install-ollama\n./install.sh --install-codex\n./install.sh --install-grok\n./install.sh --install-gemini --install-ollama\n./install.sh --install-codex --no-permission-panes\n./install.sh --install-grok --no-permission-panes\n./install.sh --accept-defaults --no-permission-panes\n./install.sh --help\n```\n\nIf you run `./install.sh` with no install flags in an interactive terminal, it now prompts for each optional component.\nPress Enter for “yes” to install or `n` to skip.\nIf 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`.\n\nYou can also control this via environment:\n\n```bash\nexport WARP_AI_ACCEPT_DEFAULTS=1\n./install.sh\n```\n\nAccepted values: `1`, `true`, `yes`, `on`, `enabled`.\n\nIf you want this behavior to persist for this repository, set it in:\n\n```text\n.superwarp-toolkit.env\n```\n\nOr point to a custom defaults file with `WARP_AI_INSTALL_DEFAULTS_FILE`:\n\n```bash\nexport WARP_AI_INSTALL_DEFAULTS_FILE=\"/path/to/custom.defaults\"\n./install.sh\n```\n\n### `--install-grok` setup example\n\nGrok is installed with the official xAI installer by default, or a custom command path:\n\n```bash\nexport WARP_AI_GROK_INSTALL_COMMAND=\"curl -fsSL https://x.ai/cli/install.sh | bash\"\nexport WARP_AI_GROK_BIN=\"grok\"\nexport WARP_AI_GROK_MODEL=\"grok-4\"\n\n./install.sh --install-grok\n```\n\nFor non-browser / CI sessions, export an API key before launching `warpai-grok`:\n\n```bash\nexport XAI_API_KEY=\"xai-...\"\n```\n\nIf your Grok binary is not on PATH, set `WARP_AI_GROK_BIN` to the exact executable path.\n\n### `--install-codex` setup example\n\nCodex is optional and intentionally explicit. Choose one of these installer options before running `--install-codex`:\n\n```bash\nexport WARP_AI_CODEX_INSTALL_COMMAND=\"npm install -g @openai/codex\"\n# Or:\nexport WARP_AI_CODEX_NPM_PACKAGE=\"@openai/codex\"\n\n# Optional: if codex is not on PATH, set the explicit executable path:\nexport WARP_AI_CODEX_BIN=\"/full/path/to/codex\"\n\n./install.sh --install-codex\n```\n\n## 🧪 Quick Start\n\n```bash\nwarpai-doctor\nwarpai-grok \"Summarize Warp permission behavior for macOS\"\nwarpai-search \"latest AI developments\"\nwarpai-calc \"1024 * 768 / 2\"\nwarpai-image /absolute/path/to/image.png \"Describe this image\"\nwarpai-cmd split right\nwarpai-cmd split down\nwarpai-cmd close panel\nwarpai-cmd screenshot\nwarpai-cmd screenshot /tmp/warp-shot.png\nwarpai-permissions\nwarpai-layout-install\nwarpai-open toolkit\nwarpai-open doctor\nwarpai-codex \"Summarize the next safe rollout steps for this repo\"\n```\n\n## 🧠 Startup Experience\n\nWhen loaded in Warp, the toolkit can show a lightweight startup banner with recent session context.\n\nThat startup behavior is intentionally tuned to be friendlier now:\n\n- **Warp-first** by default\n- **rate-limited** so quick pane and tab creation does not keep replaying the full banner\n- **quieter outside Warp**, unless you explicitly opt in with:\n\n```bash\nexport WARP_AI_ALWAYS_SHOW_WELCOME=1\n```\n\n## 🔐 macOS Permissions\n\nFor `warpai-cmd`, macOS may require:\n\n- `Accessibility`\n- `Automation`\n- `Screen Recording`\n\nThe suite can **open the correct System Settings panes**, but macOS still requires **manual user approval** for those permissions.\n\nUse:\n\n```bash\nwarpai-permissions\n```\n\nif you want to reopen those panes later.\n\n## 📋 Behavior Notes\n\n- `warpai-cmd` assumes the current default Warp macOS pane shortcuts.\n- If you remap Warp shortcuts, pane automation may stop matching your setup.\n- Warp Tab Configs are a better fit for repeatable workspace layouts than simulated keystrokes.\n- Gemini/Grok-free search falls back to DuckDuckGo Instant Answer and may return sparse summaries.\n- Image analysis depends on a locally installed Ollama multimodal model.\n- Codex commands depend on your local Codex auth/session and network access.\n- `warpai-grok` runs headless Grok prompts and supports `WARP_AI_GROK_MODEL`.\n\n## 🚀 Tab Configs\n\nThe suite now includes a native bridge into Warp Tab Configs.\n\nRun:\n\n```bash\nwarpai-layout-install\n```\n\nThis installs two Tab Config files into:\n\n```text\n~/.warp/tab_configs\n```\n\nor, on Warp Preview:\n\n```text\n~/.warp-preview/tab_configs\n```\n\n- **Superwarp Toolkit**\n  Opens a practical toolkit workspace with the install directory and log directory ready to go.\n\n- **Superwarp Doctor**\n  Opens a doctor-oriented workspace with a pane that runs `warpai-doctor` on startup.\n\nYou can open them from Warp's `+` menu or from the terminal:\n\n```bash\nwarpai-open toolkit\nwarpai-open doctor\n```\n\nThis is the cleanest way to make repeatable Warp sessions feel native on macOS without relying on brittle pane-keystroke simulation alone.\n\nThe helper auto-detects Warp Preview when `~/.warp-preview` exists and `~/.warp` does not, and it switches the URI scheme to `warppreview://...` in that case.\n\n## 🦾 Warp-Native Superwarp Layer\n\nThis repository now includes a real **Warp-native layer** on top of the shell toolkit.\n\nWhen you open the repo root in Warp, it can discover:\n\n- **repo-local skills** under `.agents/skills/`\n- **repo-local workflows** under `.warp/workflows/`\n\nThat 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.\n\n### Included skills\n\n- **`suite-maintainer`**\n  Keeps changes aligned with the repo boundary, docs, tests, and macOS-only scope.\n\n- **`warp-permission-doctor`**\n  Helps diagnose pane split, close-panel, and screenshot issues tied to macOS permissions.\n\n- **`usage-session-analyst`**\n  Interprets local usage state from Warp's plist snapshot, SQLite history, and toolkit logs.\n\n- **`tab-config-installer`**\n  Installs or opens the bundled Superwarp Tab Configs for a native Warp session layout.\n\n- **`codex-command-assistant`**\n  Suggests repo-aware coding strategies, risk checks, and decomposition steps via Codex.\n\n### Included workflows\n\n- **`Suite Health Check`**\n  Runs `warpai-doctor` plus the smoke suite.\n\n- **`Permission Readiness Check`**\n  Checks automation and screenshot readiness, with an option to reopen the relevant permission panes.\n\n- **`Usage Snapshot`**\n  Shows both the quick quota summary and the deeper local usage report.\n\n- **`Install Suite Safely`**\n  Runs the installer with optional extra flags.\n\n- **`Install Uninstall Validation`**\n  Proves the installer and uninstall path in a temporary `HOME`.\n\n- **`Install Tab Configs`**\n  Copies the bundled Tab Config files into Warp's user-level tab configuration directory.\n\n- **`Bootstrap Superwarp`**\n  Installs Tab Configs, runs the doctor, and prints the current quick usage snapshot in one shot.\n\n- **`Codex Assistant`**\n  Sends a structured prompt to `warpai-codex` for local rollout guidance and triage.\n\nIn 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.\n\n## ⚠️ Limitations\n\n- `zsh` is the supported startup shell.\n- GUI automation depends on a live Warp window and granted macOS permissions.\n- `--install-gemini`, `--install-grok`, and `--install-ollama` make real system-wide dependency changes.\n- `--install-codex` is optional and requires an explicit install command or npm package export.\n- This repo does **not** directly hook into Warp’s internal agent runtime or automatically capture Warp AI prompts and responses.\n- `warpai-codex` needs an authenticated Codex session and valid CLI credentials.\n\n## 🧭 Rename Notes (2026-06-04)\n\nThis repository is now branded as **Superwarp Toolkit** and the local folder is now:\n\n- `superwarp-toolkit`\n\nFor users from older local checkouts:\n\n- The rename is intentionally lightweight: install paths are now centered on `~/.superwarp-toolkit`, with `~/.warp-ai-enhancement` migration support for existing users.\n- Existing installations continue to work.\n- If you want the local checkout to reflect the new name, clone or `cd` from the new folder path shown in the instructions below.\n- Remote is now: `https://github.com/lioneltchami/superwarp-toolkit`\n\n## ✅ Validation Status\n\nThis macOS branch has been checked across:\n\n- installer behavior\n- uninstall behavior\n- doctor command behavior\n- smoke tests\n- real Warp startup loading\n- live pane splitting\n- live screenshot capture\n\nIt does not mean every machine is identical, but it does mean the branch is in much better shape than a raw concept repo.\n\n## 🧼 Uninstall\n\n```bash\n./uninstall.sh\n```\n\nThat removes:\n\n- the managed loader block from `~/.zshrc`\n- the installed suite in `~/.superwarp-toolkit`\n\nLogs are intentionally left behind at `~/Library/Logs/WarpAI` unless you remove them manually.\n\n## 🔮 Future Improvements\n\n- **Better `warpai-cmd` diagnostics** with more specific permission failure guidance\n- **More Tab Config variants** tuned for different kinds of setups\n- **Optional model bootstrap helpers** for recommended Ollama vision models\n- **Public maintenance workflow** with a release checklist and GitHub Actions smoke job\n- **Cleaner upgrade flow** for existing installs when installer behavior changes\n- **More first-run guidance** for people setting up Gemini CLI and Ollama on a fresh Mac\n- **Codex workflow presets** for command safety checks, execution planning, and staged rollback guidance\n\nFor repo-local agent guidance, see [WARP.md](./WARP.md).\n\n## 🤝 Contributing\n\nIf you want to extend it, the most natural areas are:\n\n- better Warp-native workflow support\n- richer doctor diagnostics\n- cleaner optional dependency installation\n- sharper local AI ergonomics\n- better release automation\n\n## 📜 License\n\nMIT. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flioneltchami%2Fsuperwarp-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flioneltchami%2Fsuperwarp-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flioneltchami%2Fsuperwarp-toolkit/lists"}