# 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 shown once and never stored in frontend state longer than needed.

Recommended user-facing artifact:

```text
TASKER_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.