Configuration & Environment

Complete reference for iosm-cli settings, environment variables, profiles, and permission controls.

Configuration Directories

Global (User-Level)

~/.iosm/agent/
├── settings.json          # Global settings
├── mcp.json               # User MCP servers
├── semantic.json          # User semantic search config
├── models.json            # Model configuration and preferences
├── auth.json              # Provider credentials (OAuth + API keys via /login)
├── keybindings.json       # Custom keyboard shortcuts
├── extensions/            # Global extensions (auto-discovered)
├── skills/                # Global skills
├── prompts/               # Global prompt templates
├── themes/                # Global TUI themes
├── sessions/              # Persisted sessions
└── session-traces/        # JSONL trace files

Project-Level

.iosm/
├── settings.json          # Project-specific settings
├── semantic.json          # Project semantic search overrides
├── extensions/            # Project extensions
├── skills/                # Project skills
├── prompts/               # Project prompt templates
├── themes/                # Project themes
├── agents/                # Custom agent definitions
├── subagents/             # Subagent run transcripts
│   ├── runs/
│   └── teams/
└── cycles/                # IOSM cycle artifacts

.mcp.json                  # Project MCP servers (repository root)

Keybindings File

~/.iosm/agent/keybindings.json supports keyboard shortcut overrides.

Preferred format:

{
  "cycleModelForward": ["ctrl+p", "alt+p"],
  "cycleModelBackward": ["shift+ctrl+p", "alt+shift+p"],
  "selectModel": ["ctrl+l", "alt+l"],
  "expandTools": ["ctrl+o", "alt+o"]
}

Backward compatibility:

legacy key -> action entries are also accepted (from older examples)
action aliases such as nextModel, previousModel, and openModelSelector are normalized automatically

Settings Hierarchy

Settings are merged in this order (later wins):

1. Global settings    (~/.iosm/agent/settings.json)   ← lowest priority
2. Project settings   (.iosm/settings.json)
3. CLI flags                                            ← highest priority

Settings File Example

{
  "model": {
    "provider": "anthropic",
    "id": "claude-sonnet-4-20250514",
    "thinking": "medium"
  },
  "tools": {
    "enabled": ["read", "bash", "edit", "write", "grep", "find", "ls"],
    "bashTimeout": 30000,
    "maxOutputLines": 2000
  },
  "session": {
    "autoCompact": true,
    "compactThreshold": 100000,
    "maxRetries": 3
  },
  "terminal": {
    "shell": "/bin/zsh",
    "cols": 120
  },
  "githubTools": {
    "networkEnabled": false,
    "token": "optional-gh-token"
  },
  "dbTools": {
    "defaultConnection": "main",
    "connections": {
      "main": {
        "adapter": "postgres",
        "dsnEnv": "APP_DB_DSN",
        "clientArgs": [],
        "migrate": {
          "script": "db:migrate",
          "cwd": ".",
          "args": []
        }
      },
      "localSqlite": {
        "adapter": "sqlite",
        "sqlitePath": "./data/app.db"
      }
    }
  },
  "promptContext": {
    "enableContextDedupe": true,
    "maxContextCharsPerFile": 4000,
    "maxTotalContextChars": 12000,
    "enableGitSnapshotContext": false,
    "gitSnapshotMaxChars": 2000
  },
  "permissions": {
    "autoApprove": false,
    "extensionToolEnforcement": false
  }
}

githubTools.networkEnabled controls whether git_write network actions (fetch, pull, push) are allowed.
githubTools.token is optional and, when set, is injected for GitHub HTTPS authentication during network git actions. dbTools defines named DB connection profiles consumed by db_run; for network adapters (postgres, mysql, mongodb, redis) use dsnEnv so secrets stay in environment variables instead of tool input. promptContext controls system prompt context compaction before model call: dedupe by normalized content hash, per-file char budget, total char budget, optional git snapshot context inclusion, and bounded git snapshot size. permissions.extensionToolEnforcement enables strict runtime permission tier checks for extension tools (off by default).

Telegram Bridge Settings

Telegram remote control is opt-in and disabled by default.

