\n\n---\n\n## What is IronCode?\n\nIronCode is a **high-performance CLI AI coding agent** โ a fork of [OpenCode](https://github.com/anomalyco/opencode) that runs entirely on your machine. It rewrites performance-critical components in Rust for dramatically improved speed and memory efficiency.\n\n### Key Features\n\n- โจ๏ธ **CLI-First** โ Powerful terminal UI optimized for keyboard-driven workflows\n- ๐ฑ **Narrow Terminal Support** โ Responsive TUI adapts to small screens (SSH via Termius, tmux panes, 60-col terminals)\n- ๐ **Multi-Account Round-Robin** โ Connect multiple API keys per provider for automatic load balancing\n- ๐ฏ **Git Source Control** โ Stage, commit, diff, push without leaving the TUI\n- ๐ **Code Changes Panel** โ Diff viewer with inline comments and hunk revert\n- ๐ **Local Code Search** โ BM25 + tree-sitter semantic search, offline, zero latency\n- ๐ฌ **Chat Integrations** โ Control IronCode from Telegram, Discord, or Slack\n- ๐ป **Built-in Terminal** โ Fish-style autosuggest, tab completion, syntax highlighting\n- ๐ **External Editor** โ Opens `$EDITOR`/nvim with auto-install if missing\n- ๐งฉ **Built-in Skills** โ 21 opinionated slash commands: plan review, code review, QA (web + API), ship, retro, caveman token compression, and more\n- ๐ก๏ธ **Security** โ Prompt injection detection blocks malicious websites from manipulating the AI\n- ๐ **Auto-Compact on Overflow** โ When context limit is hit, automatically compacts conversation and retries\n- ๐ **100% Local** โ No cloud services, works completely offline\n- โก **Blazing Fast** โ Native Rust for all performance-critical operations\n\n---\n\n## Security\n\nIronCode includes built-in protection against prompt injection attacks when fetching external web content:\n\n- **Prompt Injection Detection** โ Automatically scans fetched website content for malicious prompts attempting to manipulate the AI\n- **Pattern Recognition** โ Detects common attack vectors including instruction manipulation, role changes, context escapes, and delimiter-based attacks\n- **Safe Blocking** โ Blocks suspicious content with clear error messages while allowing legitimate websites through\n- **Zero False Positives** โ Carefully tuned to avoid blocking normal web content about security topics\n\nWhen the WebFetch tool encounters a website with potential prompt injection content, it will block the request and show an error like: `Content blocked: prompt injection detected - instruction manipulation`\n\n---\n\n## Installation\n\n### NPM (Recommended)\n\n```bash\nnpm install -g ironcode-ai\n```\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew tap KSD-CO/tap https://github.com/KSD-CO/homebrew-tap\nbrew install ironcode\n```\n\n### Direct Download\n\nPre-built binaries for macOS (x64/arm64), Linux (x64/arm64), and Windows are available on [GitHub Releases](https://github.com/KSD-CO/IronCode/releases).\n\n---\n\n## Usage\n\n```bash\n# Start in current directory\nironcode\n\n# With a specific model\nironcode --model anthropic/claude-sonnet-4\n\n# Custom memory limit (default: 300MB)\nironcode --max-memory 500\n```\n\nSet your API key:\n\n```bash\nexport ANTHROPIC_API_KEY=\"your-key-here\"\n# or authenticate interactively:\nironcode auth login\n```\n\n### Key Commands\n\n| Command | Description |\n| ----------- | -------------------------------------- |\n| `/git` | Open Git source control panel |\n| `/terminal` | Open built-in terminal |\n| `/editor` | Open file in `$EDITOR` |\n| `/review` | Open code changes panel |\n| `/init` | Create `AGENTS.md` for the project |\n| `Tab` | Switch between agents (build / plan) |\n| `Ctrl+T` | Cycle model variants (low/medium/high) |\n\n### Model Variants\n\nPress **`Ctrl+T`** to cycle between variants:\n\n| Variant | Description |\n| ------------- | -------------------------------------------- |\n| `low` | Faster responses, lower cost |\n| `medium` | Balanced performance and quality |\n| `high ๐ง ` | Best quality with thinking enabled (default) |\n| `thinking ๐ง ` | Extended reasoning for complex problems |\n\n---\n\n## Skills\n\nIronCode ships with **21 built-in skill workflows** โ opinionated slash commands that switch the agent into a specialist mode. Instead of one generic assistant, you get: founder, tech lead, TDD coach, debugger, paranoid reviewer, release engineer, QA tester, security auditor, technical writer, engineering manager, and a token-compression mode that cuts AI response costs by ~75%.\n\n| Skill | Mode | What it does |\n| ------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `/ceo-review` | Founder / CEO | Rethink the problem. Find the 10-star product hiding inside the request. Three modes: Scope Expansion, Hold Scope, Scope Reduction. |\n| `/eng-review` | Tech lead | Lock in architecture, data flow, failure modes, edge cases, and test matrix. |\n| `/tdd` | Developer | RED-GREEN-REFACTOR: write a failing test, minimal code to pass, refactor. No production code without a failing test first. |\n| `/debug` | Debugger | Systematic 4-phase debugging: root cause investigation, pattern analysis, hypothesis testing, implementation. 3-fix rule escalates architectural problems. |\n| `/code-review` | Staff engineer | Find bugs that pass CI but blow up in production. Two-pass: critical + informational. |\n| `/security-review` | Security engineer | Scan the current branch diff for OWASP Top 10 vulnerabilities before shipping. Two-pass: critical + informational. Integrates Semgrep MCP when available. |\n| `/web-scan` | Penetration tester | Actively probe a live URL for misconfigs, exposed files, SSL issues, CORS, and info disclosure. Uses curl; optionally integrates Nikto and Nuclei. |\n| `/verify` | Gatekeeper | Run the command, read the output, then claim the result. Evidence before assertions โ no \"should work now.\" |\n| `/code-ship` | Release engineer | Merge, test, typecheck, review, changelog, bisectable commits, push, and PR โ one command. |\n| `/browse` | QA engineer | Headless Chromium via Playwright. Navigate, click, fill forms, screenshot, assert states, test responsive layouts. |\n| `/qa` | QA + fix engineer | Test web app, find bugs, fix with atomic commits, re-verify. Four modes: diff-aware, full, quick, regression. |\n| `/qa-only` | QA reporter | Report-only QA. Same methodology as `/qa` but never fixes anything. Pure bug report with health score. |\n| `/qa-api` | API tester | REST & GraphQL API testing. Auto-discovers routes, tests every endpoint with valid/invalid/edge-case payloads, auth, schema validation. |\n| `/document-release` | Technical writer | Post-ship doc update. Cross-references diff against README, ARCHITECTURE, CONTRIBUTING, CHANGELOG. |\n| `/retro` | Engineering manager | Team-aware weekly retro: commit analysis, session detection, per-person praise and growth areas. |\n\n### Caveman: Token Compression\n\nSix skills that cut AI response tokens by ~65โ75% โ useful when you want fast, terse answers or need to stretch a long session's context budget.\n\n| Skill | Trigger | What it does |\n| --- | --- | --- |\n| `/caveman` | `/caveman [lite\\|full\\|ultra\\|wenyan-*]` | Activate compressed response mode. Persists until \"stop caveman\". |\n| `/caveman-commit` | `/caveman-commit` | Generate terse commit messages. Conventional Commits format, โค50 char subject. |\n| `/caveman-review` | `/caveman-review` | One-line-per-finding PR review: `L42: ๐ด bug: user null. Add guard.` |\n| `/caveman:compress` | `/caveman:compress ` | Compress a `.md`/`.txt` file to caveman prose. Saves ~46% input tokens. Backs up original first. |\n| `/caveman-help` | `/caveman-help` | Reference card for all modes and commands. |\n| `/cavecrew` | `/cavecrew` | Decision guide for spawning compressed subagents โ keeps main context ~60% smaller per delegation. |\n\n**Intensity levels** (for `/caveman`):\n\n| Level | Style |\n| --- | --- |\n| `lite` | No filler/hedging. Full sentences. Professional but tight. |\n| `full` | Drop articles, fragments OK, short synonyms. Default. |\n| `ultra` | Abbreviate prose (DB/auth/req/res), arrows for causality (X โ Y). |\n| `wenyan-lite` | Semi-classical Chinese register. |\n| `wenyan-full` | Full ๆ่จๆ. 80โ90% character reduction. |\n| `wenyan-ultra` | Maximum classical compression. |\n\n**Configure default mode** in `~/.config/ironcode/ironcode.json`:\n\n```json\n{\n \"caveman\": { \"defaultMode\": \"ultra\" }\n}\n```\n\nOr via env var: `export CAVEMAN_DEFAULT_MODE=ultra`\n\n> Caveman automatically reverts to normal for security warnings and irreversible-action confirmations, then re-activates after.\n\n---\n\n### Workflow\n\n````\n/ceo-review โ /eng-review โ /tdd โ /debug (when stuck) โ /code-review โ /verify โ /code-ship โ /qa โ /document-release โ /retro\n product architecture build fix it right find bugs prove it land it verify update docs reflect\n```### Example\n\n````\n\nYou: I want to add voice message transcription.\n/ceo-review\n\nIronCode: \"Voice transcription\" is not the feature. The real job is\nletting users code from anywhere โ even when they can't type.\n\n A) SCOPE EXPANSION โ voice commands, image upload, voice-to-diff\n B) HOLD SCOPE โ transcription only, production-ready\n C) SCOPE REDUCTION โ bare minimum Whisper API call\n\nYou: B\n\nYou: /eng-review\nIronCode: [Architecture diagram, data flow, failure modes, test matrix]\n\nYou: /tdd\nIronCode: RED: Writing test for Whisper API transcription...\ntest(\"transcribes voice message to text\") โ FAIL โ\nGREEN: Implementing minimal WhisperService.transcribe()...\n34/34 tests pass. Committed.\n\nYou: /debug\nIronCode: Phase 1: Reading error โ \"ECONNRESET on Whisper API\"\nPhase 2: Working example found โ image upload uses retry\nPhase 3: Hypothesis โ no retry on transient network errors\nPhase 4: Test written, fix applied, verified. โ \n\nYou: /code-review\nIronCode: Missing .catch() on Whisper API โ unhandled rejection will crash the bot.\n\nYou: (fix it)\nYou: /verify\nIronCode: $ bun test โ 34/34 pass, exit 0\n$ bun check โ 0 errors\nAll verified. Ready to ship.\n\nYou: /code-ship\nIronCode: โ Format โ typecheck โ test โ push โ PR created\n\nYou: /qa http://localhost:3000\nIronCode: [Screenshots, console check, form test] All pages load. Voice flow works.\nHealth score: 92/100. 1 medium issue found and fixed.\n\nYou: /document-release\nIronCode: README.md: added voice transcription to features table.\nCHANGELOG.md: polished voice. All docs up to date.\n\nYou: /retro\nIronCode: Week of Mar 10: 23 commits, 1.8k LOC, 42% tests, peak: 10pm\nYour biggest ship: voice transcription pipeline.\nStreak: 12 consecutive days.\n\n````\n\n### Security Skills\n\n`/security-review` and `/web-scan` work out of the box with no extra setup. Install optional tools below for deeper scanning.\n\n#### Optional: Semgrep MCP (static analysis for `/security-review`)\n\n[Semgrep](https://semgrep.dev) adds pattern-based static analysis on top of the built-in OWASP checklist โ detecting injection, hardcoded secrets, insecure APIs, and supply chain issues across 30+ languages.\n\n**1. Add to your ironcode config** (`~/.config/ironcode/ironcode.json` for global, or `ironcode.json` in your project):\n\n```json\n{\n \"mcp\": {\n \"semgrep\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"@modular-intelligence/semgrep\"]\n }\n }\n}\n```\n\nOptional โ add `SEMGREP_APP_TOKEN` to unlock Pro rules (free at semgrep.dev):\n\n```json\n{\n \"mcp\": {\n \"semgrep\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"@modular-intelligence/semgrep\"],\n \"environment\": {\n \"SEMGREP_APP_TOKEN\": \"your-token-here\"\n }\n }\n }\n}\n```\n\n**2. Install Semgrep CLI** (required by the MCP server):\n\n```bash\n# macOS\nbrew install semgrep\n\n# pip\npip install semgrep\n```\n\n**3. Restart IronCode**, then verify:\n\n```bash\nironcode mcp list\n# semgrep connected\n```\n\nWhen connected, `/security-review` runs three scans automatically โ SAST (diff-aware), secrets detection, and supply chain โ then merges all findings into the report under `[SEMGREP]`.\n\n> `npx` auto-downloads `@modular-intelligence/semgrep` on first run. The Semgrep CLI must be installed separately (step 2 above).\n\n#### Optional: Nikto + Nuclei (active scanning for `/web-scan`)\n\n`/web-scan` uses `curl` by default. Install Nikto and/or Nuclei for deeper active scanning:\n\n```bash\n# macOS\nbrew install nikto\nbrew install nuclei && nuclei -update-templates\n\n# Ubuntu / Debian\nsudo apt install nikto\ngo install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest\n```\n\nWhen installed, `/web-scan` detects them automatically and appends their findings to the report.\n\n---\n\n### Skills requiring Playwright MCP\n\nThe `/browse`, `/qa`, `/qa-only`, and `/qa-browse` skills control a real browser via [Playwright MCP](https://github.com/microsoft/playwright-mcp). Set it up once before using them.\n\n**1. Add to your ironcode config** (`~/.ironcode/config.json` for global, or `ironcode.json` in your project):\n\n```json\n{\n \"mcp\": {\n \"playwright\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"@playwright/mcp@latest\"]\n }\n }\n}\n```\n\n**2. Restart IronCode**, then verify:\n\n```bash\nironcode mcp list\n# playwright connected\n```\n\n> `npx` auto-downloads `@playwright/mcp` on first run. Chromium is bundled โ no separate `playwright install` needed.\n\n---\n\n### Custom Skills\n\nCreate `.ironcode/skill//SKILL.md` with YAML frontmatter:\n\n```yaml\n---\nname: my-skill\ndescription: What this skill does and when to use it.\n---\n\n# Instructions for the agent\n\nYour prompt content here...\n````\n\nSkills are automatically discovered โ no restart needed.\n\n### Built-in Skill Auto-Install\n\nBuilt-in skills are embedded in the IronCode binary. On first run, they are extracted to `~/.ironcode/skill/`. If you customize a built-in skill (remove the `.builtin` marker), your version is preserved across upgrades.\n\n---\n\n## Agents\n\nSwitch between agents with `Tab`:\n\n| Agent | Access | Use for |\n| --------- | --------------- | ------------------------------------- |\n| **build** | Full read/write | Development, implementation (default) |\n| **plan** | Read-only | Analysis, code exploration, planning |\n\n---\n\n## Chat Integrations\n\nControl IronCode from your favorite messaging app โ send tasks from your phone, upload files, and get live streaming responses.\n\n### Telegram\n\n```bash\nbun install -g @ironcode-ai/telegram\nironcode-telegram setup\ncd your-project && ironcode-telegram\n```\n\n๐ธ Image upload ยท ๐ Document upload (20MB) ยท ๐ค Voice transcription ยท โก Streaming ยท `/new` `/sessions` `/info` `/init` `/diff`\n\nโ [`packages/telegram/README.md`](./packages/telegram/README.md)\n\n### Discord\n\n```bash\nbun install -g @ironcode-ai/discord\nironcode-discord setup\ncd your-project && ironcode-discord\n```\n\nโก Slash commands ยท ๐ธ File upload (25MB) ยท ๐ค Voice transcription ยท โจ Rich embeds ยท ๐ Reactions\n\nโ [`packages/discord/README.md`](./packages/discord/README.md)\n\n### Slack\n\n```bash\ncd packages/slack && bun dev\n```\n\n๐ฌ Threaded conversations ยท โก Real-time tool notifications ยท ๐ค Socket mode\n\nโ [`packages/slack/README.md`](./packages/slack/README.md)\n\n---\n\n## Performance\n\nNative Rust components via FFI:\n\n| Operation | Speedup | Notes |\n| --------------------- | ---------------------------------- | ------------------------------- |\n| PTY/Terminal | **15x faster** | Zero-copy ring buffer |\n| Edit Tool | **2โ6x faster** | 9 smart replacement strategies |\n| Bash Parser | **50โ100x faster** | Native tree-sitter vs WASM |\n| Archive extraction | **3โ5x faster** | s-zip streaming reader |\n| Grep search | **90โ99% less memory** | Streams GB-sized files |\n| File read | **1.5x faster, 99.7% less memory** | 64KB buffer + pre-allocation |\n| Git operations | **1.8x faster** | libgit2, no process spawning |\n| Permission evaluation | **Nร fewer FFI calls** | Entire ruleset in 1 native call |\n| File ignore matching | **Faster glob matching** | Compiled `globset` regex |\n\n---\n\n## Architecture\n\n```\nโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ\nโ IronCode CLI โ\nโ TypeScript + Bun โ\nโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค\nโ TUI โ Agents โ Skills โ Integrations โ\nโ โ build/ โ ceo/eng/ โ Telegram/ โ\nโ โ plan โ review/ โ Discord/Slack โ\nโ โ โ ship/qa โ โ\nโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค\nโ Native Performance Layer โ\nโ Rust via FFI โ\nโ PTY ยท Edit ยท Grep ยท Git ยท Bash ยท BM25 ยท โ\nโ Archive ยท Permission ยท Glob ยท Stats โ\nโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ\n```\n\n| Layer | Tech | Packages |\n| -------- | --------------------------- | ------------------------------- |\n| CLI/TUI | TypeScript + Bun | `packages/ironcode` |\n| Native | Rust FFI | `packages/ironcode/native/tool` |\n| Telegram | grammy + SDK + Groq Whisper | `@ironcode-ai/telegram` |\n| Discord | discord.js + SDK | `@ironcode-ai/discord` |\n| Slack | Bolt + SDK | `@ironcode-ai/slack` |\n\n---\n\n## Development\n\n**Requirements:** Bun 1.3.8+, Rust (stable), Git\n\n```bash\ngit clone https://github.com/KSD-CO/IronCode.git\ncd IronCode\nbun install\n\n# Build native Rust components\ncd packages/ironcode/native/tool && cargo build --release && cd ../../../..\n\n# Run in development mode\nbun dev\n```\n\n---\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md).\n\nAreas to help with: performance optimizations, bug fixes, documentation, new plugins, additional Rust components, new skills.\n\n---\n\n## Changelog\n\n\nv1.20.6 โ Auto-Compact Overflow + UI Fixes\n\n**Auto-compact on context overflow**\n- When model returns a token limit error (e.g. `\"prompt token count of 128195 exceeds the limit of 128000\"`), IronCode now automatically triggers compaction to summarize the conversation, then retries the request โ instead of showing an error\n- Covers Gemini, OpenAI, and generic `context length exceeded` error messages\n\n**File Explorer โ insert to prompt**\n- Selecting a file in the file explorer (`/explorer`) now inserts its path directly into the prompt and closes the dialog\n- Previously, selecting a file only toggled the preview panel with no action\n\n**Fix data: URI file attachments**\n- Files attached as `data:` URIs (screenshots, voice messages, documents sent via Telegram/Discord) no longer fail with `AI_DownloadError: URL scheme must be http or https`\n- The `data:` prefix is stripped before passing to the AI SDK\n\n\n\n\nv1.20.5 โ Narrow Terminal / Mobile SSH Support\n\nResponsive TUI that adapts when terminal width drops below 60 columns โ usable over SSH from mobile clients (Termius, Blink Shell, JuiceSSH).\n\n**Home screen**\n- Logo hidden on narrow terminals to save vertical space\n- CPU/Memory stats bar and tips hidden โ only prompt is shown\n\n**Session header**\n- CPU/Memory bars and version number hidden โ only session title and token context/cost shown\n\n**Session footer**\n- Directory path truncated to last folder name + branch (e.g. `ironcode:feature/my-branch ~4`)\n- `/status` hint hidden\n\n**Prompt area**\n- Keyboard hint bar (`variants`, `agents`, `commands`, `changes`) hidden\n- `esc interrupt` text fixed to never wrap (`wrapMode=\"none\"`)\n- Provider name hidden from model info row โ only agent + model name + variant shown\n\n\n\n\nv1.18.0 โ Chat Integrations Upgrade\n\n- **Discord Bot** โ Full-featured Discord integration with slash commands, rich embeds, file upload (25MB)\n- **Telegram Enhancement** โ Image upload, document upload, media groups, voice transcription via Groq Whisper\n- **Packages:** `@ironcode-ai/telegram`, `@ironcode-ai/discord`, `@ironcode-ai/slack`\n\n\n\n\nv1.17.6 โ AI SDK v6 ModelRef Migration\n\n- Migrated model references from object format to string-based `ModelRef` format (`\"provider:model\"`)\n- Updated 24 files including session handling, compaction, summary, task/plan tools\n- Zero breaking changes for end users\n\n\n\n\nv1.17.5 โ Voice Message Support\n\n- Voice messages in Telegram bot โ auto-transcribed via Groq Whisper\n- BM25 improvements โ retain method-prefix tokens for more accurate code search\n\n\n\n\nv1.17.3 โ Rust Rule Engine Migration\n\n- Permission rule engine migrated to Rust โ entire ruleset in 1 FFI call\n- File ignore matching migrated to Rust using `globset` compiled regex\n- Removed dead code (`permission/arity.ts`)\n\n\n\n\nv1.17.2 โ Telegram Enhancement\n\n- `/init` command โ generate `AGENTS.md` from Telegram\n- `/diff` โ stream changed files\n- `/sessions` โ inline switch buttons\n\n\n\n\nv1.17.0 โ AI SDK v6\n\n- Upgraded to AI SDK v6 with full support for new providers\n- Improved terminal UX\n\n\n","readmeFilename":"README.md"}
![\"Build](\"https://img.shields.io/github/actions/workflow/status/KSD-CO/IronCode/publish.yml?style=flat-square&branch=dev\")
\n ![\"npm](\"https://img.shields.io/npm/v/ironcode-ai?style=flat-square\")
\n ![\"Website\"](\"https://img.shields.io/badge/website-ironcode.cloud-brightgreen?style=flat-square\"){kind=icon}
\n