> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticket-rs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Codex

> Set up tk with OpenAI Codex for AI-powered issue tracking

Integrate **tk** with OpenAI Codex to give your AI assistant full context about your project's issues, priorities, and workflow.

***

## Codex Options

OpenAI Codex is available in multiple forms:

<CardGroup cols={2}>
  <Card title="Codex CLI" icon="terminal">
    Terminal-based agent installed locally via npm. Runs commands and edits code autonomously.
  </Card>

  <Card title="Codex Desktop" icon="desktop">
    Desktop application with GUI. Provides the same agent capabilities with a visual interface.
  </Card>
</CardGroup>

Both versions work with the same `.tickets/` directory via git, so issues created in one are immediately available in the other.

***

## Recommended Setup

### Step 1: Install Codex CLI

```bash theme={null}
npm install -g @openai/codex
```

### Step 2: Install tk and Initialize

```bash theme={null}
# Install tk
curl -fsSL https://ticket-rs.io/install.sh | sh

# Initialize .tickets/ directory
tk init

# Commit and push
git add .tickets/
git commit -m "feat: add tk issue tracking"
git push
```

### Step 3: Add AGENTS.md

Create or update your `AGENTS.md` file so Codex has context about tk:

```markdown theme={null}
## Issue Tracking

This project uses **tk (ticket-rs)** for issue tracking.
Run `tk prime` for workflow context.

**Quick reference:**
- `tk ready` - Find unblocked work
- `tk create "Title" -t task -p 2` - Create issue
- `tk close <id>` - Complete work
- `tk triage` - AI-powered recommendations
```

<Tip>
  Run `tk onboard` to get a copy-pasteable snippet for your AGENTS.md.
</Tip>

***

## Codex CLI Setup

### Using tk with Codex CLI

Codex CLI reads `AGENTS.md` automatically. Once tk is installed and `AGENTS.md` is configured, Codex can use tk commands directly.

Start a session and ask Codex to use tk:

```bash theme={null}
codex "What should I work on next? Use tk triage to find out."
```

### Injecting Context

For richer context at session start, pipe `tk prime` output to Codex:

```bash theme={null}
codex "$(tk prime) -- Based on the above context, what should I work on?"
```

Or create a wrapper script:

```bash theme={null}
#!/bin/bash
# codex-tk.sh - Start Codex with tk context
CONTEXT=$(tk prime 2>/dev/null)
codex "$CONTEXT

Based on the project state above, help me with: $*"
```

### CLI Advantages

<CardGroup cols={2}>
  <Card title="Terminal-First" icon="terminal">
    Runs in your existing terminal workflow
  </Card>

  <Card title="Full Autonomy" icon="robot">
    Can run tk commands, edit code, and manage issues
  </Card>

  <Card title="Local Performance" icon="gauge-high">
    Direct access to your local development environment
  </Card>

  <Card title="Git Access" icon="code-branch">
    Full access to git history and repository
  </Card>
</CardGroup>

***

## Codex Desktop Setup

### Using tk with Codex Desktop

1. Open Codex Desktop and navigate to your project
2. Codex reads `AGENTS.md` from the repository root
3. Ask Codex to work with issues using tk commands

### Desktop Advantages

<CardGroup cols={2}>
  <Card title="Visual Interface" icon="desktop">
    GUI for reviewing agent actions and approving changes
  </Card>

  <Card title="Session History" icon="clock-rotate-left">
    Browse past sessions and their outcomes
  </Card>
</CardGroup>

***

## Working with Codex

Once configured, Codex can help you:

### Find Work to Do

Ask Codex: *"What should I work on next?"*

Codex will use `tk ready` and `tk triage` to recommend the highest-impact work.

### Create Issues

Ask Codex: *"Create an issue for adding dark mode support"*

Codex will run:

```bash theme={null}
tk create "Add dark mode support" -t feature -p 2
```

### Manage Dependencies

Ask Codex: *"The auth feature blocks the dashboard, add that dependency"*

Codex will run:

```bash theme={null}
tk dep add tk-dashboard tk-auth
```

### Close Issues

Ask Codex: *"I finished the login bug, close it"*

Codex will run:

```bash theme={null}
tk close tk-abc123 "Fixed in this session"
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Codex doesn't know about tk">
    Make sure `AGENTS.md` exists in your repository root and mentions tk. Codex reads this file for project context.

    ```bash theme={null}
    tk onboard
    ```
  </Accordion>

  <Accordion title="No issues showing up">
    Make sure you're in a directory with a `.tickets/` folder, or a subdirectory of one.

    ```bash theme={null}
    tk doctor
    ```
  </Accordion>

  <Accordion title="tk not found in Codex session">
    Ensure tk is installed and available in your PATH:

    ```bash theme={null}
    which tk
    tk version
    ```

    If not installed:

    ```bash theme={null}
    curl -fsSL https://ticket-rs.io/install.sh | sh
    ```
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Stacks" icon="layer-group" href="/concepts/stacks">
    Understanding linear dependency chains.
  </Card>

  <Card title="CLI Commands" icon="terminal" href="/cli-reference/commands">
    Full command reference for working with issues.
  </Card>

  <Card title="Graph Analytics" icon="chart-network" href="/concepts/graph-analytics">
    PageRank, critical path, and bottleneck detection.
  </Card>

  <Card title="MCP Server" icon="plug" href="/integrations/mcp">
    Give AI assistants direct access to tk documentation.
  </Card>
</CardGroup>