# Install Estelle

> Install the native plugin for Claude Code, Codex, Kimi Code, Grok Build or Cursor, or connect a tools-only MCP client.

The native plugin connects Estelle's hosted MCP tools and the host's session hooks. You do not need to clone Estelle's backend, run a local MCP server, or install the Estelle CLI for this route.

Choose the connection you need:

| Route | What it provides |
|---|---|
| Native coding-agent plugin | Hosted tools plus the supported host's session hooks. |
| Hosted MCP only | Tools in another MCP client, without installing session capture hooks. |
| Optional Estelle CLI | Local indexing and terminal commands, with its own setup. |

## Check three prerequisites

1. Install the coding host and use a version with its native plugin feature.
2. Make external **Node.js 22 or later** available as `node` to that actual host process. A bundled host runtime is not a substitute for the external command the hooks launch.
3. On Claude Code, MCP signs in through your browser. Session capture hooks, and every other host, use an `ESTELLE_API_KEY` from your Estelle account, which must be available to the host process.

A GUI app started from the Dock or Start menu may not inherit your terminal's environment. Check from the environment that launches the actual host, without printing the key:

```bash
node --version
node -e "console.log(process.env.ESTELLE_API_KEY ? 'ESTELLE_API_KEY present' : 'ESTELLE_API_KEY missing')"
```

Presence is not authentication. The plugin does not provision an account or install Node for you. Do not paste credentials into an agent conversation, a shared plugin variable, or support output.

## Install a native plugin

