GitHub - KSD-CO/IronCode: IronCode is a high-performance fork of OpenCode - an AI coding agent that runs entirely on your machine. This fork removes cloud dependencies, focuses on core functionality, and rewrites performance-critical components in Rust for dramatically improved speed and efficiency.


@@@  @@@@@@@    @@@@@@   @@@  @@@      @@@@@@@   @@@@@@   @@@@@@@   @@@@@@@@
@@@  @@@@@@@@  @@@@@@@@  @@@@ @@@     @@@@@@@@  @@@@@@@@  @@@@@@@@  @@@@@@@@
@@!  @@!  @@@  @@!  @@@  @@!@!@@@     !@@       @@!  @@@  @@!  @@@  @@!
!@!  !@!  @!@  !@!  @!@  !@!!@!@!     !@!       !@!  @!@  !@!  @!@  !@!
!!@  @!@!!@!   @!@  !@!  @!@ !!@!     !@!       @!@  !@!  @!@  !@!  @!!!:!
!!!  !!@!@!    !@!  !!!  !@!  !!!     !!!       !@!  !!!  !@!  !!!  !!!!!:
!!:  !!: :!!   !!:  !!!  !!:  !!!     :!!       !!:  !!!  !!:  !!!  !!:
:!:  :!:  !:!  :!:  !:!  :!:  !:!     :!:       :!:  !:!  :!:  !:!  :!:
 ::  ::   :::  ::::: ::   ::   ::      ::: :::  ::::: ::   :::: ::   :: ::::
:     :   : :   : :  :   ::    :       :: :: :   : :  :   :: :  :   : :: ::

High-performance CLI AI coding agent

What is IronCode?

IronCode is a high-performance CLI AI coding agent — a fork of OpenCode that runs entirely on your machine. It rewrites performance-critical components in Rust for dramatically improved speed and memory efficiency.

Key Features

⌨️ CLI-First — Powerful terminal UI optimized for keyboard-driven workflows
📱 Narrow Terminal Support — Responsive TUI adapts to small screens (SSH via Termius, tmux panes, 60-col terminals)
🔀 Multi-Account Round-Robin — Connect multiple API keys per provider for automatic load balancing
🎯 Git Source Control — Stage, commit, diff, push without leaving the TUI
🔍 Code Changes Panel — Diff viewer with inline comments and hunk revert
🔎 Local Code Search — BM25 + tree-sitter semantic search, offline, zero latency
💬 Chat Integrations — Control IronCode from Telegram, Discord, or Slack
💻 Built-in Terminal — Fish-style autosuggest, tab completion, syntax highlighting
📝 External Editor — Opens $EDITOR/nvim with auto-install if missing
🧩 Built-in Skills — 21 opinionated slash commands: plan review, code review, QA (web + API), ship, retro, caveman token compression, and more
🛡️ Security — Prompt injection detection blocks malicious websites from manipulating the AI
🔄 Auto-Compact on Overflow — When context limit is hit, automatically compacts conversation and retries
🏠 100% Local — No cloud services, works completely offline
⚡ Blazing Fast — Native Rust for all performance-critical operations

Security

IronCode includes built-in protection against prompt injection attacks when fetching external web content:

Prompt Injection Detection — Automatically scans fetched website content for malicious prompts attempting to manipulate the AI
Pattern Recognition — Detects common attack vectors including instruction manipulation, role changes, context escapes, and delimiter-based attacks
Safe Blocking — Blocks suspicious content with clear error messages while allowing legitimate websites through
Zero False Positives — Carefully tuned to avoid blocking normal web content about security topics

When 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

Installation

NPM (Recommended)

npm install -g ironcode-ai

Homebrew (macOS/Linux)

brew tap KSD-CO/tap https://github.com/KSD-CO/homebrew-tap
brew install ironcode

Direct Download

Pre-built binaries for macOS (x64/arm64), Linux (x64/arm64), and Windows are available on GitHub Releases.

Usage

# Start in current directory
ironcode

# With a specific model
ironcode --model anthropic/claude-sonnet-4

