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

​
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

  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

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

Make sure AGENTS.md exists in your repository root and mentions tk. Codex reads this file for project context.
tk onboard
Make sure you’re in a directory with a .tickets/ folder, or a subdirectory of one.
tk doctor
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.