Orbit AI

AI-powered coding companion for IBM ACE integration developers.

Orbit brings an AI agent directly into your terminal — purpose-built for IBM App Connect Enterprise (ACE), ESQL, IBM MQ, and API Connect workflows. It ships with embedded skills and reference material so the AI understands your integration stack out of the box.

Install

npm install -g orbit-code-ai

Requires Node.js 20 or later.

Quick Start

With Anthropic (Claude)

export ANTHROPIC_API_KEY=sk-ant-your-key-here
orbit

Windows PowerShell:

$env:ANTHROPIC_API_KEY="sk-ant-your-key-here"
orbit

With Gemini

export GEMINI_API_KEY=your-key-here
orbit

With Ollama (local, no API key)

export ORBIT_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=qwen2.5-coder:7b
orbit

What's Inside

Orbit ships with a suite of IBM ACE slash commands and a full agent reference — loaded automatically so the AI has deep context on your stack without any extra setup.

Commands

| Command | What it does | |---|---| | /ace-app | Generate a complete IBM ACE application from requirements — .project, descriptor, gateway + main flows, subflows, ESQL, XSD, and Swagger | | /ace-scaffold | Scaffold a single new message flow with ESQL from a description | | /ace-review | Thorough code review of ESQL, flow wiring, naming, error handling, and standards | | /ace-fix | Diagnose and fix bugs in ESQL or message flows | | /ace-explain | Explain an ACE flow or ESQL module in plain language | | /ace-refactor | Refactor ESQL for performance, clarity, and standards | | /ace-test | Generate comprehensive test scenarios for flows and ESQL | | /apic-api | Generate a complete API Connect (APIC) API definition — OpenAPI contract plus the full x-ibm-configuration assembly (JWT validate, logging, response envelope, catch handlers) | | /gitlab | Connect your GitLab server (URL + access token) so Orbit can browse, read and clone your repos — see GitLab |

Agent Reference

Built-in reference docs loaded into every session:

• ESQL coding standards
• Message flow XML reference
• Node types (extended)
• HTTP, MQ, and file flow templates
• Naming conventions and properties templates
• Component patterns: audit logging, common utils, error handling, HTTP/input/output adapters, retry

Supported Providers

| Provider | How to configure | |---|---| | Anthropic (Claude) | ANTHROPIC_API_KEY env var | | Google Gemini | GEMINI_API_KEY env var | | OpenAI | ORBIT_CODE_USE_OPENAI=1 + OPENAI_API_KEY | | Ollama (local) | ORBIT_CODE_USE_OPENAI=1 + OPENAI_BASE_URL pointing to local server | | OpenAI-compatible | Any /v1-compatible endpoint via OPENAI_BASE_URL |

Features

• IBM ACE-aware — skills and reference docs ship inside the package; no external config needed
• Terminal-first — streaming responses, tool calling, slash commands, file tools, bash
• MCP support — connect external Model Context Protocol servers
• GitLab access — browse, search, read and clone repos on your own GitLab server, including ones behind a VPN (see GitLab)
• Agent routing — route different tasks to different models via ~/.orbit/settings.json
• gRPC server mode (source build) — run Orbit as a headless service on localhost:50051 for CI/CD or custom UI integration
• Privacy-first — telemetry stubbed at build time; no phone-home

LLD → APIC artifacts

Turn a middleware Low-Level Design (.docx) into deployable artifacts. /lld reads the Word document (paragraphs and tables), extracts the API spec against the house template, shows you an extraction summary to confirm, then generates any combination of:

/lld "C:\path\to\LLD_MyApi.docx" [contract] [api] [diagram]   # or: both | all (default: all)

• contract → a contract-only OpenAPI (rich request/response/error schemas) via /api-contract
• api → the APIC gateway definition (x-ibm-configuration assembly) via /apic-api — supports a backend pattern (APIC wraps a raw backend in the ESB envelope) and a wrapper pattern (a thin proxy over an existing ACE/webMethods service that already returns the envelope)
• diagram → the Integration Service Flow as a .drawio file (BIDAYA activity-diagram house style) via /drawio

The diagram is drawn deterministically from a small flow model, and branches reflect the LLD:

• a token branch (access-token call cached until the JWT exp) appears only when auth is token-based — omitted for no-auth / static-key services;
• a cache branch appears only when the MW caches the response — omitted when the LLD says "Cache: Not applicable";
• the success/error decision uses the LLD's actual success rule (e.g. HTTP 200, or a body status code like eigerResultCode = 200), feeding green (success) / red (error) mapping boxes.

Output opens directly in diagrams.net with the house style: green swimlanes, blue action parallelograms, pink decision diamonds, green/red mapping boxes, a yellow START ellipse and a red-ringed final node.

GitLab

Orbit can read code straight from your GitLab server, gitlab.com or self-hosted. Requests go out from your machine, so a server that is only reachable over the company VPN works as soon as the VPN is connected.

Connect with /gitlab

Inside Orbit, run:

/gitlab

Orbit asks for two things:

1. Server URL, e.g. https://gitlab.yourcompany.com
2. Personal access token — typed into a hidden field. Orbit shows a link that opens GitLab's token page with the name and the read_api + read_repository scopes already filled in.