# Custom memory limit (default: 300MB)
ironcode --max-memory 500

Set your API key:

export ANTHROPIC_API_KEY="your-key-here"
# or authenticate interactively:
ironcode auth login

Key Commands

Command	Description
`/git`	Open Git source control panel
`/terminal`	Open built-in terminal
`/editor`	Open file in `$EDITOR`
`/review`	Open code changes panel
`/init`	Create `AGENTS.md` for the project
`Tab`	Switch between agents (build / plan)
`Ctrl+T`	Cycle model variants (low/medium/high)

Model Variants

Press Ctrl+T to cycle between variants:

Variant	Description
`low`	Faster responses, lower cost
`medium`	Balanced performance and quality
`high 🧠`	Best quality with thinking enabled (default)
`thinking 🧠`	Extended reasoning for complex problems

Skills

IronCode 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%.

Skill	Mode	What it does
`/ceo-review`	Founder / CEO	Rethink the problem. Find the 10-star product hiding inside the request. Three modes: Scope Expansion, Hold Scope, Scope Reduction.
`/eng-review`	Tech lead	Lock in architecture, data flow, failure modes, edge cases, and test matrix.
`/tdd`	Developer	RED-GREEN-REFACTOR: write a failing test, minimal code to pass, refactor. No production code without a failing test first.
`/debug`	Debugger	Systematic 4-phase debugging: root cause investigation, pattern analysis, hypothesis testing, implementation. 3-fix rule escalates architectural problems.
`/code-review`	Staff engineer	Find bugs that pass CI but blow up in production. Two-pass: critical + informational.
`/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.
`/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.
`/verify`	Gatekeeper	Run the command, read the output, then claim the result. Evidence before assertions — no "should work now."
`/code-ship`	Release engineer	Merge, test, typecheck, review, changelog, bisectable commits, push, and PR — one command.
`/browse`	QA engineer	Headless Chromium via Playwright. Navigate, click, fill forms, screenshot, assert states, test responsive layouts.
`/qa`	QA + fix engineer	Test web app, find bugs, fix with atomic commits, re-verify. Four modes: diff-aware, full, quick, regression.
`/qa-only`	QA reporter	Report-only QA. Same methodology as `/qa` but never fixes anything. Pure bug report with health score.
`/qa-api`	API tester	REST & GraphQL API testing. Auto-discovers routes, tests every endpoint with valid/invalid/edge-case payloads, auth, schema validation.
`/document-release`	Technical writer	Post-ship doc update. Cross-references diff against README, ARCHITECTURE, CONTRIBUTING, CHANGELOG.
`/retro`	Engineering manager	Team-aware weekly retro: commit analysis, session detection, per-person praise and growth areas.

Caveman: Token Compression

Six 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.

Skill	Trigger	What it does
`/caveman`	`/caveman [lite\|full\|ultra\|wenyan-*]`	Activate compressed response mode. Persists until "stop caveman".
`/caveman-commit`	`/caveman-commit`	Generate terse commit messages. Conventional Commits format, ≤50 char subject.
`/caveman-review`	`/caveman-review`	One-line-per-finding PR review: `L42: 🔴 bug: user null. Add guard.`
`/caveman:compress`	`/caveman:compress <file>`	Compress a `.md`/`.txt` file to caveman prose. Saves ~46% input tokens. Backs up original first.
`/caveman-help`	`/caveman-help`	Reference card for all modes and commands.
`/cavecrew`	`/cavecrew`	Decision guide for spawning compressed subagents — keeps main context ~60% smaller per delegation.

Intensity levels (for /caveman):

Level	Style
`lite`	No filler/hedging. Full sentences. Professional but tight.
`full`	Drop articles, fragments OK, short synonyms. Default.
`ultra`	Abbreviate prose (DB/auth/req/res), arrows for causality (X → Y).
`wenyan-lite`	Semi-classical Chinese register.
`wenyan-full`	Full 文言文. 80–90% character reduction.
`wenyan-ultra`	Maximum classical compression.

