iAgentX for IBM i

Bring your IBM i system into VS Code AI agents — GitHub Copilot Chat, Claude Code, and IBM Bob.

iAgentX for IBM i exposes IBM i resources (source members, IFS files, SQL, job logs, CL commands) to AI coding agents via the Model Context Protocol (MCP). It reuses the active SSH connection managed by Code for IBM i — no second connection, no extra credentials.

iAgentX is updated frequently. Enable auto-updates in VS Code: Extensions → right-click iAgentX for IBM i → Enable Auto Update.

See It In Action

Your AI is brilliant. Just completely blind to IBM i.

iAgentX for IBM i — Bring AI Intelligence to Your IBM i

The Challenge — Why AI can't help IBM i developers

Market Gap — How do the options stack up?

The Solution — Meet iAgentX for IBM i

Architecture — How it all connects

Security — Built-in, not bolted-on

Capabilities — 29 IBM i Tools

Demo 1 — Diagnose a job stuck in MSGW

Demo 2 — Analyse an IFS directory and explain its contents

Demo 3 — Analyse a source member and generate a program flow diagram

Demo 4 — Cross-table row count analysis

Demo 5 — Debug & fix a SQL table function

Impact — Before & After iAgentX

Get Started — Up and running in 3 steps

What you can do

Ask your AI agent to:

• Read and review source members (RPG, CL, COBOL, DDS, …)
• Search across source members — find any string or symbol across a whole source physical file
• Edit open source members directly from the AI agent — surgical single-line replacements or full updates
• Browse IFS files and directories; search IFS trees recursively by text content and filename pattern
• Query DB2 for i with plain SQL
• Explore objects in a library — list by type, check existence, read data area values, inspect file fields
• Inspect program and service program details — ILE attributes, activation group, bound modules
• Pull job log messages by job ID — works for active and ended jobs alike; look up CPFxxxx message text from any message file
• Retrieve spool file content (QPJOBLOG and others) from any job; browse spool files on a named output queue
• Search for jobs by name pattern, user, subsystem, and status; list user profiles with status and last signon
• Run read-only CL commands (DSPFD, WRKACTJOB, …)

Everything happens through the existing Code for IBM i SSH session.

Requirements

• VS Code 1.99 or later
• Code for IBM i — installed and connected to an IBM i system
• One or more of the supported AI agents:
  • Claude Code CLI
  • Claude Code VS Code extension
  • GitHub Copilot Chat (built into VS Code)
  • IBM Bob

Installation

Install from the Marketplace or via the command line:

code --install-extension Duvaragesh.iagentx4i

Or install a .vsix file directly (e.g. after building from source):

Extensions view → ⋯ → Install from VSIX… → select iagentx4i-<version>.vsix

code --install-extension iagentx4i-<version>.vsix

No manual configuration required — the extension auto-configures Claude Code and VS Code on first activation.

Setup

Claude Code (automatic)

On first activation the extension writes its MCP server URL into ~/.claude.json automatically:

{
  "mcpServers": {
    "iagentx4i": {
      "type": "sse",
      "url": "http://127.0.0.1:41927/sse"
    }
  }
}

After installing, start a new Claude Code session — the IBM i tools will be discovered automatically.

GitHub Copilot Chat (automatic)

The extension registers itself via VS Code's MCP provider API and writes to %APPDATA%/Code/User/mcp.json (Windows) or the platform equivalent. Copilot Chat picks this up without any manual steps.

IBM Bob (automatic)

iAgentX auto-configures IBM Bob by writing to its MCP settings file. Set the iagentx4i.bobAppDataFolder setting to the app data folder name Bob uses on your machine (e.g. IBMBob) — leave it blank to skip Bob configuration.

The file updated is:

%APPDATA%\<bobAppDataFolder>\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

For example, with bobAppDataFolder set to IBMBob:

%APPDATA%\IBMBob\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

The extension only updates this file if it already exists — confirming Bob is installed before writing.

Port conflict

The server starts on port 41927 by default and automatically tries the next 4 ports (41928–41931) if busy. The status bar shows the actual port in use. If the port changes between VS Code restarts, click the status bar item → Refresh iAgentX config and restart your Claude Code session.

To pin a port permanently:

"iagentx4i.preferredPort": 41927

Available Tools

Connection & status

Source members & libraries

IFS

SQL & data

Jobs, spool & diagnostics

Users

Messages

Editor (VS Code)

Tool details

Input:  (none)
Output: { connected, host?, user?, port?, connectionName?, osVersion? }

Input:  library (string), spf (string), member (string)
Output: { library, spf, member, memberType, content, lines }
Example: ibmi_get_source_member("DK", "QCLLESRC", "BATCHFTP")

Input:  library (string), spf (string), filter? (string, * wildcard)
Output: { library, spf, total, members: [{ name, type, description, lastModified, lines }] }
Example: ibmi_list_source_members("DK", "QCLLESRC", "BATCH*")

Input:  library (string)
Output: { library, total, files: [{ name, description }] }

