Skip to content
Docs

Install Estelle

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

View as Markdown

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:

RouteWhat it provides
Native coding-agent pluginHosted tools plus the supported host's session hooks.
Hosted MCP onlyTools in another MCP client, without installing session capture hooks.
Optional Estelle CLILocal 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. These instructions describe the v0.0.12 package; package registration, authenticated MCP access and working hooks are separate checks.

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.

#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.

#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:

ClientCommand
Cursorestelle init --client cursor
VS Codeestelle init --client vscode
Windsurfestelle init --client windsurf
JetBrains through Junieestelle 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.

#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.

#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.

CLI Read the full command reference and indexing options.MCP server See connection options and the tools available to your agent.Sessions Learn what session hooks capture and where to find recorded work.