Documentation

Everything you need to know about using IronCode

Quick Start

Get up and running with IronCode in less than 5 minutes

1. Install IronCode (NPM)

$ npm install -g ironcode-ai

Or Install via Homebrew (macOS/Linux)

$ brew tap KSD-CO/tap
$ brew install ironcode

2. Set up your API key

$ export ANTHROPIC_API_KEY="your-key"

Get your API key from Anthropic Console

3. Start IronCode in your project

$ cd your-project
$ ironcode

Installation

NPM (Recommended)

# Install globally

$ npm install -g ironcode-ai

# Or use with npx (no installation)

$ npx ironcode-ai

Homebrew (macOS/Linux)

# Add the tap

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

# Install IronCode

$ brew install ironcode

# Verify installation

$ ironcode --version

Supported: macOS (Intel x64, Apple Silicon arm64), Linux (x64, arm64)

Direct Download (Standalone Binary)

Download pre-built executables from GitHub Releases

Linux (x64)

$ curl -L https://github.com/KSD-CO/IronCode/releases/latest/download/ironcode-linux-x64.tar.gz | tar xz
$ sudo mv ironcode /usr/local/bin/

macOS (Apple Silicon)

$ curl -L https://github.com/KSD-CO/IronCode/releases/latest/download/ironcode-darwin-arm64.tar.gz | tar xz
$ sudo mv ironcode /usr/local/bin/

Arch Linux (AUR)

Coming soon - AUR package will be available in the future

Usage

Basic Usage

# Start interactive session

$ ironcode

# Run with custom memory limit (default: 300MB)

$ ironcode --max-memory 500

# Run with specific model

$ ironcode --model anthropic/claude-sonnet-4

# Show version and help

$ ironcode --version
$ ironcode --help

Configuration

IronCode requires API keys for AI models. Set them as environment variables:

# Anthropic Claude (recommended)

$ export ANTHROPIC_API_KEY="your-key-here"

# OpenAI

$ export OPENAI_API_KEY="your-key-here"

# Add to shell profile (~/.bashrc, ~/.zshrc)

$ echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.bashrc

Interactive Mode

Once started, IronCode provides an interactive terminal UI:

Type your requests naturally in English
Switch between agents with Tab key
Use Ctrl+C to cancel operations
Use Ctrl+D or type exit to quit

Built‑in Skills

Skills are slash commands that switch IronCode into specialist modes. Type the command in the chat prompt and the agent becomes a different expert — founder, tech lead, QA tester, etc.

Quick Reference

Command	Role	What it does
/ceo-review	Founder	Rethink the problem. Find the 10‑star product. Three modes: Expand, Hold, Reduce scope.
/eng-review	Tech Lead	Lock architecture, data flow, failure modes, edge cases, test matrix.
/tdd	Developer	RED‑GREEN‑REFACTOR: failing test → minimal code → refactor. No production code without a failing test.
/debug	Debugger	4‑phase systematic debugging: root cause → pattern analysis → hypothesis → fix. 3‑fix rule escalates.
/verify	Gatekeeper	Run the command, read the output, then claim the result. Evidence before assertions.
/code-review	Staff Engineer	Two‑pass PR review: critical (type safety, injection, concurrency) + informational.
/code-ship	Release Engineer	Merge, test, typecheck, changelog, bisectable commits, push, PR — one command.
/browse	Browser Tool	Headless Chromium via Playwright. Navigate, click, fill forms, screenshot, assert states.
/qa	QA + Fix	Test web app, find bugs, auto‑fix with atomic commits, re‑verify. 4 modes.
/qa-only	QA Reporter	Same as /qa but never fixes — pure bug report with health score.
/qa-api	API Tester	REST/GraphQL testing. Auto‑discovers routes, tests with valid/invalid/edge‑case payloads.
/document-release	Technical Writer	Post‑ship doc update. Cross‑references diff against README, ARCHITECTURE, CHANGELOG.
/retro	Eng Manager	Weekly retro: commit analysis, session detection, per‑person praise and growth areas.

Typical Workflow

# 1. Plan — what are we building?

You: /ceo-review Add voice transcription to the Telegram bot

# 2. Design — how do we build it?

You: /eng-review

# 3. Build — write tests first, then code

You: /tdd

# 4. Stuck? Debug systematically

You: /debug

# 5. Review — find bugs before landing

You: /code-review

