Skip to main content
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.
1

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).
2

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
3

Get available transitions

Before claiming, confirm the work item can transition to an in-progress status:
oi work-item transitions ABC-123
4

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.
5

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
6

Schedule the work (optional)

Place the work item on a date or time block:
oi work-item schedule ABC-123 --date 2026-03-01
7

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"
8

Complete the item

Mark the work item as resolved with a terminal status:
oi work-item complete ABC-123 --to-status completed
9

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

Check your token configuration:
oi profile show
Ensure the PAT is valid, not revoked, and not expired.
Work-item and queue operations require at least read_write scope. Create a new PAT with the correct scope in OpenIndex settings.
Query the transitions endpoint before claiming:
oi work-item transitions ABC-123
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
Pass --accept-requirements-text for text-acknowledgement gates:
oi work-item progress ABC-123 --stage-gate-key <gate-key> --accept-requirements-text
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