Configure default mode in ~/.config/ironcode/ironcode.json:

{
  "caveman": { "defaultMode": "ultra" }
}

Or via env var: export CAVEMAN_DEFAULT_MODE=ultra

Caveman automatically reverts to normal for security warnings and irreversible-action confirmations, then re-activates after.

Workflow

/ceo-review → /eng-review → /tdd → /debug (when stuck) → /code-review → /verify → /code-ship → /qa → /document-release → /retro
 product      architecture   build   fix it right         find bugs      prove it   land it      verify   update docs       reflect
```### Example

You: I want to add voice message transcription. /ceo-review

IronCode: "Voice transcription" is not the feature. The real job is letting users code from anywhere — even when they can't type.

      A) SCOPE EXPANSION — voice commands, image upload, voice-to-diff
      B) HOLD SCOPE — transcription only, production-ready
      C) SCOPE REDUCTION — bare minimum Whisper API call

You: B

You: /eng-review IronCode: [Architecture diagram, data flow, failure modes, test matrix]

You: /tdd IronCode: RED: Writing test for Whisper API transcription... test("transcribes voice message to text") → FAIL ✓ GREEN: Implementing minimal WhisperService.transcribe()... 34/34 tests pass. Committed.

You: /debug IronCode: Phase 1: Reading error — "ECONNRESET on Whisper API" Phase 2: Working example found — image upload uses retry Phase 3: Hypothesis — no retry on transient network errors Phase 4: Test written, fix applied, verified. ✅

You: /code-review IronCode: Missing .catch() on Whisper API — unhandled rejection will crash the bot.

You: (fix it) You: /verify IronCode: $ bun test → 34/34 pass, exit 0 $ bun check → 0 errors All verified. Ready to ship.

You: /code-ship IronCode: ✅ Format → typecheck → test → push → PR created

You: /qa http://localhost:3000 IronCode: [Screenshots, console check, form test] All pages load. Voice flow works. Health score: 92/100. 1 medium issue found and fixed.

You: /document-release IronCode: README.md: added voice transcription to features table. CHANGELOG.md: polished voice. All docs up to date.

You: /retro IronCode: Week of Mar 10: 23 commits, 1.8k LOC, 42% tests, peak: 10pm Your biggest ship: voice transcription pipeline. Streak: 12 consecutive days.


### Security Skills

`/security-review` and `/web-scan` work out of the box with no extra setup. Install optional tools below for deeper scanning.

#### Optional: Semgrep MCP (static analysis for `/security-review`)

[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.

**1. Add to your ironcode config** (`~/.config/ironcode/ironcode.json` for global, or `ironcode.json` in your project):

```json
{
  "mcp": {
    "semgrep": {
      "type": "local",
      "command": ["npx", "@modular-intelligence/semgrep"]
    }
  }
}
```

Optional — add `SEMGREP_APP_TOKEN` to unlock Pro rules (free at semgrep.dev):

```json
{
  "mcp": {
    "semgrep": {
      "type": "local",
      "command": ["npx", "@modular-intelligence/semgrep"],
      "environment": {
        "SEMGREP_APP_TOKEN": "your-token-here"
      }
    }
  }
}
```

**2. Install Semgrep CLI** (required by the MCP server):

```bash
# macOS
brew install semgrep

# pip
pip install semgrep
```

**3. Restart IronCode**, then verify:

```bash
ironcode mcp list
# semgrep  connected
```

When connected, `/security-review` runs three scans automatically — SAST (diff-aware), secrets detection, and supply chain — then merges all findings into the report under `[SEMGREP]`.

> `npx` auto-downloads `@modular-intelligence/semgrep` on first run. The Semgrep CLI must be installed separately (step 2 above).

#### Optional: Nikto + Nuclei (active scanning for `/web-scan`)

`/web-scan` uses `curl` by default. Install Nikto and/or Nuclei for deeper active scanning:

```bash
# macOS
brew install nikto
brew install nuclei && nuclei -update-templates