The public package and its maintained host guides are at [uqeu/estelle-plugins](https://github.com/uqeu/estelle-plugins). These instructions describe the v0.0.12 package; package registration, authenticated MCP access and working hooks are separate checks.

#### Claude Code

Inside Claude Code, run:

```text
/plugin marketplace add uqeu/estelle-plugins
/plugin install estelle@estelle-plugins
```

Review the normal installation and Estelle hook prompts, restart Claude, run `/mcp`, and sign in with your browser. Add `ESTELLE_API_KEY` only if you want session capture, then quit and reopen the app so it reads the key. If you installed the older `estelle@fatelabs` plugin, run `setup claude` from the new package to migrate. See the [Claude Code guide](https://github.com/uqeu/estelle-plugins/blob/main/docs/install/claude.md).

#### Codex

From your shell, outside the Codex conversation:

```bash
codex plugin marketplace add uqeu/estelle-plugins --ref main
codex plugin add estelle@estelle-plugins
```

Open `/hooks` and review Estelle's hooks. `t` grants trust; space only toggles enablement. Start a fresh session after approval. An enabled package alone does not prove the hooks can run. See the [Codex guide](https://github.com/uqeu/estelle-plugins/blob/main/docs/install/codex.md) for updating an existing marketplace.

#### Kimi Code

Use the native commands inside interactive Kimi Code:

```text
/plugins install https://github.com/uqeu/estelle-plugins
/plugins info estelle
/reload
```

The GitHub URL selects the latest published release. A change on the repository's main branch is not automatically a new release. Review the package and normal approval prompts; `/reload` or `/new` applies it to a session.

For an explicitly requested fresh Estelle registration, run `/plugins remove estelle` and `/reload` before the GitHub install. This is an Estelle plugin reset, not permission to delete chats, Kimi's home, unrelated settings, other hosts or shared memories.

Do not run `kimi -p '/plugins …'`: it sends a model prompt instead of operating the native installer. Do not launch a model turn as an installation test. If an agent cannot operate the interactive installer, it should give you the exact command and report installation pending. See the [Kimi Code guide](https://github.com/uqeu/estelle-plugins/blob/main/docs/install/kimi.md).

#### Grok Build

```text
grok plugin install uqeu/estelle-plugins@v0.0.12#plugins/grok
grok plugin enable estelle
```

Use the normal approval flow and start a fresh session. See the [Grok Build guide](https://github.com/uqeu/estelle-plugins/blob/main/docs/install/grok.md).

#### Cursor

Use the editor's **Customize** page to install from an available marketplace. For this Git repository, use a team marketplace import if your plan supports it. Otherwise, follow Cursor's documented local plugin loading: copy the contents of `plugins/cursor` from the public plugin repository into a new `~/.cursor/plugins/local/estelle` directory, then run **Developer: Reload Window**.

Local plugins must be allowed, and a marketplace plugin with the same name takes precedence. Ensure the editor process inherits `ESTELLE_API_KEY`. Inspect the plugin components, Hooks and MCP in Customize after reload. A terminal Agent CLI inventory does not prove the editor loaded or authenticated the plugin. See the [Cursor guide](https://github.com/uqeu/estelle-plugins/blob/main/docs/install/cursor.md).

## Verify package, MCP and hooks separately

1. Inspect the native package registration and version.
2. In the new session's actual advertised tools, use **one advertised read-only MCP tool** to check authenticated access. Do not invent an identity tool or repeat session-history reads as an authentication test.
3. Check a new session's hook status and acknowledged timeline entries separately. A connected badge or tool list does not prove session capture, and a stored entry does not promise a complete transcript.

No paid task or model turn is needed as an installation test. Report any pending prerequisite rather than calling setup complete.

The public repository also contains an optional maintainer connection diagnostic. Its current source checks MCP initialization, rejects an invalid synthetic credential, and requires each invalid write request to reach its specific missing-session validation. A 401, 403, 404 or 429 from a write route is not that proof. The diagnostic sends no valid session or checkpoint write; it does not certify native hooks. A diagnostic change on main is not a new plugin runtime release.

Node build and test checks run on Linux, macOS and Windows. That matrix does not certify every native host on every OS, native login, Windows file permissions, or full-history capture. See the [support boundaries](https://github.com/uqeu/estelle-plugins/blob/main/docs/SUPPORT.md).

## Install the CLI

The CLI supports macOS and Linux on x86_64 and arm64. With Node.js 18 or later, install it with npm:

```bash
npm i -g @fatelabs/estelle
```

Without npm, use the release installer:

```bash
curl --proto '=https' --tlsv1.2 -fsSL \
  https://github.com/uqeu/estelle-cli/releases/latest/download/install.sh | sh
```

Create an API key in **Settings → API keys**, then run:

```bash
estelle login
estelle setup
```

Run `estelle setup` from the repository root. It configures Estelle for the repository, indexes it, and checks that Estelle can answer using a symbol from that code.

`estelle login` stores the key for later commands. You can also provide `ESTELLE_API_KEY` in the environment; do not commit the key or paste it into support messages.

## Connect another MCP client

The hosted server is:

```text
https://api.fatelabs.ca/mcp
```

For a client that supports browser sign-in, add this server configuration:

```json
{
  "mcpServers": {
    "estelle": {
      "type": "http",
      "url": "https://api.fatelabs.ca/mcp"
    }
  }
}
```

Start a new session and approve the sign-in request. If the client cannot use browser sign-in, configure an `Authorization: Bearer <your-key>` header instead.

For Claude Code without the plugin, add the hosted server directly:

```bash
claude mcp add --transport http estelle https://api.fatelabs.ca/mcp
```

Or use an API key stored in your environment:

```bash
claude mcp add --transport http estelle https://api.fatelabs.ca/mcp \
  --header "Authorization: Bearer $ESTELLE_API_KEY"
```

### Let the CLI write client configuration

After `estelle login`, run the command for your client from the repository root:

| Client | Command |
|---|---|
| Cursor | `estelle init --client cursor` |
| VS Code | `estelle init --client vscode` |
| Windsurf | `estelle init --client windsurf` |
| JetBrains through Junie | `estelle init --client jetbrains` |

Run `estelle init` without `--client` to detect supported editors. Use `--dry-run` when you want to inspect a configuration change before applying it.

### Use the CLI instead of the Codex plugin

To provide session hooks and serve Estelle's tools over stdio:

```bash
estelle install-hooks
codex mcp add estelle -- estelle mcp-server
```

Open Codex, run `/hooks`, trust the hooks, and restart the session.

## Index and update a repository

From the repository root:

```bash
estelle sweep --dry-run
estelle sweep
```

`--dry-run` lists the files that would be sent and sends nothing. A sweep reads the files Git can see in the checkout, including uncommitted changes. Use it when the available index must include work you have not pushed.

Run `estelle reindex` after later changes. If Estelle reports that an index is stale or missing, update it before relying on code answers. You can also index through the GitHub connection instead; see [GitHub](https://docs.fatelabs.ca/github).

## Capture local sessions

The native plugins above supply their host-specific hooks. The optional legacy CLI route installs its own Claude Code and Codex hooks separately:

```bash
estelle install-hooks
```

Restart the agent afterward. In Codex, also run `/hooks` and trust Estelle's hooks. Local session timelines require active, trusted hooks. MCP activity may appear separately as a saved activity record.

To remove only Estelle's hooks:

```bash
estelle uninstall-hooks
```

To remove Estelle from editor configurations written by the CLI:

```bash
estelle remove
```

## Check the installation

```bash
estelle --version
estelle doctor
```

`estelle doctor` checks credentials and setup without printing secrets. To see whether a newer CLI release is available:

```bash
estelle upgrade
```

`estelle upgrade` reports the release and prints the installation command; it does not perform the upgrade.

For connection failures, see [Troubleshooting](https://docs.fatelabs.ca/troubleshooting).

## Windows and the optional CLI

The legacy CLI instructions below use WSL. This is separate from the native plugin package and its Node.js runtime; do not require WSL for every native plugin host:

1. In PowerShell as Administrator, run `wsl --install`, restart, and open Ubuntu.
2. Install the CLI inside WSL with the release installer above.
3. Add the install location to your shell path if needed, then run `estelle --version` and `estelle login`.
4. Install Claude Code or Codex inside WSL as well, and keep the repository on the WSL filesystem so the agent and hooks can reach `estelle`.

The hosted MCP server can also be used without installing the CLI.

## Related

- [CLI](https://docs.fatelabs.ca/cli): Read the full command reference and indexing options.
- [MCP server](https://docs.fatelabs.ca/mcp): See connection options and the tools available to your agent.
- [Sessions](https://docs.fatelabs.ca/sessions): Learn what session hooks capture and where to find recorded work.