# UX Flow: Codex Agents

Last updated: 2026-05-14.

## Launcher entitlement UX

Launcher grants access to the module. It does not configure individual agents.

### Open contour

Current open-contour Operational Core access is a dropdown with:

- workspace member;
- service admin;
- blocked.

Target UX: replace this dropdown with a modal aligned with enterprise access modals.

Modal structure:

```text
Operational Core access
  Role:
    - Workspace member
    - Service admin
    - Blocked

Operational Core modules
  Codex agents: on/off
```

This keeps the existing role decision but makes room for module-level entitlements.

### Enterprise contour

The existing enterprise Operational Core access modal should gain a bottom section:

```text
Operational Core modules
  Codex agents: on/off
```

It must coexist with current controls:

- client;
- service;
- NODE.DC user;
- global status;
- workspace/project assignment;
- role assignment.

The module toggle is independent from project assignment. A user may have Tasker access without Codex-agent access.

## Tasker workspace settings UX

Location:

```text
Workspace settings -> Features
```

The `Codex agents` feature appears only when Launcher entitlement is present.

Feature card:

```text
Codex agents
Connect local Codex or compatible AI agents to maintain work items in this workspace.
```

Controls:

- enable/disable feature for workspace;
- create agent;
- list agents;
- revoke agent;
- show last activity;
- open agent setup instructions.

The toggle/checker should use the NODE.DC round checker style, not a browser checkbox. If an existing reusable switch from `AI Voice Tasker` is suitable, extract it into a shared component instead of duplicating local styling.

## Agent create flow

Steps:

1. User opens `Codex agents`.
2. User clicks `Create agent`.
3. User enters agent name.
4. User optionally chooses avatar.
5. User chooses allowed projects.
6. User chooses capability preset.
7. System creates agent and one-time pairing code.
8. UI shows setup instructions for local Codex.

Recommended capability presets:

```text
Task author
  create/update/move/comment/label/assign/structured blocks

Reporter
  read/update/comment/structured blocks/work sessions

Read-only reviewer
  read only
```

MVP should focus on `Task author`.

## Agent setup UX

The UI should provide:

- copy MCP endpoint;
- copy environment variable name;
- generate one-time pairing code;
- download instruction file;
- show allowed workspace/project list;
- show revoke button.

The token itself should be returned once, shown masked in the active setup packet, and never returned by the backend again.
The frontend may keep the full secret only in the current browser session for copy actions until reload/navigation.

Recommended user-facing artifact:

```text
OPS_AGENT.md
```

This file contains instructions, not the raw secret. Secrets should be passed through environment variables or Codex secret storage.

## Card management UX expectations

Codex agents should follow NODE.DC task-card structure:

- concise card title;
- conceptual description;
- `Current architecture` text block when relevant;
- stage text blocks;
- checker blocks;
- implementation notes after real work;
- validation notes;
- no top-level card spam for substeps of one product topic.

For cards created by agents, UI should make the author clear:

```text
Created by Codex Agent: <name>
Owner: <human user>
```

## Voluntary scenario

The user explicitly asks local Codex to maintain Tasker.

Example flow:

```text
User: We agreed on the architecture. Go create Tasker cards for this in project X.
Codex: calls tasker_create_issue and tasker_update_structured_blocks.
User: Implement stage 1.
Codex: updates checker and appends implementation note.
```

## Reporting scenario

The organization expects developers to report through Tasker while working with Codex.

UX should expose:

- connected/not connected agent status;
- last activity;
- stale report indicator;
- active work session;
- last updated card;
- missing report warning.

Important limitation: local Codex cannot be forced to report unless it is launched with a managed config/wrapper. The system can show missing reports and enforce API scope, but it cannot control an arbitrary external agent process.