iosm-cli

Most AI CLIs are optimized for conversation. IOSM CLI is optimized for controlled engineering execution — working directly against your filesystem and shell, orchestrating parallel agents across complex tasks, tracking metrics and artifacts over time, and running improvement cycles that can be audited, repeated, and benchmarked.

It is not a chat interface. It is a runtime.

✦ What's New in 0.3.13

• Hotkeys are now more reliable across terminals and OSes:
  • added fallback bindings for unstable control combos (Ctrl+O/T/P/L now have Alt+... alternatives)
  • model cycling and selector shortcuts are more robust in Windows terminal environments
  • reverse model cycling is explicitly surfaced in /hotkeys
• Ctrl+Z/suspend behavior was hardened:
  • suspend is disabled on Windows by default (no broken signal path)
  • unsupported suspend environments now recover TUI safely and show a warning instead of breaking the session
• Keybinding configuration compatibility was improved:
  • supports both action -> key(s) (preferred) and legacy key -> action formats
  • normalizes common variants (Control+..., case/spacing differences)
  • includes action aliases like nextModel, previousModel, openModelSelector
• Keyboard docs and runtime hints were aligned:
  • updated interactive/docs/configuration examples to the real supported format
  • /hotkeys now displays active bind values (including platform-specific image-paste key)

✦ Major Additions in 0.2.16

• Policy Engine v2 for deterministic layered permission resolution across interactive and RPC modes
• Session/turn-scoped permission approvals to reduce repetitive confirmation prompts in ask mode
• Security baseline for package and extension sources: trust ledger, host allowlist checks, fingerprint/integrity verification, explicit consent flow
• MCP trust enforcement with per-tool policy decision tracing
• Opt-in Linux sandbox execution with explicit bwrap requirement validation
• Filesystem checkpointing (snapshot/restore) integrated into command execution flow with deterministic rollback order
• ACP adapter mode (--mode acp) over existing RPC/event bus with capability degradation mapping
• New built-in tools: apply_patch, tool_search, and tool_suggest
• PTY-based unified execution runtime support for interactive process workflows
• Faster session resume path via indexed session lookup
• Schema-driven settings with generated configuration documentation and CI consistency checks
• Improved task UX in interactive mode: structured checklist rendering for task-state operations instead of raw JSON payload dumps

Table of Contents

• What You Get
• The IOSM Methodology
• Quick Start
• Usage Patterns
• Agent Profiles
• Complex Change Workflow
• Integration Modes
• Extensibility
• Configuration
• Architecture
• Documentation
• Development
• Contributing
• License

✦ What You Get

| Area | Capability | |------|-----------| | Everyday coding | Interactive terminal session with file, search, edit, and shell tools | | Operational safety | /checkpoint, /rollback, /doctor, granular permission controls | | Complex changes | /contract → /singular → /swarm — deterministic execution with locks and gates | | Codebase understanding | Semantic search, repository-scale indexing, project memory | | Multi-agent work | Parallel subagents with shared memory and consistency model | | Background execution | Detached shell runs (! <command> &) with /bg process management | | Methodology | IOSM cycles: measurable improvement with metrics, evidence, and artifact history | | Integrations | Interactive TUI, print mode, JSON event stream, JSON-RPC server, Telegram bridge, TypeScript SDK | | Extensibility | MCP servers, TypeScript extensions, Markdown skills, prompt templates, themes |

✦ The IOSM Methodology

IOSM — Improve, Optimize, Shrink, Modularize — is an algorithmic methodology for systematic engineering improvement. It transforms ad-hoc refactoring into a reproducible, measurable process.

Four mandatory phases — executed in strict order:

Improve → Optimize → Shrink → Modularize

| Phase | Focus | |-------|-------| | Improve | Eliminate defects, inconsistencies, and technical debt | | Optimize | Reduce resource usage, latency, and execution cost | | Shrink | Minimize code surface — delete dead code, compress abstractions | | Modularize | Extract cohesive components, enforce dependency hygiene |

Six canonical metrics track progress across every phase:

| Metric | Measures | |--------|----------| | semantic | Code clarity — naming, comments, structure readability | | logic | Correctness — test coverage, error handling, invariants | | performance | Runtime efficiency — latency, throughput, resource usage | | simplicity | Cognitive load — cyclomatic complexity, abstraction depth | | modularity | Dependency health — coupling, cohesion, interface clarity | | flow | Delivery velocity — CI reliability, deploy frequency, lead time |

Metrics can be derived automatically or attached as evidence during IOSM cycles.

The IOSM-Index aggregates all six metrics into a single weighted health score. Every cycle produces a baseline, hypothesis cards, evidence trails, and a final report — stored in .iosm/ for permanent project history.

Quality gates after each phase enforce progression: a phase cannot close if any guardrail is breached.

Full specification: iosm-spec.md · Canonical repository: github.com/rokoss21/IOSM

✦ Quick Start

1. Install

npm install -g iosm-cli
iosm --version

Requirements: Node.js >=20.6.0 · at least one authenticated model provider

No global install? Use npx:

npx iosm-cli --version

2. Configure a provider

The fastest path is interactive setup inside the app:

iosm
/login      ← OAuth or API key (models.dev catalog)
/model      ← pick your model

Or set an environment variable before launching:

export ANTHROPIC_API_KEY="sk-ant-..."   # Claude (recommended)
export OPENAI_API_KEY="sk-..."          # GPT models
export GEMINI_API_KEY="AI..."           # Gemini
export GROQ_API_KEY="gsk_..."           # Groq
# Also supported: OpenRouter, Mistral, xAI, Cerebras, AWS Bedrock

3. Run your first session

cd /path/to/your/project

# Interactive mode
iosm

# Or one-shot without entering the TUI
iosm -p "Summarize the repository architecture"

Inside interactive mode:

Review the repository structure and summarize the architecture.

4. Optional — enhanced search toolchain

Works without these, but large repositories benefit significantly:

# macOS
brew install ripgrep fd ast-grep comby jq yq semgrep

# Ubuntu / Debian
sudo apt-get install -y ripgrep fd-find jq yq sed

Run /doctor to check your environment at any time.

✦ Usage Patterns

Daily coding and repository work

Default full profile. Works on any codebase without prior setup.

iosm

Common tasks:

• implement or refactor features
• read, search, and edit files with full shell access
• run long shell jobs in background (! npm run dev &) and manage them through /bg interactive menu (list/running/status/logs/stop/stop-all/prune)
• treat "start/run project or dev server" requests as detached background jobs by default, then follow with /bg status|logs|stop
• manage extension lifecycle from chat with /extensions (/ext) for list/install/update/remove/enable/disable
• review architecture or explore unfamiliar modules
• resume previous sessions: /resume, /fork, /tree
• keep persistent notes: /memory

One-shot tasks skip the interactive TUI entirely:

iosm -p "Audit src/ for unused exports"
iosm @README.md @src/main.ts -p "Explain the CLI entry points"
iosm --tools read,grep,find -p "Find all TODO comments in src/"

Read-only planning and review

Use plan when you want architecture analysis or code review without any writes.

iosm --profile plan

The agent is restricted to read-only tools. Nothing can be written to disk. Useful for code review, architecture audits, or exploring a codebase you are unfamiliar with before making changes.

Complex or risky engineering changes

Define constraints → analyze options → execute with guardrails:

/contract
/singular Refactor auth module, split token validation from session management

`/singular