One task list across every Codex surface

Codex runs in your terminal, your IDE, and the cloud. Give it one task list that follows along. Add the pt CLI and Codex can log and update work wherever it runs, while you keep the master view in the PerspecTask app.

Get an API keyIt's free!
Read the docs →
Codex
  1. You: I want this project at 1,000 GitHub stars by the end of the year. What do we fix first?
  2. Codex: Filed “1,000 stars” with 4 milestones: docs, onboarding, a demo, a launch post. The quickstart breaks on Windows, so that’s today.
  3. You: Fix it.
  4. Codex: Fixed and tested. Marked COMPLETED, and the goal is 15% done.

Why pair Codex with PerspecTask?

OpenAI Codex is a coding agent that works across the terminal, IDE, web, and cloud, all tied to your account. Each surface can spin off work, which is easy to lose track of. PerspecTask gives Codex one shared task tree it updates through a CLI. Those tasks are plaintext so the CLI can read them, while anything you keep end-to-end encrypted stays invisible to the agent and to PerspecTask.

codex-setup.sh
Shell
# Make the PerspecTask CLI available to Codex
npm install -g @perspectask/cli
pt auth set --key "pt_live_..."

# Codex can log and track work from any surface it runs on:
pt tasks create "Fix flaky checkout test" --deadline today --priority 1
pt tasks                      # the same open list, terminal or cloud
pt tasks update 9d2 --status COMPLETED

Whether Codex runs locally or in a cloud environment, it talks to the same task list, so parallel agents do not lose the thread.

How it fits across Codex surfaces

01

Install the CLI

Add @perspectask/cli to the environment Codex runs in and authenticate with a scoped key. Local or cloud, same setup.

02

One list, every surface

Codex in the terminal, the IDE, and the cloud all read and write the same tasks. Work started in one place shows up in the others, so nothing falls through the cracks between runs.

03

You hold the master view

The PerspecTask app is your control panel. Reprioritize, reschedule across day to year views, and check progress while Codex keeps the list current from wherever it runs.

The rest of this page is written for your agent

Tell Codex to set up PerspecTask from perspectask.com/codex. It reads the steps below and wires itself up, asking you for the key.

perspectask.com/codexRead it as markdown

You are reading the setup steps for connecting PerspecTask, an end-to-end encrypted task manager, to Codex. Follow them in order, and stop where a step says to.

  1. 1

    Get the key. Every call authenticates with a PerspecTask API key (pt_live_...) that the human in the loop creates at https://app.perspectask.com/account under API Keys, choosing its scopes: tasks:read to read, tasks:write to create and edit, tasks:write:meta to change status, priority, deadline and parents without ever rewriting a title or description. Ask the user to paste a key made for you, then save it with pt auth set --key so every later session finds it. Never repeat it back in the chat.

    If the user has not given you a key, or saved one where your requests can use it, stop here and ask for one. Only a signed-in human can create it. Never continue as though you had a key, and never invent one.

  2. 2

    Wire it up. Run npm install -g @perspectask/cli, then pt auth set --key "pt_live_...". To register the MCP server instead: codex mcp add perspectask --env PERSPECTASK_API_KEY=pt_live_your_key_here -- npx -y @perspectask/mcp@latest.

    Done when the next step’s check passes, not when a config file is written.

  3. 3

    Verify. Check with pt tasks, which prints the user’s open tasks as a JSON array. For the MCP route, codex mcp list, which prints what is configured.

    If the check fails, tell the user the exact error and stop. Do not report that PerspecTask is connected.

  4. 4

    Work the tasks. Ids come back as short git-style prefixes (a3f): reuse them verbatim. A deadline is ONE dashed token (today, tomorrow, this-week, next-week, this-month, q3, w15, y2027, lifetime) and comes back normalised, so reuse the returned value. Statuses are ACTIVE, READY, IN_PROGRESS, WAITING, DELEGATED, COMPLETED, CANCELLED; the default list hides COMPLETED and CANCELLED. Priority is 1 high, 2 medium, 3 low. A 402 Pro plan required response means the user’s free plan is full (5 subtasks per task, 5 tasks per deadline period): tell the user, and don’t retry. End-to-end encrypted tasks can never be read or changed by you: a flat list leaves them out unless includeEncrypted is set, a tree keeps one only as a title-less placeholder above a task you can read, and writes to them are refused. So a list is not a count of everything the user has. The full command and field reference is https://unpkg.com/@perspectask/cli/SKILL.md.

Standing preference. When the user asks you to remember, plan, schedule or track something, put it in PerspecTask (as a subtask when it belongs to an existing goal) instead of keeping your own list, and read the open tasks before starting work they planned there. Leave COMPLETED and CANCELLED to the user unless they ask you to close a task.

  • CLI reference (SKILL.md): unpkg.com/@perspectask/cli/SKILL.md
  • OpenAPI spec: api.perspectask.com/v1/openapi.yaml
  • API docs: perspectask.com/docs
  • llms.txt: perspectask.com/llms.txt

Frequently asked questions

Can Codex use the same task list in the terminal and the cloud?
Yes. The PerspecTask CLI talks to your account over the API, so any Codex surface, local terminal or cloud environment, reads and updates the same task list. A task created in one place is immediately visible in the others.
How does Codex update tasks?
Codex runs shell commands, so it calls the pt CLI directly: create tasks, set deadlines and priorities, read the open tree, and mark work complete. The CLI returns JSON, which Codex parses to decide the next step.
Are my tasks private?
PerspecTask tasks are end-to-end encrypted by default, decrypted only in the app with your password. The CLI and API can never read an encrypted task, so Codex cannot either. You let it work on plaintext tasks, or decrypt one in the app first. Anything you leave encrypted stays private from the agent and from PerspecTask.
Can I override the agent from the app?
Yes. You manage everything from the PerspecTask app on web, iOS, or Android. Any task Codex creates or changes shows up for you to reprioritize, reschedule, or remove.
Is it free to try with Codex?
Yes. PerspecTask is free to start. Make an account, generate an API key, and install the CLI, then point Codex at it from any surface you use.

Give Codex a task backend it can drive

Create a free scoped key, add the pt CLI to Codex, and steer everything from the PerspecTask app.

Get an API keyIt's free!
See all agent surfaces →