# Ubuntu / Debian
sudo apt install nikto
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
```

When installed, `/web-scan` detects them automatically and appends their findings to the report.

---

### Skills requiring Playwright MCP

The `/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.

**1. Add to your ironcode config** (`~/.ironcode/config.json` for global, or `ironcode.json` in your project):

```json
{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp@latest"]
    }
  }
}
```

**2. Restart IronCode**, then verify:

```bash
ironcode mcp list
# playwright  connected
```

> `npx` auto-downloads `@playwright/mcp` on first run. Chromium is bundled — no separate `playwright install` needed.

---

### Custom Skills

Create `.ironcode/skill/<name>/SKILL.md` with YAML frontmatter:

```yaml
---
name: my-skill
description: What this skill does and when to use it.
---

# Instructions for the agent

Your prompt content here...

Skills are automatically discovered — no restart needed.

Built-in Skill Auto-Install

Built-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.

Agents

Switch between agents with Tab:

Agent	Access	Use for
build	Full read/write	Development, implementation (default)
plan	Read-only	Analysis, code exploration, planning

Chat Integrations

Control IronCode from your favorite messaging app — send tasks from your phone, upload files, and get live streaming responses.

Telegram

bun install -g @ironcode-ai/telegram
ironcode-telegram setup
cd your-project && ironcode-telegram

📸 Image upload · 📄 Document upload (20MB) · 🎤 Voice transcription · ⚡ Streaming · /new /sessions /info /init /diff

→ packages/telegram/README.md

Discord

bun install -g @ironcode-ai/discord
ironcode-discord setup
cd your-project && ironcode-discord

⚡ Slash commands · 📸 File upload (25MB) · 🎤 Voice transcription · ✨ Rich embeds · 👍 Reactions

→ packages/discord/README.md

Slack

cd packages/slack && bun dev

💬 Threaded conversations · ⚡ Real-time tool notifications · 🤖 Socket mode

→ packages/slack/README.md

Performance

Native Rust components via FFI:

Operation	Speedup	Notes
PTY/Terminal	15x faster	Zero-copy ring buffer
Edit Tool	2–6x faster	9 smart replacement strategies
Bash Parser	50–100x faster	Native tree-sitter vs WASM
Archive extraction	3–5x faster	s-zip streaming reader
Grep search	90–99% less memory	Streams GB-sized files
File read	1.5x faster, 99.7% less memory	64KB buffer + pre-allocation
Git operations	1.8x faster	libgit2, no process spawning
Permission evaluation	N× fewer FFI calls	Entire ruleset in 1 native call
File ignore matching	Faster glob matching	Compiled `globset` regex

Architecture

┌──────────────────────────────────────────────┐
│                 IronCode CLI                  │
│              TypeScript + Bun                 │
├──────────────────────────────────────────────┤
│  TUI  │  Agents  │  Skills  │  Integrations  │
│       │ build/   │ ceo/eng/ │  Telegram/     │
│       │ plan     │ review/  │  Discord/Slack │
│       │          │ ship/qa  │                │
├──────────────────────────────────────────────┤
│           Native Performance Layer            │
│                Rust via FFI                    │
│  PTY · Edit · Grep · Git · Bash · BM25 ·     │
│  Archive · Permission · Glob · Stats          │
└──────────────────────────────────────────────┘

Layer	Tech	Packages
CLI/TUI	TypeScript + Bun	`packages/ironcode`
Native	Rust FFI	`packages/ironcode/native/tool`
Telegram	grammy + SDK + Groq Whisper	`@ironcode-ai/telegram`
Discord	discord.js + SDK	`@ironcode-ai/discord`
Slack	Bolt + SDK	`@ironcode-ai/slack`

Development

Requirements: Bun 1.3.8+, Rust (stable), Git

git clone https://github.com/KSD-CO/IronCode.git
cd IronCode
bun install

# Build native Rust components
cd packages/ironcode/native/tool && cargo build --release && cd ../../../..

# Run in development mode
bun dev

Contributing

Contributions welcome! See CONTRIBUTING.md.

Areas to help with: performance optimizations, bug fixes, documentation, new plugins, additional Rust components, new skills.

Changelog

v1.20.6 — Auto-Compact Overflow + UI Fixes

Auto-compact on context overflow

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
Covers Gemini, OpenAI, and generic context length exceeded error messages

File Explorer — insert to prompt

Selecting a file in the file explorer (/explorer) now inserts its path directly into the prompt and closes the dialog
Previously, selecting a file only toggled the preview panel with no action

Fix data: URI file attachments

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
The data: prefix is stripped before passing to the AI SDK

v1.20.5 — Narrow Terminal / Mobile SSH Support

Responsive TUI that adapts when terminal width drops below 60 columns — usable over SSH from mobile clients (Termius, Blink Shell, JuiceSSH).

Home screen

Logo hidden on narrow terminals to save vertical space
CPU/Memory stats bar and tips hidden — only prompt is shown

Session header

CPU/Memory bars and version number hidden — only session title and token context/cost shown

Session footer

Directory path truncated to last folder name + branch (e.g. ironcode:feature/my-branch ~4)
/status hint hidden

Prompt area

Keyboard hint bar (variants, agents, commands, changes) hidden
esc interrupt text fixed to never wrap (wrapMode="none")
Provider name hidden from model info row — only agent + model name + variant shown

v1.18.0 — Chat Integrations Upgrade

Discord Bot — Full-featured Discord integration with slash commands, rich embeds, file upload (25MB)
Telegram Enhancement — Image upload, document upload, media groups, voice transcription via Groq Whisper
Packages: @ironcode-ai/telegram, @ironcode-ai/discord, @ironcode-ai/slack

v1.17.6 — AI SDK v6 ModelRef Migration

Migrated model references from object format to string-based ModelRef format ("provider:model")
Updated 24 files including session handling, compaction, summary, task/plan tools
Zero breaking changes for end users

v1.17.5 — Voice Message Support

Voice messages in Telegram bot — auto-transcribed via Groq Whisper
BM25 improvements — retain method-prefix tokens for more accurate code search

v1.17.3 — Rust Rule Engine Migration

Permission rule engine migrated to Rust — entire ruleset in 1 FFI call
File ignore matching migrated to Rust using globset compiled regex
Removed dead code (permission/arity.ts)

v1.17.2 — Telegram Enhancement

/init command — generate AGENTS.md from Telegram
/diff — stream changed files
/sessions — inline switch buttons

v1.17.0 — AI SDK v6

Upgraded to AI SDK v6 with full support for new providers
Improved terminal UX

Name		Name	Last commit message	Last commit date
.github		.github
.husky		.husky
.ironcode		.ironcode
.vscode		.vscode
nix		nix
packages		packages
patches		patches
script		script
themes		themes
.editorconfig		.editorconfig
.gitignore		.gitignore
.prettierignore		.prettierignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
RESOURCE-MONITORING.md		RESOURCE-MONITORING.md
SECURITY.md		SECURITY.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
flake.lock		flake.lock
flake.nix		flake.nix
global.d.ts		global.d.ts
install		install
install.md		install.md
package.json		package.json
run.sh		run.sh
test-session-create.ts		test-session-create.ts
tsconfig.json		tsconfig.json
turbo.json		turbo.json

Navigation Menu

Uh oh!

Repository files navigation

What is IronCode?

Key Features

Security

Installation

NPM (Recommended)

Homebrew (macOS/Linux)

Direct Download

Usage

Key Commands

Model Variants

Skills

Caveman: Token Compression

Workflow

Built-in Skill Auto-Install

Agents

Chat Integrations

Telegram

Discord

Slack

Performance

Architecture

Development

Contributing

Changelog

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

What is IronCode?

Key Features

Security

Installation

NPM (Recommended)

Homebrew (macOS/Linux)

Direct Download

Usage

Key Commands

Model Variants

Skills

Caveman: Token Compression

Workflow

Built-in Skill Auto-Install

Agents

Chat Integrations

Telegram

Discord

Slack

Performance

Architecture

Development

Contributing

Changelog

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages