Run Codex And Claude Code As External Agents

Codex and Claude Code can participate in IntuitivePM agent orchestration when they run behind an approved external agent runtime.

The runtime bridge connects to IntuitivePM, receives work, fetches task details, and heartbeats active leases. Codex or Claude Code remains the executor that reads the task, performs the work in the approved workspace, and writes progress or completion comments back to IntuitivePM.

What The Runtime Does

The managed runtime:

• Exchanges approved agent credentials for a short-lived token.
• Connects to the IntuitivePM runtime WebSocket.
• Announces runtime.ready.
• Receives work.available notifications.
• Fetches authoritative task details from the Agent API.
• Heartbeats the active lease while the runtime remains connected.
• For orchestrator runtimes, receives review.available, claims an explicit review lease, heartbeats that review lease, emits review progress, and accepts, returns, or escalates through the Orchestrator API.
• Reconnects after token refresh, restart, or temporary network loss.

It does not execute arbitrary shell commands and does not mark work complete by itself. A production setup also needs an executor adapter that invokes Codex or Claude Code with approved task context, captures output, writes task comments, and completes or fails the lease through IntuitivePM.

Runtime Bridge Versus Executor

Keep these separate. The bridge should not become an unrestricted command runner.

Before You Start

You need:

• An Enterprise IntuitivePM workspace.
• Company administrator access to System -> Integrations -> Agent Registry.
• An approved external agent identity for each external tool.
• A client ID, client secret, and runtime ID for each runtime.
• Bun installed on the Ubuntu machine.
• Codex or Claude Code installed and configured according to your company’s policy.
• The approved IntuitivePM external runtime package or container image. See External Runtime Packages.
• A dedicated OS user, container, or Kubernetes pod for each live executor runtime.

Recommended Agent Setup

Create separate external agent identities for orchestration and execution.

Keep scopes as narrow as possible. Add file write or orchestration control scopes only when the agent actually needs them.

For orchestrators, keep IPM_AGENT_ORCHESTRATOR_REVIEW_ENABLED=true unless your company wants a human-only review queue. The managed reviewer is intentionally conservative: it accepts only ready work with completion evidence, a passing quality preview, no failed criteria, and no caveats. It returns uncertain work with feedback instead of guessing.

The review lease includes a snapshot of the effective retry policy. Managed orchestrator runtimes honor the configured maximum automated review returns and escalate after the limit instead of repeatedly sending the same work back to In Progress.

Managed runtimes also treat waitingOnUser, waitingOnOrchestrator, and needsReload as manual pause states. They skip those items during review queue polling, and the backend rejects new automated review lease claims for them until a user or orchestrator resolves the waiting reason.

Managed orchestrator runtimes also send live review progress phases for claiming, checking evidence, checking Git/CI context, accepting, returning, escalating, completing, and failure. These phases are for visibility only; the review decision still writes a durable comment and history entry.

In the IntuitivePM task modal, reviewers and admins can see the active review owner/runtime, review attempt number, current review status, retry feedback, and escalation details. Board cards keep showing an orchestrator review badge from the task’s durable reviewing state when transient progress events have expired.

IPM_AGENT_ORCHESTRATOR_REVIEW_POLL_SECONDS controls the fallback polling interval for missed review.available events. Set it to 0 only when your company wants WebSocket wake events to be the only automated Review trigger.

Install The Managed Runtime

On the Ubuntu machine, unpack the approved IntuitivePM external runtime package, then run the runtime manager with an instance name. Do not deploy the full IntuitivePM application repository for normal customer runtimes.

Most administrators should copy the generated setup command from System -> Integrations -> Agent Registry. That command fills in the approved agent identity, runtime ID, runtime label, executor workspace, and smoke-mode settings.

If you are preparing the command manually, use placeholders and enter the secret at the prompt:

bun scripts/intuitivepm-agent-runtime.ts install claude-code-agent

read -r -s -p "Client secret: " IPM_AGENT_CLIENT_SECRET
echo

IPM_AGENT_CLIENT_SECRET="$IPM_AGENT_CLIENT_SECRET" bun scripts/intuitivepm-agent-runtime.ts configure claude-code-agent \
  --client-id <client-id> \
  --runtime-id <runtime-id> \
  --runtime-label "Ubuntu Claude Code Agent" \
  --executor-enabled true \
  --executor-workspace-root "$HOME/intuitivepm-agent-workspaces/claude-code-agent" \
  --smoke-mode true

unset IPM_AGENT_CLIENT_SECRET

The installer creates:

~/.local/share/intuitivepm-agent-runtime/external-agent-runtime.ts
~/.config/intuitivepm-agent-runtime/claude-code-agent.env
~/.config/intuitivepm-agent-runtime/claude-code-agent.manifest.json
~/.config/systemd/user/intuitivepm-agent-runtime@.service

Validate and start the service:

bun scripts/intuitivepm-agent-runtime.ts validate claude-code-agent
bun scripts/intuitivepm-agent-runtime.ts enable claude-code-agent

Watch the logs:

bun scripts/intuitivepm-agent-runtime.ts logs claude-code-agent --follow

Expected log events include:

connected
runtime.connected
runtime.ready:ack
pong

For boot without an interactive login, ask an administrator to enable linger for the service account:

sudo loginctl enable-linger <linux-user>

Configure Codex Orchestrator

Use a separate runtime instance for Codex when it acts as the orchestrator:

bun scripts/intuitivepm-agent-runtime.ts install codex-orchestrator

read -r -s -p "Client secret: " IPM_AGENT_CLIENT_SECRET
echo

IPM_AGENT_CLIENT_SECRET="$IPM_AGENT_CLIENT_SECRET" bun scripts/intuitivepm-agent-runtime.ts configure codex-orchestrator \
  --client-id <client-id> \
  --runtime-id <runtime-id> \
  --runtime-label "Ubuntu Codex Orchestrator" \
  --executor-enabled false

unset IPM_AGENT_CLIENT_SECRET

bun scripts/intuitivepm-agent-runtime.ts validate codex-orchestrator
bun scripts/intuitivepm-agent-runtime.ts enable codex-orchestrator
bun scripts/intuitivepm-agent-runtime.ts logs codex-orchestrator --follow

Use the Codex orchestrator agent credentials and runtime ID from Agent Registry.

Configure Claude Code Execution

Use a separate runtime instance for Claude Code when it acts as an execution agent:

bun scripts/intuitivepm-agent-runtime.ts install claude-code-agent

read -r -s -p "Client secret: " IPM_AGENT_CLIENT_SECRET
echo

IPM_AGENT_CLIENT_SECRET="$IPM_AGENT_CLIENT_SECRET" bun scripts/intuitivepm-agent-runtime.ts configure claude-code-agent \
  --client-id <client-id> \
  --runtime-id <runtime-id> \
  --runtime-label "Ubuntu Claude Code Agent" \
  --executor-enabled true \
  --executor-workspace-root "$HOME/intuitivepm-agent-workspaces/claude-code-agent" \
  --smoke-mode true

unset IPM_AGENT_CLIENT_SECRET

bun scripts/intuitivepm-agent-runtime.ts validate claude-code-agent
bun scripts/intuitivepm-agent-runtime.ts enable claude-code-agent
bun scripts/intuitivepm-agent-runtime.ts logs claude-code-agent --follow

Use the Claude Code execution agent credentials and runtime ID from Agent Registry.

Send A Smoke Task

Create a small task in IntuitivePM:

Confirm that the external agent receives delegated work through IntuitivePM.
No code changes required.
When received, add a task comment saying the runtime received the task.

Then:

1. Assign the task to the correct human owner.
2. Select the approved external agent.
3. Move the task to In Progress.
4. Confirm the service logs show work.available.
5. Confirm the runtime logs work fetched.
6. Let Codex or Claude Code add the required task comment.
7. Move the task to Review after the evidence is present.

Working Pattern

For Codex as orchestrator:

1. Keep the runtime service enabled.
2. Use fetched task details to decide whether work should be split, delegated, reviewed, or returned.
3. Write planning decisions and review feedback as task comments.
4. Keep IntuitivePM as the source of truth for status and assignment changes.

For Claude Code as execution agent:

1. Keep the runtime service enabled.
2. Read the fetched task details and acceptance criteria.
3. Perform the requested work in the approved workspace.
4. Write progress, questions, tests run, caveats, and completion evidence as task comments.
5. Move work to Review only when the assigned task or subtask is complete.