{
  "telegram": {
    "enabled": true,
    "botToken": "123456:AA...",
    "allowedUserIds": [123456789],
    "transport": "long-polling",
    "chatDefaults": {
      "statusEditThrottleMs": 1200,
      "maxSummaryChars": 3000
    },
    "retry": {
      "apiMax429Retries": 4,
      "apiMaxNetworkRetries": 3,
      "apiNetworkBackoffInitialMs": 1500,
      "apiNetworkBackoffMaxMs": 30000,
      "pollingBackoffInitialMs": 2000,
      "pollingBackoffMaxMs": 30000,
      "statusEditNetworkRetryMs": 5000
    },
    "debug": {
      "pollingTrace": false
    }
  }
}

Run with iosm --mode telegram or iosm telegram.

Practical bridge notes:

Telegram has strict message-size/rate limits. Keep prompts and expected outputs focused; large results are summarized in chat and may be attached as files.
For heavy scans/audits, prefer script-file execution (write a .ps1/.cmd/.sh file, then run it) over one huge inline shell command.
On Windows, avoid complex nested escaping in one-liners. If a command needs heavy quoting ($, backticks, mixed quotes), switch to script-file execution path immediately.
For repository-wide search, explicitly exclude high-noise directories (node_modules, .git, dist, build, coverage, .next) unless they are in scope.

`db_run` Setup (Recommended)

Install required DB client CLI for your adapter:
- SQLite: sqlite3
- Postgres: psql
- MySQL: mysql
- MongoDB: mongosh
- Redis: redis-cli
Add named connection profiles to .iosm/settings.json (dbTools.connections).
For network adapters, export DSN env vars referenced by dsnEnv.
If settings were edited while a session is open, run /reload (or restart the session) before calling db_run.

SQLite profile example:

{
  "dbTools": {
    "defaultConnection": "main",
    "connections": {
      "main": {
        "adapter": "sqlite",
        "sqlitePath": "./test_database.sqlite"
      }
    }
  }
}

Postgres profile example:

{
  "dbTools": {
    "defaultConnection": "main",
    "connections": {
      "main": {
        "adapter": "postgres",
        "dsnEnv": "APP_DB_DSN",
        "clientArgs": []
      }
    }
  }
}

export APP_DB_DSN="postgres://user:password@localhost:5432/appdb"

db_run.connection expects a profile name (for example "main"), not a DB file path and not an inline DSN. db_run is built-in; no separate db-tools npm package is required.

MCP Configuration

Manage MCP servers from CLI and interactive mode:

# CLI
iosm mcp list
iosm mcp add filesystem --transport stdio --command npx --arg -y --arg @modelcontextprotocol/server-filesystem --arg .
iosm mcp add github --transport http --url https://mcp.example.com --tool-approval search=prompt --tool-approval get_file=approve
iosm mcp tools

# Interactive
/mcp
/mcp add                      # guided wizard
/mcp add filesystem --transport stdio --command npx --arg -y --arg @modelcontextprotocol/server-filesystem --arg .

Per-tool approval mode is set with --tool-approval <tool>=<mode>:

auto: default policy behavior.
prompt: always require confirmation.
approve: auto-allow only for trusted MCP servers (trust=true); otherwise confirmation is required.

MCP configs are loaded with project override precedence:

~/.iosm/agent/mcp.json
.mcp.json (project root)

Semantic Search Configuration

Semantic search is configured separately from settings and supports user/project override merge:

~/.iosm/agent/semantic.json
.iosm/semantic.json (project root, overrides user)

Interactive setup:

/semantic setup

CLI actions:

iosm semantic status
iosm semantic index
iosm semantic query "where auth token is validated" --top-k 8
iosm semantic rebuild

Schema (semanticSearch object):

{
  "semanticSearch": {
    "enabled": true,
    "autoIndex": true,
    "provider": {
      "type": "openrouter",
      "model": "openai/text-embedding-3-small",
      "baseUrl": "optional",
      "apiKeyEnv": "optional",
      "headers": {
        "KEY": "VALUE"
      },
      "batchSize": 32,
      "timeoutMs": 30000
    },
    "index": {
      "includeGlobs": [
        "**/*.{ts,tsx,js,jsx,py,go,rs,java,md,json,yaml,yml}"
      ],
      "excludeGlobs": [
        "**/.git/**",
        "**/node_modules/**",
        "**/dist/**",
        "**/build/**",
        "**/.iosm/**"
      ],
      "chunkMaxChars": 1200,
      "chunkOverlapChars": 200,
      "maxFileBytes": 262144,
      "maxFiles": 20000
    }
  }
}

autoIndex controls query-time automatic refresh:

