# Quickstart

Install the skill, point your harness at the production MCP endpoint, authenticate, verify tool discovery, and complete your first useful action — per supported harness.

This takes about five minutes. Pick your harness below. Every path ends at the same first useful action: **create a Build Brief from a Linear issue**. Launch-supported harnesses are **Claude Code** and **Codex**; other MCP clients are experimental.

## Prerequisites
<a id="prerequisites"></a>

- A Semel workspace and browser sign-in.
- Node.js 20 or newer for the inspectable installer.
- A launch-supported harness installed locally: **Claude Code** or **Codex**.
- An absolute, operator-chosen path for the skill file. The installer deliberately does not guess it.
- The stable production MCP endpoint shown below:

**Production MCP endpoint:** `https://mcp.semel.ai/mcp`

## Download, inspect, and install the skill
<a id="install-skill"></a>

**Download and inspect**

```bash
curl -fsSLo semel-install.mjs https://docs.semel.ai/downloads/semel-install.mjs
less semel-install.mjs
node semel-install.mjs --help
```

**Run one explicit install**

```bash
node semel-install.mjs --harness codex --path /absolute/path/to/skills/semel/SKILL.md
# Or: --harness claude --path /absolute/path/to/skills/semel/SKILL.md
```

Do not pipe the installer into Node. The saved installer fetches `https://mcp.semel.ai/.well-known/semel-skill.json`, verifies the pinned Ed25519 publisher signature, protocol range, SHA-256, and skill metadata, then activates the file atomically. See [Install & update](https://docs.semel.ai/install) for update and rollback behavior.

## Claude Code
<a id="claude-code"></a>

**1. Add Semel as an HTTP MCP server.** This registers the endpoint; Claude Code runs the OAuth flow on first use.

**Claude Code**

```bash
claude mcp add --transport http --scope user semel https://mcp.semel.ai/mcp
```

**2. Authenticate.** Run `claude mcp login semel`, finish the Semel consent screen in your browser, and approve only the scopes this journey needs. Registration status is not proof that the running model session has tools.

**3. Reload Claude Code** after installation or authentication, then verify the live tools below.

## Codex
<a id="codex"></a>

**1. Add the MCP server** with the canonical OAuth resource:

**Codex**

```bash
codex mcp add semel --url https://mcp.semel.ai/mcp --oauth-resource https://mcp.semel.ai/mcp
```

**2. Authenticate** with the minimum first-brief scopes, finish consent in your browser, then restart the Codex session so the live tool inventory enters model context.

**Codex OAuth**

```bash
codex mcp login semel --scopes brief:read,brief:write
```

## Verify tool discovery
<a id="verify-tools"></a>

Run `claude mcp get semel` or `codex mcp get semel` to inspect registration, then start a fresh session and ask the agent to make the live read-only calls `project_list` and `brief_list`. Readiness requires MCP `initialize`, Semel `serverInfo`, non-empty `tools/list`, and the needed tools exposed to this model session. The [Tool reference](https://docs.semel.ai/tools) shows the current catalog.

> **Caution:** An **empty or partial** tool list means setup is incomplete — usually authentication did not finish or the endpoint is wrong. See [Troubleshooting → tools missing after setup](https://docs.semel.ai/troubleshooting#missing-tools).

## First action: create a Build Brief from a Linear issue
<a id="first-action"></a>

This is the lowest-friction, visible-value write — it needs `brief:read` and `brief:write`. Paste the issue text so the flow is self-contained; a Linear URL works only when your harness already has authorized Linear access.

**Say to your agent**

```
Create a Build Brief from this pasted issue.

Title: Retry failed invoice payments
Problem: Customers cannot tell whether a retry is scheduled.
Acceptance: Show the next retry time and send a receipt after success.
```

The agent first uses `project_list` to avoid a substantially overlapping effort. After you confirm the new project name and target, it calls `project_create` and `brief_create`, binding each later argument from the preceding `structuredContent`. Open the resulting brief in Semel. Continue with the exact state-aware paths in [Recipes](https://docs.semel.ai/recipes).

## Other MCP clients
<a id="experimental-clients"></a>

> **Caution:** Generic standards-based MCP clients and OpenClaw are experimental at launch. Use the same production endpoint and one of Semel’s two authentication modes, but do not assume install locations, refresh-token behavior, or session reload semantics from the Claude Code and Codex instructions.

Canonical page: https://docs.semel.ai/quickstart