Quickstart: Codex

This guide takes you from nothing installed to running Codex tasks that interact with your connected apps. Every step shows you exactly what to type and what you should see.

Prerequisites

Python 3.11+ — check with python3 --version
Codex CLI — installed and working (openai/codex)
An account to connect (Google, Slack, GitHub, etc.)

Step 1: Install supyagent

pip install supyagent

Verify it worked:

supyagent --version

supyagent v0.6.2

Step 2: Connect your account

supyagent connect

╭──────────────────────────────────────╮
│                                      │
│   Your code:  ABCD1234               │
│                                      │
╰──────────────────────────────────────╯

Opening browser to https://app.supyagent.com/device...

Waiting for authorization...

Your browser opens. If you haven't signed up yet, create an account at supyagent.com and connect your integrations. Then approve the device code.

✓ Connected!

Connected Integrations
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Provider ┃ Services                          ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ google   │ gmail, calendar, drive            │
│ github   │ general                           │
└──────────┴───────────────────────────────────┘

Step 3: Generate skills

Navigate to your project directory and generate skill files:

cd ~/my-project
supyagent skills generate

Detected AI tool folders:

  1. Codex  (.agents/skills/)

Select folders (comma-separated numbers, or 'a' for all): 1

✓ Generated 3 skills (13 tools) in 1 location(s)
  .agents/skills/
    supy-cloud-gmail/SKILL.md
    supy-cloud-calendar/SKILL.md
    supy-cloud-github/SKILL.md

Step 4: Configure Codex to use the skills

Codex reads instructions from an agents.md file (or AGENTS.md) in your project root. Add a reference to the generated skills:

agents.md

## Available integrations

This project has supyagent cloud tools installed. Skill files in `.agents/skills/`
describe the available integrations (Gmail, Calendar, GitHub, etc.).

To call a tool, use:
```
supyagent service run tool_name 'json_args'
```

Output format: `{"ok": true, "data": ...}` on success, `{"ok": false, "error": "..."}` on failure.

Check `.agents/skills/` for the full list of available tools and their parameters.

Step 5: Run Codex with your integrations

Now you can give Codex tasks that use your connected apps:

codex "Check my Gmail for any emails from GitHub about open pull requests and summarize them"

Codex will:

Read the skill files in .agents/skills/
Run supyagent service run gmail_list_messages '{"query": "from:notifications@github.com"}'
Process the results
Give you a summary

More tasks to try:

codex "What's on my calendar today? If I have any free slots after 2pm, list them"

codex "List my open GitHub issues and create a summary in a new file called issues.md"

codex "Check my recent emails and flag any that need a response"

What's happening behind the scenes

Codex reads agents.md and the skill files in .agents/skills/
When a task involves email/calendar/GitHub, it recognizes the available tools
It runs supyagent service run <tool> '<args>' as a shell command
The CLI authenticates and calls the Supyagent API
The API uses your OAuth tokens to call the provider (Gmail, GitHub, etc.)
JSON results come back and Codex processes them

Troubleshooting

Codex doesn't use the skills

Make sure:

The .agents/skills/ directory contains the generated SKILL.md files
Your agents.md references the skills directory
Codex has permission to run shell commands

ls .agents/skills/

`supyagent: command not found`

Codex runs commands in a sandboxed environment. Make sure supyagent is installed globally:

pipx install supyagent

Tool calls return authentication errors

Check your connection:

supyagent status

If disconnected, run supyagent connect to re-authenticate.

Adding more integrations

Go to supyagent.com and connect new integrations
Regenerate skill files:

supyagent skills generate --all

Quickstart: Codex

On this page