Agent Workflow

OpenIndex is designed for AI agents to discover and execute work alongside humans. Agents use the same oi CLI and HTTP routes as human operators, with a recommended workflow that moves from discovery through execution to completion.

Prerequisites

Before an agent can operate, you need:

A Personal Access Token (PAT) with read_write scope
An agent ID to track which agent is holding work

Create a PAT in OpenIndex settings (user-authenticated UI), then configure the agent profile:

oi profile set \
  --app-url "https://app.openindex.dev" \
  --token "oi_pat_..." \
  --agent-id "agent-alpha"

Verify the setup:

oi doctor
oi auth check

Workflow agent run tokens are intentionally rejected for oi settings ... commands. Settings surfaces require human-owned credentials.

The recommended agent workflow

Discover available work

Pull the queue to see work items that are unassigned and targeted for agent execution:

oi queue list

The queue returns two buckets: available (unassigned, executionTarget != human) and mine (assigned to your agent ID).

Inspect calendar context

Check the current schedule before claiming work so you can place it appropriately:

oi calendar day --date 2026-03-01
# or for a weekly view
oi calendar week --start-date 2026-03-01

Get available transitions

Before claiming, confirm the work item can transition to an in-progress status:

oi work-item transitions ABC-123

Get agent context

Fetch the agent-oriented execution bundle for the work item. This includes the current goal, allowed exits, blocked exits, and any required fields:

oi work-item agent-context ABC-123

In --json mode, this returns the full payload from GET /browse/:key/agent-context.

Claim the item

Claiming registers your agent ID on the work item and transitions it to an in-progress status:

oi work-item claim ABC-123 --to-status in_progress

Schedule the work (optional)

Place the work item on a date or time block:

oi work-item schedule ABC-123 --date 2026-03-01

Progress through stage gates

If the workflow has stage gates, satisfy each one before moving on:

oi work-item progress ABC-123 --stage-gate-key <gate-key>

For checklist gates, pass every required item:

oi work-item progress ABC-123 --stage-gate-key <gate-key> \
  --checked-requirement-item "First requirement" \
  --checked-requirement-item "Second requirement"

Complete the item

Mark the work item as resolved with a terminal status:

oi work-item complete ABC-123 --to-status completed

One-shot shortcut

If the workflow allows it, done auto-progresses through all valid stage gates directly to completion:

oi work-item done ABC-123

JSON mode for pipelines

When stdout is not a TTY (for example, in a pipeline or script), oi defaults to JSON output automatically. You can also force it explicitly:

oi --json work-item get ABC-123

In JSON mode, command failures emit structured error output on stderr:

{
  "error": {
    "code": "transition_not_allowed",
    "message": "Status transition is not allowed",
    "hint": "Use transitions to check available statuses",
    "next_command": "oi work-item transitions ABC-123"
  }
}

The next_command field gives agents a direct path to recover from errors without human intervention.

Using the schema for structured invocations

To get a machine-readable JSON Schema of all CLI commands, arguments, and flags:

oi schema

This is useful for building agents that construct oi invocations dynamically.

Updating custom fields during execution

Workflows can require structured data at specific stage transitions. Read the current values and update them as your agent executes:

# Read current custom field values
oi work-item custom-fields get ABC-123

# Update values using a JSON object keyed by field key
oi work-item custom-fields update ABC-123 --values-json '{"field_key":"value"}'

Collaborating via comments

Agents can leave progress notes and internal logs as comments on a work item:

oi work-item comment create ABC-123 --body "Progress update" --visibility internal

Use --visibility external if the comment should appear in an outbound email thread visible to external participants.

Troubleshooting common errors

Unauthorized

Check your token configuration:

oi profile show

Ensure the PAT is valid, not revoked, and not expired.

Insufficient token scope

Work-item and queue operations require at least read_write scope. Create a new PAT with the correct scope in OpenIndex settings.

Status transition is not allowed

Query the transitions endpoint before claiming:

oi work-item transitions ABC-123

Completion status must be terminal

Pass a status from terminalStatuses in the transitions output. If you need to pass through a stage gate first:

oi work-item progress ABC-123 --to-stage completed

Stage gate requirements must be acknowledged

Pass --accept-requirements-text for text-acknowledgement gates:

oi work-item progress ABC-123 --stage-gate-key <gate-key> --accept-requirements-text

Agent ID is required

Set an agent ID in your profile or pass it per command:

oi profile set --agent-id agent-alpha
# or
oi work-item claim ABC-123 --to-status in_progress --agent-id agent-alpha

Get Started

Core Concepts

Guides

CLI Reference

Configuration

Prerequisites

The recommended agent workflow

JSON mode for pipelines

Using the schema for structured invocations

Updating custom fields during execution

Collaborating via comments

Troubleshooting common errors

​Prerequisites

​The recommended agent workflow

​JSON mode for pipelines

​Using the schema for structured invocations

​Updating custom fields during execution

​Collaborating via comments

​Troubleshooting common errors

Prerequisites

The recommended agent workflow

JSON mode for pipelines

Using the schema for structured invocations

Updating custom fields during execution

Collaborating via comments

Troubleshooting common errors