EngineerOS Connector

The connector uses an authenticated EngineerOS WebSocket for pairing, workspace identity, run lifecycle, and evidence. Coding work can run through any agent in the official ACP registry or a custom ACP v1-compatible command over stdio. Direct Codex CLI remains available as the compatibility path.

Connect an official ACP agent

EngineerOS reads the curated ACP agent registry, caches it for 24 hours, and uses the registry's pinned distribution for the current platform. The catalog includes Codex, Claude, Gemini, GitHub Copilot, Goose, OpenCode, Qwen Code, Cursor, and other compatible agents as they are published. List the current catalog, prepare the selected agent, then pair the workspace:

npx --yes @engineeros/connector@latest agents
npx --yes @engineeros/connector@latest agent gemini install
npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engineeros.example --workspace . --onboard --agent gemini

Registry npx and uvx packages are prepared with their native package runner. Registry binaries are downloaded into ~/.engineeros/agents, checked against the published SHA-256 digest when present, and launched from that managed location. The connector checks the selected distribution before pairing. Agent processes stay alive while the connector is active, project conversations reuse their ACP sessions, and response chunks reach Copilot as the agent produces them.

Pair an ACP coding agent

Run the command from the repository the agent should work in:

npx --yes @engineeros/connector@latest pair PAIRING-CODE --url http://localhost:8000 --workspace . --onboard --agent-name "My ACP agent" --agent-command my-agent --agent-args '["--acp"]'

--agent-command must start an ACP v1 agent over NDJSON stdio. --agent-args is a JSON array so arguments are passed without invoking a shell. Omit --agent and the custom command options to use the installed Codex CLI directly.

Connect a local Codex CLI workspace to EngineerOS through an outbound WebSocket.

Agent roles and skills

The selected ACP or Codex agent is the execution engine. EngineerOS chooses a provider-neutral role for each activity and the connector injects only that role's bundled skill:

• research uses codebase-research with read-only access for questions and workspace assessment.
• planning uses change-planning with read-only access for shaping, specifications, architecture, and design work.
• implementation uses goal-execution with workspace-write access only for a registered Goal.
• verification uses change-verification with read-only access for artifact review and independent Goal proof.

The connector rejects a role whose access does not match the assignment before starting the agent. Role-specific sessions preserve useful context without mixing planning, research, implementation, or verification responsibilities. A shared interaction contract makes the Agent infer the current project situation, lead with the useful outcome, and suggest one concrete next activity only when it genuinely helps. User-visible responses refer neutrally to the Agent; provider and harness details remain operational metadata.

Onboard a workspace

Create a connection command from Project steering -> Connect workspace, then run it inside the local folder:

npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engineeros.example --workspace . --onboard

The connector uploads a bounded ZIP snapshot for a safe file inventory, then stays online for deep assessments, rescans, and Goal Runs. Inventory never executes repository code. It excludes known secrets, dependency directories, build output, compiled binaries, files larger than 5 MB, agent-tool caches, Git metadata, and connector state before upload.

From Project steering -> Workspace, run the workspace assessment to use the connected agent subscription already authenticated on that computer. EngineerOS stores the source-cited findings in System State and promotes the highest-return corrective action in Steering. Assessment cannot modify the workspace.

After onboarding, every project prompt is routed to this connection. Copilot, shaping, planning, architecture, and experience generation use the connected agent subscription and workspace context. Interactive prompts run independently from assessments and Goal scheduling. Prompt runs are read-only; only an explicitly registered Goal Run receives workspace-write access. If the connector is offline, EngineerOS asks the user to reconnect instead of silently switching models.

Project prompts use resumable, role- and purpose-specific agent sessions. The connector keeps the external session identifiers in its local configuration, so Copilot and artifact conversations survive connector restarts. Changing the role, purpose, model, or reasoning effort starts a separate session. Goal implementation and verification remain isolated runs.

An empty or document-only folder establishes a greenfield baseline. A code-bearing folder is assessed as brownfield. Use Rescan in Steering after the local workspace changes.

Reconnect

npx --yes @engineeros/connector@latest start --workspace .

Credentials are stored per workspace under ~/.engineeros/connectors with owner-only permissions where supported. If a new pairing command is accidentally run from the same folder against the same EngineerOS server, the connector reuses this saved identity instead of creating another baseline assessment.

Run Goals

Keep the connector online to receive Goals assigned from EngineerOS. Each Goal runs in an isolated worktree below ~/.engineeros/runs. Cancellation stops the agent. The connector returns changed paths, a bounded diff, and the exact repository ZIP; a human still performs independent attestation.

During the writable implementation phase, Codex receives an authenticated EngineerOS MCP server automatically. It can list, read, create, update, reclassify, soft-delete, and materialize project artifacts into canonical Product records through the same repository boundary used by Copilot. The backend accepts those calls only while the assigned Goal is running. Read-only project prompts and the independent verification phase do not receive mutation tools.

Requirements: Node.js 22 or newer, Git, and an authenticated agent. npx distributions use npm, uvx distributions require uv, and binary archives require tar (unzip for ZIP files on Linux). Registry agents report their own authentication prerequisites when they start.

Execution profiles

EngineerOS can set a workspace default model and reasoning effort, then override either value for an individual Goal. The same workspace default is used for assessments, Copilot, and generated artifacts. The connector passes the resolved values to Codex CLI and reports unsupported profiles instead of silently ignoring them.

Codex connectors advertise gpt-5.6-sol and gpt-5.6-terra by default. Override the choices shown in EngineerOS before starting the connector:

ENGINEEROS_AGENT_MODELS="model-a,model-b" npx @engineeros/connector start --workspace .

Codex CLI compatibility

The connector prints the exact Codex CLI version it will use before connecting. If the configured model requires a newer CLI, update Codex and restart the connector:

npm install -g @openai/codex@latest
codex --version
npx @engineeros/connector start --workspace .

Publish the connector

Run the release workflow from this package instead of calling npm publish directly:

npm run release:patch

The workflow checks the versions already present on npm, keeps the current version when it is unpublished, or advances to the next unused patch version when necessary. It then runs the connector tests, syntax checks, and package dry run before publishing. A direct npm publish now stops early with the corrective command when its version already exists.