true (default): query automatically refreshes stale index (and rebuilds when required)
false: stale/missing index must be updated manually via iosm semantic index / rebuild

Index storage (global cache):

~/.iosm/agent/semantic/indexes/<project-hash>/
├── meta.json
├── chunks.jsonl
└── vectors.jsonl

Environment Variables

Provider API Keys

/login supports the full provider catalog from models.dev and stores credentials in ~/.iosm/agent/auth.json. The table below lists common environment variables, but is not exhaustive.

Variable	Provider	Notes
`ANTHROPIC_API_KEY`	Anthropic (Claude)	Primary recommended provider
`OPENAI_API_KEY`	OpenAI (GPT)
`AZURE_OPENAI_API_KEY`	Azure OpenAI	Requires endpoint config
`GEMINI_API_KEY`	Google Gemini
`GROQ_API_KEY`	Groq
`CEREBRAS_API_KEY`	Cerebras
`XAI_API_KEY`	xAI (Grok)
`OPENROUTER_API_KEY`	OpenRouter	Multi-provider gateway + default semantic embeddings key
`MISTRAL_API_KEY`	Mistral
`MINIMAX_API_KEY`	MiniMax
`KIMI_API_KEY`	Kimi
`OPENCODE_API_KEY`	OpenCode
`AI_GATEWAY_API_KEY`	AI Gateway
`AWS_PROFILE`	AWS Bedrock	Also: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`

Runtime Configuration

Variable	Default	Description
`IOSM_CODING_AGENT_DIR`	`~/.iosm/agent`	Override global config directory
`IOSM_PACKAGE_DIR`	Auto	Override package base directory
`IOSM_OFFLINE`	`false`	Disable startup network operations (`1`/`true`/`yes`)
`IOSM_SESSION_TRACE`	`false`	Enable JSONL session trace logging
`IOSM_SESSION_TRACE_DIR`	Auto	Override trace directory location
`IOSM_SHARE_VIEWER_URL`	Default	Custom base URL for `/share` links
`IOSM_AI_ANTIGRAVITY_VERSION`	Auto	Override Antigravity user-agent version
`IOSM_SKIP_VERSION_CHECK`	`false`	Disable update/version checks
`TAVILY_API_KEY`	unset	Enables Tavily primary provider for `web_search`
`IOSM_WEB_SEARCH_SEARXNG_URL`	unset	Optional SearXNG fallback base URL for `web_search` (legacy alias: `PI_WEB_SEARCH_SEARXNG_URL`)

Example: Shell Configuration

Add to ~/.zshrc or ~/.bashrc:

# Provider key
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# Optional: enable tracing
export IOSM_SESSION_TRACE=1
export IOSM_SESSION_TRACE_DIR="$HOME/.iosm/traces"

# Optional: offline mode for air-gapped environments
# export IOSM_OFFLINE=1

Windows note: when IOSM runs through Git Bash, bash tool execution now auto-adapts native Windows command syntax (%LOCALAPPDATA%, dir, C:\..., $env:..., Get-*) to the correct interpreter (cmd.exe or powershell.exe) automatically.

Profiles

Profiles control the agent's behavior, available tools, and system prompt.

Primary Profiles

Profile	Tools	Behavior
`full`	All built-ins (read, bash, edit, write, git_write, fs_ops, test_run, lint_run, typecheck_run, db_run, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search, lsp, fetch, web_search, git_read)	Default full development capabilities
`plan`	Read-only bundle (read, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search, lsp, fetch, web_search, git_read)	Architecture planning and code review
`iosm`	All + IOSM context	IOSM cycle execution with artifact synchronization
`meta`	Full tools + orchestration-first contract	Adaptive multi-agent/delegate execution with verification closure

Advanced Profiles

Profile	Use Case
`explore`	Exploratory codebase analysis
`iosm_analyst`	Deep IOSM metric analysis
`iosm_verifier`	IOSM quality gate verification
`cycle_planner`	IOSM cycle planning specialist

db_run is enabled only in write-capable engineering profiles (full, meta, iosm).
typecheck_run is enabled in write-capable engineering profiles and iosm_verifier.

meta profile recommendation: for orchestration-heavy work, prefer modern models with large context windows (>=128k, ideally >=200k) and high output limits. This improves delegate routing, contract retention, and synthesis reliability.

Usage

# CLI flag
iosm --profile plan
iosm --profile iosm
iosm --profile meta

# Interactive: cycle with Shift+Tab
# full → plan → iosm → meta → full → ...

# In orchestration
/orchestrate --profiles explore,full,iosm_verifier

Permissions

Permissions control tool execution approval behavior.

Interactive Commands

# View current permission status
/permissions

# Enable auto-approve (YOLO mode)
/yolo on

# Disable auto-approve
/yolo off

# Check status
/yolo status

What Permissions Control

Tool calls: Whether the agent can execute tools without user confirmation
File writes: Whether edit and write tools require approval
Shell commands: Whether bash executions require approval
Destructive actions: Special handling for rm, sudo, etc.

Extension Tool Permission Tiers

Extension tools can declare one of the runtime tiers:

read-only
workspace-write
danger-full-access

When permissions.extensionToolEnforcement=true, interactive mode enforces stricter behavior for extension tools:

in auto mode, extension tools marked read-only are allowed automatically
extension tools missing requiredPermission metadata are blocked in auto mode (with warning)
ask and yolo modes keep their expected approval semantics

Example:

{
  "permissions": {
    "extensionToolEnforcement": true
  }
}

Prompt Context Budgets

promptContext applies deterministic preprocessing to loaded context files before they are appended to the system prompt:

normalize line endings and trim
optional dedupe by normalized-content hash
per-file cap (maxContextCharsPerFile)
total cap (maxTotalContextChars)
optional git snapshot context (enableGitSnapshotContext)
git snapshot cap (gitSnapshotMaxChars, default 2000)

Default values:

{
  "promptContext": {
    "enableContextDedupe": true,
    "maxContextCharsPerFile": 4000,
    "maxTotalContextChars": 12000,
    "enableGitSnapshotContext": false,
    "gitSnapshotMaxChars": 2000
  }
}

Safety Defaults

By default, iosm-cli asks for confirmation before:

Executing shell commands
Writing or editing files
Performing destructive operations

Use extensions like permission-gate.ts or protected-paths.ts for additional safety layers.

Provider-Specific Configuration

Anthropic

export ANTHROPIC_API_KEY="sk-ant-api03-..."

iosm --model claude-sonnet-4-20250514
iosm --model sonnet:high          # With thinking

OpenAI

export OPENAI_API_KEY="sk-..."

iosm --model gpt-5.3
iosm --model openai/gpt-5.3-mini

Google Gemini

export GEMINI_API_KEY="AI..."

iosm --model gemini-2.5-pro

AWS Bedrock

export AWS_PROFILE="default"
# or
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

iosm --provider bedrock --model anthropic.claude-v2

Azure OpenAI

export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"

iosm --provider azure --model gpt-5.3

OAuth-Based Providers

Some providers support OAuth login (for example, Qwen CLI free OAuth). API-key providers are available via the same /login flow from the models.dev catalog:

iosm
# In interactive mode:
/login
# Follow the authentication flow

Navigation Menu

Configuration & Environment

Configuration Directories

Global (User-Level)

Project-Level

Keybindings File

Settings Hierarchy

Settings File Example

Telegram Bridge Settings

`db_run` Setup (Recommended)

MCP Configuration

Semantic Search Configuration

Environment Variables

Provider API Keys

Runtime Configuration

Example: Shell Configuration

Profiles

Primary Profiles

Advanced Profiles

Usage

Permissions

Interactive Commands

What Permissions Control

Extension Tool Permission Tiers

Prompt Context Budgets

Safety Defaults

Provider-Specific Configuration

Anthropic

OpenAI

Google Gemini

AWS Bedrock

Azure OpenAI

OAuth-Based Providers

Further Reading

FilesExpand file tree

configuration.md

Latest commit

History

configuration.md

File metadata and controls

Configuration & Environment

Configuration Directories

Global (User-Level)

Project-Level

Keybindings File

Settings Hierarchy

Settings File Example

Telegram Bridge Settings

db_run Setup (Recommended)

MCP Configuration

Semantic Search Configuration

Environment Variables

Provider API Keys

Runtime Configuration

Example: Shell Configuration

Profiles

Primary Profiles

Advanced Profiles

Usage

Permissions

Interactive Commands

What Permissions Control

Extension Tool Permission Tiers

Prompt Context Budgets

Safety Defaults

Provider-Specific Configuration

Anthropic

OpenAI

Google Gemini

AWS Bedrock

Azure OpenAI

OAuth-Based Providers

Further Reading

`db_run` Setup (Recommended)