# Codex extensions

In Codex and ChatGPT, Clanker Ship adds My work to the sidebar, a ticket panel to each thread, a plan viewer, ticket mentions and a settings page.

Codex in the ChatGPT desktop app, and ChatGPT, read
[OpenAI's extensions to MCP and MCP Apps](https://github.com/openai/mcp-extensions/blob/main/docs/spec.md).
Clanker Ship uses them to open its screens without the model, list tickets in the composer's
mentions, and give the plugin a settings page. Other clients ignore the extensions and see ordinary
tools, so nothing depends on them.

| Feature      | Tool                                                                                     | Where it shows          |
| ------------ | ---------------------------------------------------------------------------------------- | ----------------------- |
| My work      | [show_work](https://docs.qa.clankership.net/mcp/tools/show_work.md)                                                        | The sidebar, fullscreen |
| Ticket panel | [open_ticket_panel](https://docs.qa.clankership.net/mcp/tools/open_ticket_panel.md)                                        | A thread's side panel   |
| Plan viewer  | [open_plan_file](https://docs.qa.clankership.net/mcp/tools/open_plan_file.md)                                              | `.plan.md` files        |
| Mentions     | [search_tickets](https://docs.qa.clankership.net/mcp/tools/search_tickets.md)                                              | The composer's `@` list |
| Settings     | [read_settings](https://docs.qa.clankership.net/mcp/tools/read_settings.md), [update_settings](https://docs.qa.clankership.net/mcp/tools/update_settings.md) | The plugin's page       |

## My work in the sidebar

[show_work](https://docs.qa.clankership.net/mcp/tools/show_work.md) declares a global entrypoint in `_meta["openai/ui"]`, so My work
opens from the sidebar, fullscreen, without a prompt. A deep link with `?path=/tickets/WEB-31` opens
it on that ticket. **Work on this** opens a new thread with an unsent draft that asks the agent to
read the ticket and follow its plan.

The screens open inline in the conversation and can go fullscreen on request.

## A thread's ticket panel

[open_ticket_panel](https://docs.qa.clankership.net/mcp/tools/open_ticket_panel.md) declares a thread entrypoint, so Codex opens it in
a thread's side panel. It shows the ticket named in the branch of the agent's most recent live
session, such as `maya/web-31-docs-search` for `WEB-31`, or lets the person pick one of their open
tickets. The ticket stays in the agent's context as a chip above the composer. Only screens call
this tool; the model never sees it.

## Plan files

[open_plan_file](https://docs.qa.clankership.net/mcp/tools/open_plan_file.md) claims files ending in `.plan.md`, never plain `.md`.
When the person opens one, such as `WEB-31.plan.md`, Codex reads the file for the plan viewer. The
viewer finds the ticket from the file's name, marks the sections that are new or changed against the
ticket's plan, and **Publish to WEB-31** saves the file as the ticket's plan with
[update_ticket](https://docs.qa.clankership.net/mcp/tools/update_ticket.md). A file whose name gives no ticket the person can open
shows how to name it. Only screens call this tool.

## Ticket mentions

[search_tickets](https://docs.qa.clankership.net/mcp/tools/search_tickets.md) is advertised as `openai/mentions` under
`capabilities.extensions` in the `initialize` result, so the composer's `@` list searches Clanker
Ship. It finds tickets whose ID starts with the query or whose title contains it, open tickets
first, and projects whose name or slug contains it: up to 20 tickets and 5 projects. An empty query
lists the open tickets the person's agents own.

Each result is a resource link, such as `clanker-ship://tickets/WEB-31` or
`clanker-ship://projects/docs-launch`. The agent reads it with `resources/read` and gets the ticket
with its summary and plan, or the project with its document, as Markdown.

## Settings

[read_settings](https://docs.qa.clankership.net/mcp/tools/read_settings.md) and [update_settings](https://docs.qa.clankership.net/mcp/tools/update_settings.md) are
advertised as `openai/settings`, so the plugin's page in Codex shows two settings, stored per agent:

| Setting                            | Field             | What it does                                                                                                 |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
| Default team                       | `defaultTeam`     | The team [create_ticket](https://docs.qa.clankership.net/mcp/tools/create_ticket.md) uses when the agent names none; one of the person's teams |
| Wake idle threads for new messages | `wakeIdleThreads` | Whether the plugin hands each new message to an idle Codex thread                                            |

Without a saved default team, new tickets go to the first of the person's teams. Any client can
call the two tools; the plugin's `setup` skill offers them too:

```json
{ "set": { "defaultTeam": "WEB", "wakeIdleThreads": true } }
```

When Wake idle threads is on, the plugin's session hook starts a helper that hands each new message
to the thread with `codex queue --thread`. When it cannot, the message stays queued and the next
prompt's hook shows it.

## Onboarding

After the plugin is installed, Codex runs its `setup` skill: it signs the agent in by calling
[show_work](https://docs.qa.clankership.net/mcp/tools/show_work.md), shows the person's work, reads their settings, and offers to
change the default team and Wake idle threads.

## Coming later

A Create ticket form in Codex, with the team's icons and files from the thread, is not built yet.
It needs MCP form elicitation, which OpenAI's hosted servers handle with a newer MCP version than
this server speaks.