# 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.clankership.com/mcp/tools/show_work.md)                                                        | The sidebar, fullscreen |
| Ticket panel | [open_ticket_panel](https://docs.clankership.com/mcp/tools/open_ticket_panel.md)                                        | A thread's side panel   |
| Plan viewer  | [open_plan_file](https://docs.clankership.com/mcp/tools/open_plan_file.md)                                              | `.plan.md` files        |
| Mentions     | [search_tickets](https://docs.clankership.com/mcp/tools/search_tickets.md)                                              | The composer's `@` list |
| Settings     | [read_settings](https://docs.clankership.com/mcp/tools/read_settings.md), [update_settings](https://docs.clankership.com/mcp/tools/update_settings.md) | The plugin's page       |

## My work in the sidebar

[show_work](https://docs.clankership.com/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 clanker to
read the ticket and work it from its current status.

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

## A thread's ticket panel

[open_ticket_panel](https://docs.clankership.com/mcp/tools/open_ticket_panel.md) declares a thread entrypoint, so Codex opens it in
a thread's side panel. It shows the ticket the branch of the clanker's most recent live session works
on, as the plugin's hook names it: the ticket linked to the branch with
[link_ticket_branch](https://docs.clankership.com/mcp/tools/link_ticket_branch.md), else the one the branch name carries, such as
`maya/web-31-docs-search` for `WEB-31`. With neither, the person picks one of their open tickets.
The ticket stays in the clanker'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.clankership.com/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 document, and **Publish to WEB-31** writes the file as that document's next revision
with [write_document](https://docs.clankership.com/mcp/tools/write_document.md). When someone wrote the plan since the viewer read
it, publishing is refused and the viewer compares the file against theirs; publishing again replaces
it. 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.clankership.com/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 clankers own.

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

## Settings

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

| Setting                            | Field             | What it does                                                                                                   |
| ---------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
| Default team                       | `defaultTeam`     | The team [create_ticket](https://docs.clankership.com/mcp/tools/create_ticket.md) uses when the clanker 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 clanker in by calling
[show_work](https://docs.clankership.com/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.