The Problem

Developers who work with multiple LLM providers (Claude, Codex, etc.) need a single, local‑first environment to author, schedule, and observe autonomous “agents” without sending proprietary data to the cloud. Existing solutions are either SaaS‑only or require heavyweight server setups, creating friction for privacy‑focused teams.

What This Does

Ordinus is an Electron desktop app that lets you compose agents from your own CLI‑based LLM back‑ends and wire them together in a DAG‑style workflow designer. Core source lives under app/:

  • Main process – entry point app/src/main/index.ts boots Electron, registers IPC channels (app/src/main/ipc/register) and starts provider‑specific MCP servers (app/src/main/ordinus-mcp/server.ts).
  • Renderer – UI lives in app/src/renderer/ (e.g., App.tsx) and communicates with the main process via the IPC hub.
  • Persistence – a SQLite‑backed layer in app/src/main/db/database.ts stores workspace config, agent definitions, and run history.
  • Runtime adapters – app/src/main/runtime/adapters/claude/adapter and …/codex/adapter translate generic task calls into provider‑specific CLI invocations.

All configuration files (app/electron-builder.yml, app/electron.vite.config.ts) are already in place, and the UI is styled with Tailwind.

How It Is Wired

  1. Startup – The Node entry app/src/main/index.ts creates the Electron BrowserWindow, loads the Vite‑built renderer, and calls registerIpc() from app/src/main/ipc/register.
  2. IPC Hub – registerIpc imports 27 internal modules (the most outgoing edges in the graph) and exposes functions such as runWorkflow, fetchAgent, and persistState. These are the only public surface the renderer touches.
  3. Workflow Execution – When the UI dispatches a run, the IPC handler invokes app/src/main/runtime/index.ts, which selects the appropriate adapter (claude or codex) based on the agent’s provider field stored in the SQLite DB (app/src/main/db/database.ts).
  4. Provider Adapter – Each adapter builds a CLI command line, spawns a child process, and streams stdout/stderr back through IPC to the renderer. The adapters import 17–18 modules each, giving them a high instability score (≈0.95).
  5. Persistence – All state changes funnel through app/src/main/db/database.ts (≈5 866 lines, a high‑cognitive‑load module). It exports getWorkspace, saveRun, and queryRuns, which are called by the IPC layer, the runtime, and the UI.
  6. Path Hub – app/src/main/paths.ts is a pure‑utility module with zero outgoing imports but 16 incoming ones, acting as the canonical source for file‑system locations (e.g., resources/, userData/).

No circular dependencies were detected; the import graph consists of 240 modules and 361 edges. The widest blast radius belongs to registerIpc (27 imports) and the DB layer (multiple callers across UI, runtime, and MCP servers).

How To Use It

# Clone the repo
git clone https://github.com/moses-y/ordinus.git
cd ordinus/app

# Install exact dependency tree
npm ci

# Start the Electron app (script defined in app/package.json)
npm run start

The repository does not contain a Dockerfile or explicit build scripts, so the standard npm workflow is the only documented path. Configuration files such as app/electron-builder.yml control packaging, while provider credentials are expected to be stored encrypted by the UI (no env‑var names are present in the source).

Real‑World Use

A content team could define an “Article Writer” agent that calls a local Claude CLI, then chain it to a “SEO Optimizer” agent using the Codex CLI. The workflow is built in the visual designer, scheduled via the built‑in planner, and all drafts are persisted locally in the SQLite DB. Running the workflow triggers the two adapters, streams results back to the workboard, and allows a human operator to intervene if needed.

Code Health & Issues

Measured audit (8 findings)

  • HIGH – Pin GitHub Actions to commit SHA (.github/workflows/*).
  • HIGH – No test suite (236 source files, 0 tests).
  • MEDIUM – Enable Dependabot/Renovate (.github/dependabot.yml).
  • MEDIUM – Add dependency‑vulnerability scan in CI.
  • MEDIUM – Remove generated build output from VCS (app/build/*).
  • MEDIUM – Set persist-credentials: false on checkout step.
  • LOW – Define timeout-minutes on workflow jobs.
  • LOW – Add missing convention files (.editorconfig, .gitattributes).

Static findings (44 total)

  • HIGH/cognitive_load – Oversized files (e.g., app/src/main/db/database.ts, app/src/shared/contracts.ts).
  • HIGH/clarity – Duplicated 6‑line blocks across server and DB modules.
  • HIGH/cognitive_load – Deep nesting (max depth 8) in several renderer components (plan-queue.tsx, settings-screen.tsx).
  • MEDIUM/clarity – Hub modules (ordinus-tools/types.ts, paths.ts) with many dependents.
  • MEDIUM/cognitive_load – High branching density in CLI output handling (runtime/cli/output.ts).
  • MEDIUM/resilience – Empty catch blocks in docs scripts.

No critical vulnerabilities, no committed secrets, and CI is present, but the lack of tests and several high‑cognitive‑load modules suggest a steep learning curve for new contributors.

The Bottom Line

Ordinus delivers a functional, locally‑hosted Electron platform for orchestrating LLM‑backed agents, with a clear separation between UI, IPC, and provider adapters. The codebase is sizable and contains several large, tightly coupled modules, which hampers maintainability. It is suitable for teams that require strict data locality and are comfortable adding tests and refactoring the identified hotspots.