IOSM CLI
Terminal coding agent with profiles, a swarm of subagents, checkpoints and code improvement cycles scored on six metrics
- 143 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent reads and writes project files and runs shell commands, including long background processes
- The swarm mode edits code in parallel, and the Telegram bridge lets you drive it remotely
- Provider keys sit in environment variables or come from `/login`, and project context goes to the chosen model
Install
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/iosm-cliDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent reads and writes project files and runs shell commands, including long background processes
- The swarm mode edits code in parallel, and the Telegram bridge lets you drive it remotely
- Provider keys sit in environment variables or come from `/login`, and project context goes to the chosen model
This is third-party code. Review the repository files before installing.
What it does
IOSM CLI is a Node.js terminal agent for working with code. It reads and edits files, runs shell commands, searches the repository and keeps long processes in the background. It works with models from Anthropic, OpenAI, Gemini, Groq, OpenRouter, Mistral, xAI, Cerebras and AWS Bedrock; you set access through `/login` or environment variables. What sets it apart is the IOSM method of four phases (`Improve`, `Optimize`, `Shrink`, `Modularize`). `iosm cycle plan` builds an improvement cycle, and six metrics (semantic, logic, performance, simplicity, modularity, flow) add up to an IOSM index. Baselines, hypothesis cards and final reports live in the project's `.iosm/` folder. For complex changes there is a `/contract`, `/singular` and `/swarm` chain: it fixes the scope, offers three options and launches parallel subagents with locks and gates. Profiles `full`, `meta`, `iosm` and `plan` set the toolset, and `plan` leaves read-only access. It connects MCP servers (the `.mcp.json` file), TypeScript extensions, markdown skills and prompt templates. Modes include `-p` for a single task, a JSON stream, RPC for editors and a Telegram bridge.
Who it is for. Engineers who change large codebases and want metrics and an artifact trail after every refactoring.
Good fit when
- Refactoring an auth module with three options laid out and a checkpoint before writes
- Auditing `src/` in `iosm --profile plan` when writing to disk must be closed off
- A series of improvement iterations toward a target index that rises from cycle to cycle
- A one-off `iosm -p` run in a CI pipeline where a non-zero exit code on failure matters
- Steering a long task from a phone through the Telegram bridge
Not a fit when
- You only want to chat with a model without file and shell access: the tool has a full set of rights by default
- The task is a couple of lines: the `/contract`, `/singular`, `/swarm` chain targets complex changes
- The environment has no Node.js 20.6 or newer: the package installs through npm
- You have no key or sign-in with any provider: the agent will not start without a model
Example request
Run iosm --profile plan and review the src folder for unused exports without changing anythingLimitations
The last commit in the repository dates from April 2026. It needs Node.js 20.6 or newer and a sign-in with at least one model provider. The author recommends `meta` delegation mode only for a strong model with a large context, and `full` for ordinary sessions. The extra search tools `ripgrep`, `fd`, `ast-grep` and `semgrep` install separately, and without them the tool is slower on large repositories.
How to disable. Run `npm uninstall -g iosm-cli`. Delete the `.iosm/` folders in your projects and the user settings by hand if you no longer need them.
FAQ
How do I install IOSM CLI?
Run `npm install -g iosm-cli` and check `iosm --version`. Without a global install, `npx iosm-cli --version` also works. Then type `/login` inside `iosm` and pick a model.
What is the IOSM index?
It is a single weighted score across six metrics: semantic, logic, performance, simplicity, modularity and flow. The `/iosm 0.95 --max-iterations 5` cycle steers work toward the target and saves the baseline and report in `.iosm/cycles/`.
Can I forbid the agent from writing files?
Yes, start `iosm --profile plan`. The profile keeps only reading, so nothing reaches the disk. You can narrow the tool list with the `--tools read,grep,find` flag too.
Does IOSM CLI work with MCP?
Yes. MCP servers connect at user or project level through the `.mcp.json` file. Tool calls pass through a permission policy, and decisions are recorded for review.
How is the meta profile different from full?
The `meta` profile mostly delegates tasks to parallel subagents, while `full` does the work itself. The author recommends `full` as the default for ordinary sessions.
Discussion
No questions or reviews yet.
Related
CLI toolsWork modes for AI coding agents: a light solo mode for daily tasks and /man with a plan, checks and review for big changes
An MCP server and CLI for code research: search and understand your project and all of GitHub with fewer tokens
Open-source multi-agent coding CLI: switch models mid-session and finish a goal only when your own test passes
A CLI that runs Claude Code, Codex, Gemini CLI and other agents in parallel on one task and collects their answers side by side
A terminal coding agent in Go that edits files and runs commands in a UI or scriptable CLI and works with any model.
A Python terminal coding agent in the manner of Claude Code: reads the repository, edits files, runs commands, with memory, sub-agents and MCP
Comparison with similar tools
Cards that share the main search query, and how they differ.
README in short
The README opens with the new features of version 0.3.13 (hotkeys, keybinding settings) and an overview of the earlier 0.2.16 with its permission policy, checkpoints and ACP mode. It then describes the IOSM method with its phases and metrics, quick start, working patterns, agent profiles, embedding modes and extensibility. The documentation section points to files in `docs/`.