Input:  library (string), objectType? (string, default *ALL), nameFilter? (string, * wildcard)
Output: { library, objectType, total, objects: [{ name, type, attribute, description, owner, size, lastModified }] }
Example: ibmi_list_objects("DK", "*PGM")

Input:  library (string), name (string), objectType (string)
Output: { exists, library, name, objectType, attribute?, description?, owner?, size?, createTime?, lastModifiedTime?, lastUsedTime? }

Input:  library (string), name (string), objectType (string)
Output: { exists, library, name, objectType, attribute?, description? }

Input:  library (string), file (string)
Output: { library, file, total, fields: [{ name, type, length, precision, scale, nullable, default, description, position }] }

Input:  (none)
Output: { total, libraries: [{ library, type, position, description }] }
Types:  *SYS (system), *PROD (product), *CUR (current), *USR (user library list)

Input:  path (string)
Output: { path, content, size, encoding }
        encoding: "ccsid-NNN" | "base64-binary" | "utf-8-fallback"

Input:  path (string)
Output: { path, total, entries: [{ name, type, path, size, lastModified, owner }] }

Input:  path (string), pattern (string), filePattern? (string)
Output: { path, pattern, total, matches: [{ file, line, content }] }

Input:  query (string), maxRows? (number, default 100, max 1000), offset? (number, default 0)
Output: { rows, columns, rowCount, offset, hasMore }
Note:   On V7R6+ use TABLE() wrapper: FROM TABLE(QSYS2.func(...)) — auto-retried on SQL0104.
Example: ibmi_run_sql("SELECT * FROM QSYS2.SYSTABLES WHERE TABLE_SCHEMA = 'DK'")
         ibmi_run_sql("SELECT * FROM DK.CUSTMST", maxRows=50, offset=100)

Input:  library (string), name (string)
Output: { library, name, value, dataType, length, description }
        dataType: *CHAR | *DEC | *LGL

Input:  job? (NUMBER/USER/NAME, or omit for current job),
        minSeverity? (number), messageType? (*ESCAPE | *DIAG | *COMP | *INFO | *NOTIFY | *REQUEST | *STATUS),
        maxMessages? (number, default 100, max 500), includeTimestamp? (boolean)
Output: { total, messages: [{ id, text, secondLevelText?, severity?, type?, sendTime? }] }
Example: ibmi_get_job_log("123456/MYUSER/BATCH", minSeverity=40, messageType="*ESCAPE")

Input:  jobname (string, trailing * wildcard), username? (string),
        status? ("ACTIVE" | "OUTQ" | "ALL"), subsystem? (string),
        date_from? (YYYY-MM-DD), date_to? (YYYY-MM-DD)
Output: { total, jobs: [{ job_number, job_user, job_name, status, end_time, completion_code, subsystem }] }
Example: ibmi_find_jobs("BATCH*", subsystem="QBATCH", status="ACTIVE")

Input:  job? (NUMBER/USER/NAME), username? (string), splfname? (string), maxFiles? (number, default 50, max 200)
Output: { total, spoolFiles: [{ job, splfname, splfnbr, status, pages, createTime, outputQueue, outputQueueLibrary }] }

Input:  job (NUMBER/USER/NAME), splfname (string), splfnbr? (number),
        startLine? (number, 1-based), lineCount? (number)
Output: { job, splfname, splfnbr, content, startLine, returnedLines, totalLines }

Input:  command (string)
Output: { output, stderr?, exitCode }
Allowed prefixes (configurable): DSP, LST, WRK, CHK, PRT, DMP, RTV, QRY
Also allowed: CPYSPLF FILE(...) TOFILE(*TOSTMF) ... TOSTMF('/tmp/...')
Example: ibmi_run_cl_command("DSPFD FILE(DK/CUSTMST)")

Input:  (none)
Output: { scheme, library?, spf?, member?, ifsPath?, filePath?, content, isDirty, lineCount }

Input:  (none)
Output: Array of { uri, scheme, library?, spf?, member?, ifsPath?, filePath?, isDirty, lineCount, isActive }

Input:  oldText (string, must be unique in the file), newText (string)
Output: { success, uri, replacedAtLine }

Input:  content (string — use real newline characters, not escaped \n)
Output: { success, uri }

Input:  uri (string — from ibmi_list_open_editors), content (string)
Output: { success, uri }

Settings

Status Bar

The status bar item reflects the live state of both the iAgentX server and the IBM i connection.

Click the status bar item to open the management menu:

• Start iAgentX server — start the server after a manual stop
• Stop iAgentX server — shut down the server
• Restart iAgentX server — stop and restart (useful after a port conflict)
• Refresh iAgentX config — re-write ~/.claude.json and mcp.json with the current port

The command is also available from the Command Palette as iAgentX: Manage MCP Server.

Multiple VS Code Windows

Only one iAgentX server runs at a time. When you open a second VS Code window, it detects the existing server on port 41927 and enters shared mode — the status bar shows (shared) and the second window's AI tools route through the same server. No extra ports are used.

Architecture