# 6. Verify — prove it works before shipping

You: /verify

# 7. Ship — merge, test, push, create PR

You: /code-ship

# 8. QA — test the deployed result

You: /qa http://localhost:3000

# 9. Document — update all project docs

You: /document-release

# 10. Reflect — weekly retrospective

You: /retro

You can use any skill standalone — the workflow is a suggestion, not a requirement.

QA Testing Guide

IronCode has 4 QA skills for different scenarios:

/qa

Web app with UI — finds bugs AND auto‑fixes them with atomic commits. Best for testing your own code.

/qa-only

Web app with UI — report only, never fixes. Best for auditing or reviewing someone else's code.

/qa-api

REST/GraphQL API without UI — tests endpoints with curl. Auto‑discovers routes from source code.

/browse

Raw browser tool — navigate, click, screenshot. Use for ad‑hoc testing, not full QA runs.

QA Modes

# Diff-aware — auto on feature branches (tests only what you changed)

You: /qa

# Full — test entire app

You: /qa http://localhost:3000

# Quick — 30-second smoke test

You: /qa http://localhost:3000 --quick

# Regression — compare with previous run

You: /qa http://localhost:3000 --regression baseline.json

# API testing

You: /qa-api http://localhost:4000

Testing Authenticated Pages

Three ways to handle authentication during QA testing:

1. Auto‑login (form-based auth)

You: /qa http://localhost:3000
# Agent finds login form, fills email/password, clicks submit
# Tell it: "Sign in as [email protected] / password123"

Works for simple login forms without CAPTCHA.

2. Cookie import (best for CAPTCHA / SSO / OAuth)

# Step 1: Login on your real browser (Chrome, Arc, etc.)
# Step 2: Export cookies
# Chrome DevTools → Application → Cookies → copy as JSON
# Or use a browser extension like "EditThisCookie"

# Step 3: Tell the agent
You: /qa http://myapp.com
Import cookies from cookies.json

Bypasses CAPTCHA, 2FA, SSO completely — the agent uses your already‑authenticated session.

3. 2FA / OTP

The agent logs in normally, then pauses and asks you for the 2FA code. You type it, the agent continues testing.

💡 CAPTCHA / Cloudflare Protection

Headless browsers cannot solve CAPTCHAs. Use the cookie import method — login on your real browser, export cookies, and the agent skips CAPTCHA entirely. This works for reCAPTCHA, hCaptcha, Cloudflare Turnstile, and any other challenge.

Testing Authenticated APIs

# Pass auth token directly

You: /qa-api http://localhost:4000 --auth "Bearer eyJhbG..."

# Or tell the agent to login first

You: /qa-api http://localhost:4000
Login with POST /api/auth/login {"email": "[email protected]", "password": "pass"}
Use the token from the response for all subsequent requests

Custom Skills

Create your own skills by adding a SKILL.md file to your project:

# Create a skill directory

$ mkdir -p .ironcode/skill/my-skill

# Create SKILL.md with YAML frontmatter

$ cat > .ironcode/skill/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What this skill does
---

# Instructions for the agent
Your prompt content here...
EOF

Skills are auto‑discovered — no restart needed. Type /my-skill in the chat and it works immediately.

How Built‑in Skills Work

Embedded in binary — skills are compiled into the IronCode executable at build time
Auto‑extracted — on first run, skills are written to ~/.ironcode/skill/ with a .builtin marker
Auto‑upgrade — when IronCode updates, built‑in skills are refreshed automatically
Customizable — delete the .builtin marker file to prevent auto‑upgrade, then edit the SKILL.md freely

Git Source Control

IronCode includes a built-in Git UI accessible within the TUI

Open Git Panel

•Press Ctrl+X then I (keybinding)
•Or type /git or /source-control command

Status View - Stage & Commit

See all file changes (staged/unstaged)

↑↓ or j/k: Navigate files
Space: Stage/unstage selected file
Enter: View diff
a: Stage all files
u: Unstage all files
r: Refresh status
p: Push to remote

Branches & Commits

Branches View

↑↓ or j/k: Navigate branches
Enter: Checkout branch
Current branch marked with *

Commit View

Type your commit message
Enter: Commit staged changes
Esc: Cancel

Push Authentication

IronCode supports multiple authentication methods:

SSH keys (id_rsa, id_ed25519) from ~/.ssh/
SSH agent
HTTPS with credential helper (GitHub CLI recommended)

