OpenAI Codex

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:

Codex CLI

Terminal-based agent installed locally via npm. Runs commands and edits code autonomously.

Codex Desktop

Desktop application with GUI. Provides the same agent capabilities with a visual interface.

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

npm install -g @openai/codex

Step 2: Install tk and Initialize

# 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:

## 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

Run tk onboard to get a copy-pasteable snippet for your AGENTS.md.

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:

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:

codex "$(tk prime) -- Based on the above context, what should I work on?"

Or create a wrapper script:

#!/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

Terminal-First

Runs in your existing terminal workflow

Full Autonomy

Can run tk commands, edit code, and manage issues

Local Performance

Direct access to your local development environment

Git Access

Full access to git history and repository

Codex Desktop Setup

Using tk with Codex Desktop

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

Desktop Advantages

Visual Interface

GUI for reviewing agent actions and approving changes

Session History

Browse past sessions and their outcomes

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:

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:

tk dep add tk-dashboard tk-auth

Close Issues

Ask Codex: “I finished the login bug, close it” Codex will run:

tk close tk-abc123 "Fixed in this session"

Troubleshooting

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.

tk onboard

No issues showing up

Make sure you’re in a directory with a .tickets/ folder, or a subdirectory of one.

tk doctor

tk not found in Codex session

Ensure tk is installed and available in your PATH:

which tk
tk version

If not installed:

curl -fsSL https://ticket-rs.io/install.sh | sh

Next Steps

Stacks

Understanding linear dependency chains.

CLI Commands

Full command reference for working with issues.

Graph Analytics

PageRank, critical path, and bottleneck detection.

MCP Server

Give AI assistants direct access to tk documentation.

Getting Started

Concepts

CLI Reference

Integrations

About

Blog

Codex Options

Codex CLI

Codex Desktop

Recommended Setup

Step 1: Install Codex CLI

Step 2: Install tk and Initialize

Step 3: Add AGENTS.md

Codex CLI Setup

Using tk with Codex CLI

Injecting Context

CLI Advantages

Terminal-First

Full Autonomy

Local Performance

Git Access

Codex Desktop Setup

Using tk with Codex Desktop

Desktop Advantages

Visual Interface

Session History

Working with Codex

Find Work to Do

Create Issues

Manage Dependencies

Close Issues

Troubleshooting

Next Steps

Stacks

CLI Commands

Graph Analytics

MCP Server

​Codex Options

Codex CLI

Codex Desktop

​Recommended Setup

​Step 1: Install Codex CLI

​Step 2: Install tk and Initialize

​Step 3: Add AGENTS.md

​Codex CLI Setup

​Using tk with Codex CLI

​Injecting Context

​CLI Advantages

Terminal-First

Full Autonomy

Local Performance

Git Access

​Codex Desktop Setup

​Using tk with Codex Desktop

​Desktop Advantages

Visual Interface

Session History

​Working with Codex

​Find Work to Do

​Create Issues

​Manage Dependencies

​Close Issues

​Troubleshooting

​Next Steps

Stacks

CLI Commands

Graph Analytics

MCP Server

Codex Options

Recommended Setup

Step 1: Install Codex CLI

Step 2: Install tk and Initialize

Step 3: Add AGENTS.md

Codex CLI Setup

Using tk with Codex CLI

Injecting Context

CLI Advantages

Codex Desktop Setup

Using tk with Codex Desktop

Desktop Advantages

Working with Codex

Find Work to Do

Create Issues

Manage Dependencies

Close Issues

Troubleshooting

Next Steps