Executor Adapter Requirements

For Enterprise use, an executor adapter should define:

• the allowed command or tool to run
• the approved working directory and repositories
• which Work Files, inputs, templates, and outputs are available
• timeout and cancellation behavior
• stop/reload handling when a task changes while running
• what logs are retained and where
• the required completion comment format
• when to complete, release, or fail a lease
• when to submit work to Review

The adapter should use named IntuitivePM runtime capabilities for comments, leases, waiting states, and review requests. It should not turn the runtime bridge into an unrestricted command runner or a general API proxy.

With managed runtime package ao37.11, the adapter polls IntuitivePM while Codex or Claude Code is running. If a task is reloaded, the adapter stops the child process, records the run as reloaded, releases the lease, and waits for fresh task context. If a task is stopped, the adapter cancels the run, reports stopped progress, and prevents old output from moving to Review. Orchestrator runtimes can also receive review.available, claim a review lease, read the retry policy snapshot, emit review progress, and make the conservative automated Review decision. Live Claude Code executor runs also send periodic progress heartbeats while the child process is active so board cards keep showing that the agent is working during longer tasks.

The adapter should never bypass IntuitivePM review or move work directly to Done.

Managed adapters include the task’s execution-agent instructions, orchestrator/reviewer instructions, and completion-evidence expectations in the executor prompt. Put operational constraints and review expectations in those task fields instead of relying only on comments.

The managed Claude Code adapter is disabled by default. Enable it only after reviewing the generated manifest:

bun scripts/intuitivepm-agent-runtime.ts configure claude-code-agent \
  --executor-enabled true \
  --executor-workspace-root "$HOME/intuitivepm-agent-workspaces/claude-code-agent" \
  --smoke-mode true

Keep smoke mode enabled for the first validation task. Smoke mode validates the full IntuitivePM workflow without invoking Claude Code.

Turn smoke mode off only after the workspace, command, permissions, and company policy are confirmed:

bun scripts/intuitivepm-agent-runtime.ts configure claude-code-agent --smoke-mode false

If the runtime is not yet approved for continuous live execution, restore smoke mode after the live validation:

bun scripts/intuitivepm-agent-runtime.ts configure claude-code-agent --smoke-mode true

For Claude Code runtimes, live execution uses safe edit mode inside the approved workspace. The runtime should not be configured with bypass permission mode, and administrators should keep the workspace path narrow.

The managed runtime writes a protected local JSON run log for each adapter run. Completion comments include a run ID and local log reference so an administrator can inspect what happened on the Ubuntu machine without exposing secrets in IntuitivePM comments.

Workspace evidence is checked before the lease is completed. docsTouched and filesChanged must be none, not run, relative paths inside the approved workspace, or absolute paths inside an approved workspace path.

Optional: Register A Runtime By API

Most administrators should use System -> Integrations -> Agent Registry. If your company allows API-based registration, use placeholders and store the secret safely:

export IPM_API_BASE='https://api.intuitivepm.net'
export IPM_AGENT_CLIENT_ID='<client-id>'
read -r -s -p "Client secret: " IPM_AGENT_CLIENT_SECRET
echo
export IPM_AGENT_CLIENT_SECRET

bun -e '
const response = await fetch(`${process.env.IPM_API_BASE}/api/agent-auth/runtimes/register`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    clientId: process.env.IPM_AGENT_CLIENT_ID,
    clientSecret: process.env.IPM_AGENT_CLIENT_SECRET,
    name: "Ubuntu Claude Code Agent",
    runtimeType: "bun",
    deliveryMode: "websocket",
    specializationTags: ["coding"],
    capabilityTags: ["task-execution", "comments"],
    environmentTags: ["ubuntu", "workstation"],
    maxConcurrentWork: 1,
  }),
});
console.log(JSON.stringify(await response.json(), null, 2));
'

If the response says approval is required, a company administrator must approve the runtime before it can receive work.

Troubleshooting

Related Guides

• Agent Orchestration
• Agent Orchestration Architecture & Security
• Set Up Agent Orchestration
• Connect External Agent Runtimes
• External Runtime Packages
• Assign Work To Agents