Optimus

Optimus is a task-execution agent runtime. It accepts problem reports, turns them into governed tasks, runs analysis or code changes against bound repositories, and returns status, results, and delivery outputs.

What It Does

• accepts manual submissions or external problem signals
• routes raw input into executable tasks
• runs analysis, fixes, validation, and delivery against registered repositories
• returns task status, structured results, review links, and notifications

How It Works

From a user view, the flow is simple: submit a problem, let Optimus run inside the target repository, validate the outcome, then consume the result and next action.

Quick Start

1. Install

npm install -g @sireai/optimus --registry=https://registry.npmjs.org

If Jira CAS refresh reports a missing Playwright browser, install Chromium once:

npx playwright install chromium

2. Run setup

optimus setup

Setup creates the ~/.optimus runtime home, configures Codex authentication, and records optional repository, Jira, Sentry, and Feishu delivery settings. Repository registration can be skipped during setup and added later with optimus repo add. Optimus always includes its built-in Feishu app for message delivery and analysis-document publishing. A Feishu webhook can be added during setup when group delivery should take priority. When Jira and Sentry are both enabled, setup also stores the Jira project key used to auto-create Jira issues for Sentry-origin patch publication.

Supported Codex auth modes:

• openai_api_key
• codex_cli_login
• model_provider

3. Check machine readiness

optimus doctor

4. Start the runtime

optimus start

submit sends work to the resident runtime, so start the service after setup.

5. Submit a task

optimus submit --title "Login crash" --description "Crash happens on startup with stack trace"

Common Commands

Base commands:

optimus --help
optimus help feedback
optimus version
optimus upgrade --check
optimus upgrade
optimus setup
optimus doctor
optimus start
optimus submit --title "..." --description "..."
optimus feedback --title "..." --description "..."

Task inspection:

optimus retry-task --task-id <taskId>
optimus cancel-task --task-id <taskId>
optimus task-status --task-id <taskId>
optimus task-result --task-id <taskId>
optimus delivery-status --task-id <taskId>
optimus task-events --task-id <taskId>

Repository management:

optimus repo add /path/to/repo --alias mobile-app
optimus repo list

Jira intake:

optimus jira-submit-issue --issue-key MICARAPPI-13178 --repo mobile-app
optimus jira-submit-issue --issue-key MICARAPPI-13178 --repo mobile-app --with-comments
optimus jira-refresh-auth --issue-key MICARAPPI-13178

jira-submit-issue now excludes Jira comments by default. Add --with-comments when recent comments should be included in the submit context. --comment-limit only applies when --with-comments is set.

Sentry intake:

optimus sentry-get-event --event-id 75d361c269bc40598c44e2eec75022f3
optimus sentry-submit-event --event-id 75d361c269bc40598c44e2eec75022f3 --repo mobile-app

Feedback Reporting

Use feedback when you want to report an Optimus product issue instead of submitting a task for repository execution:

optimus feedback --title "Upgrade prompt missing" --description "upgrade --check found 0.1.14 but start did not open the upgrade prompt."

This command writes a local feedback bundle under ~/.optimus/runtime/feedback, packages nearby runtime and runtime-trace logs when present, creates a Feishu feedback document, and sends a Feishu app message to the fixed feedback recipient with the document link.

More Docs

• Product PRD
• Architecture Design
• Development and Maintenance