It tests the connection, then saves the URL in Orbit's config and the token in your OS credential vault (Windows Credential Manager / macOS Keychain / libsecret), never in the chat or the project. If the VPN is off during setup you can choose Save anyway.

| Command | What it does | |---|---| | /gitlab | Set up or change the connection | | /gitlab <url> | Same, with the URL filled in | | /gitlab status | Show the saved connection and test it | | /gitlab logout | Forget the saved URL and token |

Admins / CI: GITLAB_URL and GITLAB_TOKEN environment variables also work (for example under "env" in ~/.orbit/settings.json) and take precedence over /gitlab. Set ORBIT_CODE_DISABLE_GITLAB=1 to hide the GitLab tool entirely.

Using it

Ask in plain language: "list the files in integration/esb/CustomerSync", "read src/Main.esql on the develop branch", "search the esb group for SET OutputRoot.MQMD", or paste a GitLab file link. The GitLab tool can walk the nested group tree, list and search projects, list a repository tree, read files, search code, list branches, tags and commits, compare two branches, and git clone a project into your working directory (it asks before cloning).

Deployments and pipelines

• Pre-flight check — "can I deploy cmpm-manage-license release/v1.0.0 to prod?" Orbit detects whether the repo uses the old branch-per-environment flow or the v2 tag-based flow and checks what the pipeline will check (and what it silently doesn't): branch naming, prod-only-from-release, library tags and folders in build.properties, library configs promoted to that environment in ace-deployments, open deployment MRs, promotion order (stage → preprod → main), how far your branch is behind its target, and recent shared-lib changes that will ship with you.
• Failure diagnosis — "why did pipeline 1295721 fail?" Orbit reads the failed jobs and names the cause and whose fix it is (developer, library team, CI templates or infrastructure). For BAR build failures it reads the mqsicreatebar log artifact and names the exact files that failed.
• Merge requests — status, conflicts, approvals, how far behind, and changed files.
• Old flow → v2 migration — "migrate emtf-calcchsp to v2" or "how far is company-management with the v2 migration?" For a service, Orbit pins the library tags whose content matches what the old flow builds today, shows where those library configs are promoted, lists every custom-build/ACE_Deployment.yaml setting v2 would silently drop (with the exact values-<env>.yaml overrides to add), checks for prod hotfixes missing from the release source and for schedulers without SERVICE_TYPE, and generates the new .gitlab-ci.yml and build.properties plus the steps. For a module it shows which services are migrated and whether the shared-lib is ready. Services already on v2 are audited the same way. Name an environment ("migrate it to v2 on stg-oci first") and the plan is a feature-branch trial whose library pins and build.properties match what that environment runs today, including checks for the old OCI pipeline still deploying there.

The rules Orbit applies are documented in _agent_reference/cicd/gitlab-deployment.md. Orbit only reads: it never pushes, merges, approves, runs jobs or changes anything on GitLab, and the token is not saved in cloned repos.

| Problem | Fix | |---|---| | Cannot reach GitLab … (ENOTFOUND / ETIMEDOUT) | Connect the VPN; check the URL with /gitlab status | | TLS certificate error | Set NODE_EXTRA_CA_CERTS to your company root CA (.pem) | | 401 / 403 | Token expired or missing the read_api / read_repository scope — run /gitlab again | | Requests go to your internet proxy | Add the GitLab host to NO_PROXY |

Agent Routing

Route different agent tasks to different models. Define each model's connection in agentModels, then map agents (or default) to those names in agentRouting. Every name used in agentRouting must exist in agentModels:

// ~/.orbit/settings.json
{
  "agentModels": {
    "gemini-3.1-pro-preview":  { "base_url": "https://generativelanguage.googleapis.com/v1beta/openai", "api_key": "your-gemini-key" },
    "gemini-3.5-flash-lite":   { "base_url": "https://generativelanguage.googleapis.com/v1beta/openai", "api_key": "your-gemini-key" }
  },
  "agentRouting": {
    "Explore": "gemini-3.5-flash-lite",
    "Plan": "gemini-3.1-pro-preview",
    "default": "gemini-3.5-flash-lite"
  }
}

gRPC Server Mode (source build only)

From a source checkout (not the npm package), run Orbit as a headless gRPC service on localhost:50051:

bun run dev:grpc

Connect your own client using src/proto/orbit.proto — clients can be generated in Python, Go, Rust, or any gRPC-supported language. This mode requires the repository; it is not included in the published npm package.

Source Build

bun install
bun run build
node dist/cli.mjs

Useful dev commands:

bun run dev          # build + run
bun run smoke        # build + version check
bun run doctor:runtime   # system diagnostics
bun run verify:privacy   # confirm no telemetry
bun test             # unit tests

Requirements

• Node.js >= 20.0.0
• An API key for your chosen provider (or a running Ollama instance)
• IBM ACE toolkit (for the integration projects Orbit assists with — not required to run Orbit itself)

Disclaimer

Orbit AI is an independent project and is not affiliated with, endorsed by, or sponsored by IBM, Anthropic, or Google.

License

See LICENSE.