Coding agents

Use an agent to generate a package, maintain a Project, or call Typeship's API. The agent runbook selects the appropriate workflow and verifies the result. Anonymous generation needs no setup beyond the CLI; authenticated work can use an existing key or a browser login.

Set up with one prompt

Paste this into your agent:

Read https://typeship.dev/agents.md and set Typeship up for this repo.

/agents.md is a runbook written to the agent: detect the situation, install the CLI, pick a path (no sign-in, has a key, needs a key, REST only, connect the MCP server), verify, report. It works with no sign-in: the first path generates a package from any spec anonymously.

Connect your agent

https://typeship.dev/mcp is the hosted MCP server. A client that supports MCP authorization opens a browser so you can sign in and choose an organization. The same URL accepts an organization API key for CI and machines without a browser. To try the docs and anonymous generation tools without signing in, connect to https://typeship.dev/mcp/public instead. The MCP server page describes each endpoint and its tools.

/plugin marketplace add typeship-ax/skills
/plugin install typeship@typeship-skills

claude mcp add --transport http typeship https://typeship.dev/mcp   # signs you in
claude mcp add --transport http typeship https://typeship.dev/mcp --header 'Authorization: Bearer ${TYPESHIP_TOKEN}'   # with a key

Install skills

The Typeship skills are Agent Skills that wrap the CLI: a router (typeship), typeship-cli, typeship-api (REST without the CLI), typeship-spec-prep (analyze and author a contract without fabricating behavior), typeship-mcp-clients, and typeship-ci. API-quality findings include grounded authoring_brief instructions; exact fixes can become a source pull request or reviewed Spec patch, while ambiguous changes stop for the API owner's decision.

In Claude Code or Codex, the plugin in Connect your agent installs the skills. For other agents, install the skills alone:

npx skills add typeship-ax/skills

Authenticate for linked work

Check for an existing credential before starting a login:

typeship auth check --format json

The command prints status: "ok" when a credential works. Without one, it prints status: "action_required" with next_steps and exits with a nonzero code.

If authenticated work needs a credential, run typeship login --no-browser and open the approval link it prints. The link expires after ten minutes. If TYPESHIP_TOKEN is already set, other commands use it directly and you can skip login. Login stores the credential; it does not install skills or configure MCP clients.

Before creating a Project, have the agent list Projects, inspect the matching Spec, and list its Targets. Reuse existing resources and add only the outputs you requested:

typeship projects list --all
typeship projects get <project_id>
typeship specs get <spec_id>
typeship targets list --project-id <project_id> --all

Set up every agent client

To connect one agent, use Connect your agent. For machine setup across every detected agent client, you can explicitly choose typeship init --all:

typeship init --all

This command:

• Starts a browser login and waits for approval when no credential exists. If TYPESHIP_TOKEN is set, it uses that and stores nothing.
• Installs the skills.
• Writes MCP config for detected clients with a ${TYPESHIP_TOKEN} environment reference.
• Adds a Typeship block to the repository's AGENTS.md. If only CLAUDE.md exists, it updates that file instead. Re-running it replaces the block in place.

It is optional for generation and Project work; an agent should run it only when that broader setup is requested.

CLI behavior for agents

The full contract is on the CLI output page, and typeship agent-guide --format json prints it. It provides:

• JSON on stdout. In agent mode, every failure is one envelope on stderr: {status, issues: [{code, message}], next_steps, docs_url?, detail?}. Branch on issues[].code; detail carries the API's response when an API call failed.
• Agent mode (--mode agent, TYPESHIP_MODE=agent, or no terminal) never prompts and never opens a browser.
• Destructive commands need --force; without it the CLI returns CONFIRMATION_REQUIRED and the exact command to confirm.
• typeship auth check, typeship doctor, typeship help --format json, and typeship docs search <term> for diagnosis and discovery.

Without a key

An agent with a Spec and no Typeship organization can still get a package. Up to 25 operations generate anonymously, rate limited per address:

typeship packages generate \
  --spec '{"url":"https://typeship.dev/examples/petstore/openapi.yaml"}' \
  --target '{"type":"typescript_sdk"}' \
  --out sdk/

--target takes a type of cli, mcp, typescript_sdk, python_sdk, or go_sdk. POST /api/v1/generate and the packages_generate tool at https://typeship.dev/mcp/public generate the same way. The response's coverage object says what was held back and where to sign up.

For a spec URL, the response also includes a claim link that saves the recipe as a Project within seven days. The CLI records unclaimed links in .typeship/claims.json in the working directory, and typeship doctor lists them. Organization operations need an existing credential or an approved login; the runbook explains that handoff.

CLI, MCP, and SDK requests include a download object automatically; a direct REST request includes it only when it sends an Idempotency-Key header. Use download.url to retrieve the complete ZIP, verify download.sha256, and extract it before following the package README. The private link expires with the 24-hour replay window. See Get the generated package for hosted and local MCP instructions.

To connect your own API guides to the tools Typeship generates, follow Connect your API guides to CLI and MCP.

Docs for agents

• /llms.txt: every documentation entry point, one line each. /llms-full.txt: every prose page and both generated references in one fetch.
• Append .md to any prose docs URL, or send Accept: text/markdown, for that page as markdown with frontmatter and absolute links. Use /docs/api.md and /docs/reference.md for the complete generated references.
• search_docs and read_docs at https://typeship.dev/mcp/public need no key.
• Every prose page has Copy page, View as Markdown, Open in Claude, and Open in ChatGPT under its title.

Select a code language

When fetching Markdown docs, send the programming language used by your current task:

GET /docs/targets/sdk HTTP/1.1
Host: typeship.dev
Accept: text/markdown
Accept-Code-Language: python

Accept-Code-Language is a custom Typeship header. Its supported values are typescript, python, and go, one value per request. Keep human-language preferences in Accept-Language.

Clients that cannot set headers can use the Python Markdown variant. Add ?codeLanguage=typescript, ?codeLanguage=python, or ?codeLanguage=go to any prose Markdown docs URL, /docs/reference.md, or /llms-full.txt. The query parameter takes precedence over the header; values are case-insensitive.

Typeship selects existing examples and their accompanying instructions. Shared explanations, shell commands, configuration, and client-setup tabs remain. When a matching example is missing, the response says so and links to the supported language guides. Examples are never translated or generated on request. The full-documentation variant also leaves out pages dedicated to the other SDK languages; the SDK reference uses the selected language's native method signatures.

Omit the preference for the full docs. An unsupported or empty value, including a comma-separated list, returns the full docs with a notice listing the supported languages. These preferences select code examples only; they do not translate prose or change the HTML docs.