Claude Code (CLI)  /  GitHub Copilot Chat  /  IBM Bob
        │
        │  MCP over HTTP+SSE
        │  GET /sse  →  opens event stream
        │  POST /message?sessionId=N  →  JSON-RPC messages
        ▼
VS Code Extension Host  (iAgentX for IBM i)
  HTTP server  127.0.0.1:41927  (loopback only)
        │
        │  Code for IBM i public API
        ▼
halcyontechltd.code-for-ibmi  (existing SSH session)
        │
        ▼
IBM i System

The HTTP server binds to 127.0.0.1 only — never reachable from outside your machine.

Security

• All tools are read-only — no write, delete, or compile operations
• Editor tools (ibmi_update_*, ibmi_replace_*) only modify files open in the editor — no blind remote writes
• ibmi_run_sql only accepts SELECT, WITH (CTEs), and VALUES statements
• ibmi_run_cl_command enforces a configurable verb-prefix allowlist; CPYSPLF is only permitted with TOFILE(*TOSTMF) and a destination under /tmp/
• ibmi_get_spool_file copies to a temp path under /tmp/ and deletes after reading
• No credentials stored — piggybacks on Code for IBM i's SSH session
• iAgentX server binds to loopback (127.0.0.1) only — never reachable from outside your machine

Troubleshooting

Claude Code doesn't see the IBM i tools

1. Check the status bar — must show ✓ iAgentX :NNNNN
2. Click the status bar item → Refresh iAgentX config
3. Start a new Claude Code session

No active IBM i connection error Open Code for IBM i and connect: Ctrl+Shift+P → IBM i: Connect

Status bar shows ⚠ iAgentX IBM i is disconnected. VS Code editor tools still work. Reconnect via Code for IBM i and the icon will return to ✓ automatically.

Port changed between restarts Click the status bar item → Refresh iAgentX config, then restart Claude Code.

ibmi_run_sql rejects a statement Only SELECT, WITH (CTEs), and VALUES are allowed. DML and DDL are blocked.

SQL0104 error on table functions Use the TABLE() wrapper: FROM TABLE(QSYS2.func(...)) instead of FROM QSYS2.func(...). The tool auto-retries once with the wrapper, but writing it correctly avoids the round-trip.

CL command rejected Add the verb prefix to iagentx4i.clAllowedPrefixes in VS Code settings.

For Developers

Build from source

Prerequisites: Node.js 18+ and npm.

git clone https://github.com/Duvaragesh/iagentx4i.git
cd iagentx4i
npm run package

npm run package automatically installs dependencies, runs unit tests, compiles TypeScript, and produces iagentx4i-<version>.vsix in the project root.

Testing overview

There are two independent test layers:

Unit tests

All IBM i and VS Code APIs are mocked — runs instantly in Node.js with no live system.

npm test                 # run once
npm run test:watch       # re-run on file save
npm run test:coverage    # generate coverage/index.html

Unit tests cover all 29 tools plus utilities.

Integration tests

Integration tests run inside a real VS Code extension host using @vscode/test-cli with Mocha. This gives access to the real vscode API and the live IBM i connection managed by Code for IBM i.

Prerequisites:

• VS Code installed
• Code for IBM i extension installed and connected to an IBM i system
• Run from a terminal where VS Code is accessible on PATH

npm run test:int

This compiles the integration tests (tsc -p tsconfig.int.json) and launches a headless VS Code instance to run the Mocha suites against the real IBM i system.

What is tested:

• connectionStatus — verifies host, user, and OS version from a live connection
• runSql — executes a real SELECT against QSYS2.LIBRARY_LIST_INFO; verifies DML is blocked
• getLibraryList — confirms QSYS appears in the real library list
• listSourceFiles — lists source files in QSYS
• runSql pagination — verifies maxRows and offset work against real data

Publish gate

npm run package and npm run publish both run npm test (unit tests) first. Integration tests are a separate manual step — run them before cutting a release when an IBM i system is available.

Test structure

src/tests/
├── __mocks__/           # Shared vscode + ibmiConnection stubs
├── utils/               # parseEditorUri, ccsidCast, qsysPath
├── tools/
│   ├── source/          # getSourceMember, listSourceMembers, listSourceFiles, searchSourceMembers
│   ├── ifs/             # getIfsFile, listIfsDirectory, searchIfs
│   ├── sql/             # runSql, getFileFields, getLibraryList
│   ├── jobs/            # findJobs, getJobLog, getSpoolFile, listSpoolFiles
│   ├── objects/         # listObjects, getObjectInfo, checkObject, getDataArea, getProgramInfo, getOutputQueueInfo
│   ├── admin/           # listUserProfiles, getMessageDescription
│   ├── editor/          # getActiveEditor, listOpenEditors, updateActiveEditor, updateEditorByUri
│   └── connection/      # connectionStatus
└── integration/         # Mocha suites — run via @vscode/test-cli against live IBM i

License

Elastic License 2.0 (ELv2) — Free to use including in enterprise environments. Commercial resale or offering as a hosted/managed service requires a separate commercial license. — GitHub: Duvaragesh/iagentx4i