For HTTPS with GitHub:

# Install GitHub CLI

$ brew install gh

# Authenticate

$ gh auth login

# Configure git credential helper

$ git config --global credential.helper '!gh auth git-credential'

Performance

Memory Efficiency

IronCode includes automatic resource monitoring to keep memory usage under control:

Default 300MB limit - Prevents excessive memory consumption
Real-time monitoring - Checks every 5 seconds
Auto-throttling - Automatically slows down at 95% memory
98% faster message processing - Selective cloning (254ms → 6ms)

# Default (300MB limit, monitoring enabled)

$ ironcode

# Custom memory limit

$ ironcode --max-memory 500

# Disable resource monitoring

$ ironcode --no-enable-resource-monitor

Native Rust Components

Performance-critical operations rewritten in Rust:

PTY/Terminal

15.29x faster - 93.5% reduction

File Reading

1.2-1.6x faster, 99.7% memory savings

Grep Search

90-99% memory reduction

Edit Tool

2-6x faster with fuzzy matching

Archive Extraction

3-5x faster (ZIP files)

Git Operations

1.5-3x faster via libgit2

Key Benchmarks

Operation	Speedup	Impact
PTY I/O	15.29x	58.15ms → 3.80ms
Edit Tool (10K lines)	6.03x	451ms → 75ms
Archive (500 files)	5.2x	740ms → 143ms
Glob Search (100 files)	2.74x	9.74ms → 3.55ms
Git Operations	1.83x	17.25ms → 9.43ms

CLI Commands

IronCode provides a comprehensive command-line interface with 16+ commands for all your development needs.

Development

Prerequisites

Bun 1.3.8 (exact version required)
Rust (latest stable)
Git

Building From Source

# Clone repository

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

# Install dependencies

$ bun install

# Build Rust native components

$ cd packages/ironcode/native/tool
$ cargo build --release
$ cd ../../../..

# Run CLI locally (development)

$ bun dev

# Build standalone executable

$ cd packages/ironcode
$ bun run build

Compiled binary: packages/ironcode/dist/ironcode/bin/ironcode

Contributing

We welcome contributions! Check out our contributing guidelines on GitHub.

Telegram Integration

Control IronCode remotely via Telegram. Send tasks from your phone, get real-time streaming output, and manage multiple sessions — all through a Telegram bot running on your machine.

Setup

1. Install IronCode and authenticate

$ npm install -g ironcode-ai
$ ironcode auth login

2. Create a Telegram bot via BotFather

Open Telegram, search for @BotFather, send /newbot and follow the prompts. Copy the bot token.

3. Install the Telegram bot package

$ npm install -g @ironcode-ai/telegram

4. Configure with your bot token

$ ironcode-telegram setup

Config is saved to ~/.config/ironcode/telegram.json

5. Start the bot from your project directory

$ cd your-project
$ ironcode-telegram

The bot starts an IronCode server in the current directory. Send messages from Telegram to control it.

Running on a Server (24/7)

Deploy the bot on a VPS or cloud instance so it's always available, even when your laptop is off.

Install & authenticate on the server

$ npm install -g ironcode-ai
$ bun install -g @ironcode-ai/telegram
$ ironcode auth login

Clone project & setup bot

$ git clone your-repo /app/my-project
$ ironcode-telegram setup

Run with PM2 (recommended — auto-restart + survives reboots)

$ npm install -g pm2
$ cd /app/my-project
$ pm2 start --name ironcode-telegram -- ironcode-telegram
$ pm2 save && pm2 startup

Or with systemd (Linux)

# /etc/systemd/system/ironcode-telegram.service

[Service]
User=ubuntu
WorkingDirectory=/app/my-project
ExecStart=/usr/local/bin/ironcode-telegram
Restart=on-failure

$ sudo systemctl enable --now ironcode-telegram

WorkingDirectory = the project the bot works with. Run a separate instance per project.

Bot Commands

Command	Description
/start	Welcome message and quick reference
/new	Start a new session
/sessions	List all sessions with inline buttons to switch
/info	Show current session ID and working directory
(any text)	Send a prompt to the AI agent — streams output live

Responses stream in real-time as the agent works, just like the TUI

Tool calls (file edits, searches) are reported as they complete

Sessions persist — switch between them with /sessions

Need More Help?

Check out the full documentation on GitHub or join our community