# Estelle documentation

## Introduction | introduction
Estelle is your coding agents' self-improving software factory. It gives them persistent memory, repository verification, code review with evidence, and production monitoring that leads back to the code. Keep your existing coding agent and model. Estelle connects through its plugin, hosted MCP server, CLI, and dashboard.

## Quickstart | quickstart
1. Create an account at fatelabs.ca/signup with Google, or with an email and a password of at least 8 characters (confirm the email). New accounts start on Free.
2. Connect your coding agent. In Claude Code run:
/plugin marketplace add uqeu/estelle-cli
/plugin install estelle@fatelabs
Restart Claude Code, approve the Estelle MCP connection and sign in. In Codex, run in your shell: codex plugin marketplace add uqeu/estelle-cli then codex plugin add estelle@fatelabs, then open Codex, run /hooks and trust the hooks.
3. Index a repository: from the repository root run estelle sweep (estelle sweep --dry-run lists files without sending).
4. Ask your agent to call estelle_resume to check the connection.
5. Open app.fatelabs.ca. It opens on Ask Estelle; sessions appear under Sessions.

## Install in Claude Code | quickstart
Run these two commands in Claude Code:
/plugin marketplace add uqeu/estelle-cli
/plugin install estelle@fatelabs
Restart Claude Code, approve the Estelle MCP connection, and sign in to your Estelle account. Ask your agent to call estelle_resume to check the connection and recover existing context. The plugin includes the MCP configuration and session hooks.

## Install in Codex | quickstart
Run these two commands in your shell, outside the Codex conversation:
codex plugin marketplace add uqeu/estelle-cli
codex plugin add estelle@fatelabs
Open Codex, run /hooks and trust the installed hooks. Approve the Estelle MCP connection, sign in, and restart the session. Ask your agent to call estelle_resume. Untrusted hooks do not run: installation alone does not activate them. In Codex 0.153.4, the SessionEnd time limit can defer checkpoints until the next session starts; Stop and SubagentStop do not execute in that version.

## Plans and credits | plans
Every plan includes Estelle's own model (house inference), paid from the plan's Estelle Credits. Your own provider key works on every plan, Free included, and bills your provider. Credits read from GET /plans on 2026-10-23: Free 500 credits once (lifetime, never refreshes, no card); Pro 10,000 a month; Ultra 50,000 a month; Max 100,000 a month; Team 50,000 a month per seat, at least two seats. Prices are on the pricing page. Answers from Estelle's model, Agent mode, Silo time and other metered work use credits. Paid plans spend through three limits at once: 30 days (the full monthly grant, resets at period end), 7 days (a quarter of the monthly grant, rolling) and 5 hours (a share of the weekly limit, rolling). A call runs only while all three have room. Free has no rolling windows; its 500 credits are the only limit. When a limit is reached, wait for the window to roll, add a top-up (paid plans) or change plan.

## Promo code trials | trial
A promo code starts a paid plan with no card; ESTELLE14 is active: a 14-day Pro trial, limited to 500 redemptions. Fate Labs decides which codes are active. Redeem: sign in at app.fatelabs.ca, open Settings → Plans & billing, enter the code under Promo code, choose Redeem code and finish the Stripe checkout (no card asked). Rules: a verified email; redeem from the dashboard, not with an API key; one trial per account, email address and billing account; not for accounts that ever had a paid plan; not for team members. The trial has the plan's features and up to 1,000 credits; the first paid invoice restores the full monthly credits. On the last day: with a card, Stripe bills it and you keep the plan. Without a card, the account moves to Free, and seven days later its memory, sessions and swept repositories are permanently deleted; the login stays. Any paid plan inside those seven days cancels the deletion. A dashboard banner shows the trial end and deletion dates; a reminder email about three days before the end may also be sent.

## Install and connect | mcp
CLI: npm i -g @fatelabs/estelle (Node 18+), then estelle login and paste an API key from Settings → API keys. estelle doctor checks setup; estelle upgrade reports a newer release.
Claude Code: use the plugin, or claude mcp add --transport http estelle https://api.fatelabs.ca/mcp (browser sign-in), or add --header "Authorization: Bearer $ESTELLE_API_KEY". Run claude mcp list; if Estelle is pending approval or needs authentication, open /mcp in Claude Code and approve it.
Codex: estelle install-hooks writes hooks to ~/.codex/hooks.json (or $CODEX_HOME/hooks.json) and ~/.claude/settings.json, keeping other hooks. codex mcp add estelle -- estelle mcp-server adds the tools over stdio. Run /hooks in Codex to trust the hooks. estelle uninstall-hooks removes them.
Cursor: estelle login then estelle init --client cursor writes ~/.cursor/mcp.json. Other clients: MCP server https://api.fatelabs.ca/mcp with OAuth, or an Authorization: Bearer header.
Index a repository: from its root run estelle sweep. estelle reindex updates changed files.

## macOS, Linux and Windows | platforms
The estelle CLI runs natively on macOS and Linux, x86_64 and arm64. The hosted MCP server needs no local install. Windows: there is no native build yet; native Windows support is in progress. Use WSL today: in PowerShell as Administrator run wsl --install and restart; open Ubuntu; run the release installer: curl --proto '=https' --tlsv1.2 -fsSL https://github.com/uqeu/estelle-cli/releases/latest/download/install.sh | sh; add ~/.local/bin to PATH if needed; run estelle login. Install and run your coding agent inside WSL too, with the repository on the WSL file system, so hooks can find estelle. A full end-to-end WSL test has not been published.

## Command line | cli
Install with npm i -g @fatelabs/estelle, or the release installer: curl --proto '=https' --tlsv1.2 -fsSL https://github.com/uqeu/estelle-cli/releases/latest/download/install.sh | sh. Then estelle login (stores and verifies your API key) and estelle setup. Commands use the stored key or ESTELLE_API_KEY. Useful commands: sweep (index the repository), reindex, ask "question", recall "query", verify <file>, gate --base main, install-hooks, uninstall-hooks, mcp-server (stdio MCP), doctor, upgrade. In the terminal, /login connects your model account and /model selects a model.

## Find your way around the dashboard | dashboard
Sign in at app.fatelabs.ca. The left rail has Estelle (Ask), Monitoring, Atlas, Sessions, Automations, QA and Security, plus Settings at the bottom. Spaces under the rail lists sessions grouped by repository. Settings holds Profile, Preferences, Notifications, API keys, General, Members, Connections, Apps, Provider keys, Plans & billing, Usage & limits, Sessions & agent, Prism review, Atlas, Skills & playbooks, Activity, Code graph and Environment.

## Ask Estelle | ask
The Estelle page has an Agent | Ask switch, shown before the first message; it starts in Ask. Ask mode answers questions from your indexed code with sources ("N sources", "Claims without supporting evidence", "Show the evidence behind this") and never starts work; it offers "Switch to Agent mode and send it". Agent mode is a conversation: reads run straight away (answer about code, list repositories, automations, agents, check monitoring, list issues, check usage). Anything that costs credits or acts outwardly shows a card first: create, change, pause or resume an automation, launch an agent in a Silo (Codex or Claude Code), start a parallel job, start a CI run, plan Atlas pages. Choose Confirm or reply yes (ok, go ahead, do it); Change it edits. Only the newest card can be confirmed, each runs once, and an automation that may push code needs its risk box ticked. Agent mode always uses Estelle's model and credits. Each card is signed by the server, so only cards Estelle proposed can be confirmed.

## Sessions | sessions
Sessions from Claude Code and Codex stream through Estelle's hooks (plugin or estelle install-hooks); Silo and automation sessions appear too. The board has Running, Waiting for review and Ended columns. A running session idle for an hour shows as Idle in Waiting for review. Ended sessions older than a day are hidden; choose Show on the line that counts them. Sessions without a recorded state are listed under the no-verified-state line. Board or List view; filter by Status, Space, Harness, Runtime; right-click to Rename, Open, Copy link or Hide (this browser only). Open a session to see its conversation, subagents and panes: Git (recorded diff, review, commits; merge a PR or Fix with AI), Editor (read-only unless your own running Silo), Desktop (needs a Silo), Terminal (live in a Silo, otherwise recorded output) and Files.

## Automations | automations
Create one on the Automations page with Create automation → Describe it, write what starts it and what it does, choose Fill in the form (one model call; saves nothing), check it and choose Create automation. Or ask in Agent mode. Recurring: "every", "daily", "weekly", or pick Every hour, Every day, Weekdays, Once a week. One time: name the date and time; it turns off after running. Triggers: schedule, GitHub (App), Linear, Slack, inbound webhook (API key), other apps from the catalogue. Sentry and PagerDuty triggers cannot fire yet. New automations run in a Silo; the work path runs without one, and automations with no repository always use it. "failed: Silos are not configured on this server — the run did not start" means the automation is set to a Silo and that server has no Silo backend; nothing ran and it is not silently moved to the work path. "Completed" on a Silo run means the task reached the agent. After 5 failed runs in a row it is Auto-paused. More menu: Run history, Open latest session, Copy automation id, Save as template, Delete.

## Silos | silos
A Silo is your own cloud computer started around a repository; up to 4 live Silos per account. Launch an agent from Agent mode (Codex by default, or Claude Code with your own Claude subscription or Anthropic key), or Fix with AI on a pull request. In the session's Desktop pane: Watch (Close viewer), Take control (Resume Estelle hands back), Stop agent, and Shut down Silo when idle or paused. A paused Silo wakes when given a task. A running Silo spends credits for its run time; paused time is not charged. Out of credits, Estelle pauses the Silo. A Silo paused for 24 hours is shut down and its computer removed.

## Atlas | atlas
Atlas writes a wiki of an indexed repository. Open Atlas, choose New Atlas (or use the generator shown when none exists), pick a repository, choose Generate Atlas, set a credit ceiling, tick I approve these limits and uncapped input cost., and Start. When the outline is ready choose Generate pages, approve, Start, then Open Atlas. With Estelle's model it spends credits up to your ceiling (input cost is not capped); with your own provider key it spends no credits. Regenerate appears when the repository has moved. No automatic refresh schedule yet. Settings → Atlas sets effort and repository groups.

## Estelle CI | ci
Commit .estelle/ci.yml to run CI in a Silo on pushes and on pull requests opened, updated or reopened (not from forks). It needs the GitHub App and reports a GitHub check named Estelle CI. The file is a subset of GitHub Actions: top-level name, on (push, pull_request, optional branches), env, jobs; job name, needs, env, runs-on (recorded only), steps; step run or uses, name, env, working-directory, timeout-minutes 1-15, with. Allowed actions: actions/checkout (skipped), actions/setup-python with python-version, actions/setup-node with node-version, pinned and exact (a version check, not an install). Refused: ${{ }} expressions, if, strategy/matrix, services, container, permissions, concurrency, schedule, reusable workflows, other actions. Limits: 64 KiB per file, 20 jobs, 50 steps, 8,000 characters per command. Jobs run in needs order; the first failing step stops the run. A file refused before the run gets no check; see the GitHub App webhook delivery log.

## Integrations | connections
GitHub: Settings → Connections → Link GitHub, install the Estelle GitHub App on the owner of your repositories, choose Connect on the installation, then choose the repositories to read (In memory / Not read yet). estelle github link does the linking from a terminal. Slack: Settings → Apps → Connect, then /invite @Estelle in a channel; set channel access None, Read or Read & post; disconnect by removing the app in Slack. Linear, Jira, Notion: Connect and approve. Other apps connect from the apps catalogue; automations can then use their tools. Choose Recheck to refresh status.

## Settings, keys and team | settings
API keys: Settings → API keys, optional label, Create key, copy it now (shown once; only a hash is kept). Rename changes the label; Revoke is immediate with no confirmation. Keys start with estelle_live_, have full access and do not expire. Team: on the Team plan, Settings → Members, Create team, Send invite by email (they join after accepting), Update seats (prorated). Roles in the dashboard: admin (invite, remove, change roles, webhooks, team settings, autonomy ceiling) and member (shared memory, search, run agents within the ceiling).

## Explore code | code-graph
The code graph represents files, symbols, definitions, and dependencies in a repository. Select a symbol to inspect its source and relationships. Use find_definition and locate to find real definitions; use find_usages and blast_radius to inspect callers and change impact. A stale or missing index cannot prove a symbol is absent. Refresh the repository and retry when Estelle reports insufficient coverage.

## Memory and sessions | memory-workspace
The memory library organizes persisted knowledge cards and their sources. Saved cards can include decisions, project context, concepts, and records distilled from sessions. Open a card to read its body, inspect sources, and see saved versions. Distil sessions extracts knowledge from available session records. No new cards can mean either no input runs or no new durable knowledge; the result reports that distinction. Sessions is a conversation history, not a count of concurrent agents.

## How memory works | memory
Call estelle_resume at the start of a session to recover relevant context. list_sessions and get_session revisit earlier conversations. memory_chat asks about saved knowledge. estelle_checkpoint preserves context for a later session. Persistent memory can carry decisions and their rationale across restarts and context limits. Retrieval is scoped to the account and team permissions. A source citation gives provenance; it does not automatically prove every conclusion in a memory.

## Grounding and refusals | grounding
Use verify to check a claim against repository evidence. gate checks a proposed diff deterministically; review adds a rival model review. Findings point back to code evidence. A refusal such as could-not-verify, not swept, or stale means Estelle lacks sufficient current evidence. It is not proof that the symbol is absent or that the code is wrong. Refresh the index or provide the missing evidence and retry. A clean local test is evidence about that test, not a production deployment.

## MCP tools | tools
Repository navigation: verify, find_definition, locate, find_usages, blast_radius, dependency_path. Change checks: gate and review. Persistent context: estelle_resume, list_sessions, get_session, memory_chat, estelle_checkpoint. External package research: research_ask. Production investigation: monitor tools on entitled plans. Use skill_find to discover available workflows. Tool availability depends on the connection, configured capabilities, and account entitlements.

## Automatic pull request review | pr-review
Connect the Estelle GitHub App and enable inline review for the repository. Pull request opened, synchronize, and reopened events can trigger review. Mention @estelle review for a manual review. Findings are posted as review comments. The default workflow proposes changes for a human to review and merge.

## Monitoring | monitoring
Monitoring connects production signals to affected code and reviewable repair evidence. Inspect logs, alerts, uptime, and subjects in the dashboard. An empty issue feed does not prove that monitoring is connected or that a service is healthy. Check available service coverage and the selected time window. Stored counters without retained traces are not proof of current traffic. Production monitoring features require the appropriate account entitlement.

## Permissions and autonomy | autonomy
The default is propose-only: Estelle proposes a grounded fix, checks it through the gate and reproduction tests, and presents a reviewable pull request. Autonomy is opt-in, tiered, and proof-gated. Auto-merge requires explicit opt-in and passing verification; failing a guard falls back to a reviewable PR. Protected changes involving auth, billing, schema, security, or deployment remain human-gated. Auto-deploy is not shipped. Workspace settings contains the autonomy controls.

## Authentication | authentication
Plugin and hosted MCP connections use OAuth sign-in. Direct API calls use an Estelle bearer token in the Authorization header. Production Estelle keys start with estelle_live_. Create and revoke keys in Settings → API keys. Keep credentials in environment variables or a secret manager, not source control. Never paste an API key into the docs chat. A model-provider key is separate from your Estelle account credential.

## Call the API | api
The OpenAI-compatible API base URL is https://api.fatelabs.ca/v1. The model id is estelle. Send Authorization: Bearer with your Estelle credential. GET /v1/models lists the available model surface. POST /v1/chat/completions accepts the OpenAI-style messages array. Keep secrets on your server. Your provider connection supplies the underlying model.

## Chat completions | chat
POST https://api.fatelabs.ca/v1/chat/completions with a JSON body containing model: estelle and messages: an array of role/content messages. Send Content-Type: application/json and Authorization: Bearer with your Estelle key. Use a non-streaming request. The endpoint returns the completed answer in a JSON response at choices[0].message.content. Estelle chooses its sampling settings; the documented endpoint does not support response_format. Consult the API reference for complete request fields.

## Errors and limits | errors
An authentication error means the credential could not be accepted. An entitlement or budget error needs account or plan review. Rate limits require backing off and retrying. A grounding refusal is an evidence result, not an authentication error. Never interpret an unavailable data source as a zero count. For account-specific billing, usage, and access questions, sign in and explicitly include your account in Ask AI.

## Models and providers | providers
Keep the model and plan you already use. Plugin users select their model in the host coding client. Native CLI users connect their model account with /login and select it with /model. Estelle’s account credential and model-provider connection have separate purposes. See the provider guides for the supported login or API-key setup for your provider.

## Teams and roles | teams
Settings → Members manages your team and permitted membership actions. Access depends on your role and the repositories granted to the workspace. Your personal profile appears across the workspace. Account-specific membership and billing information requires a signed-in session; the public documentation cannot infer your team’s configuration.

## Billing and usage | billing
Settings → Plans & billing: Monthly or Yearly, Upgrade to / Downgrade to a plan, Team with at least 2 seats and Start Team, Open billing portal for card and invoices, Cancel plan (active until period end), and the Promo code field. Settings → Usage & limits shows usage as a percentage: 5 hours and 7 days roll, 30 days resets on the billing date; Free shows one meter that does not reset. Also Last 7 days by surface, Monthly spend limit (owners and billing admins), Add more usage (top-up, Pro/Ultra/Max at a limit) and an Analytics tab. Prices are on the pricing page.

## Support | support
Use the documentation to set up your agent and investigate connection problems. Run estelle doctor for CLI connection diagnostics. Contact Fate Labs through the site’s Contact page for help. Never include secret keys in a support message or a docs question.

## Troubleshooting | troubleshooting
Sessions not showing: check the dashboard account matches the account that owns your CLI key (curl -s https://api.fatelabs.ca/me -H "Authorization: Bearer $ESTELLE_API_KEY" returns its email); install the hooks (plugin or estelle install-hooks; in Codex trust them with /hooks); on Windows run the agent and estelle inside WSL; choose Show for ended sessions older than a day; restart the agent after installing. Tools missing: claude mcp list; if pending approval or needing authentication, open /mcp in Claude Code and approve. "No model is connected": add a provider key or choose a plan. "Out of Estelle Credits": wait for the window, top up or change plan; Agent mode always needs credits. Prompt blocked as an sk- key (for example a branch named ask-flow-...): fixed in CLI 0.4.2; check estelle --version and run estelle upgrade. "Could not verify" or "not swept": run estelle sweep and retry; it is not proof of absence.

## BYOK and privacy | privacy
Over MCP, reasoning stays on your existing coding client’s model connection. On Estelle’s API path, the model comes from the provider configured in Workspace settings → Model pool. Provider credentials are stored encrypted at rest and are not returned by account read endpoints. Your Estelle key is stored as a hash. The docs assistant is separate: it uses a server-side model connection to answer public documentation questions. Including your account is an explicit choice and shares only limited account fields and relevant repository names, session metadata, job states, and monitoring counts with that model, not your API keys, repository contents, or private memories.

## List models | models
GET https://api.fatelabs.ca/v1/models lists the models available to your Estelle credential. The documented model id is estelle, which routes to your configured provider. Use Authorization: Bearer with your Estelle credential. This is a connectivity check for the API base URL and credential.

## Rate limits | limits
A 429 response means a request limit was reached. Honor Retry-After when present and retry with exponential backoff. Account-specific limits depend on the service and plan. Ask AI has separate question limits; its model calls are not an unlimited public API. Check current pricing and the account’s Usage page for the relevant plan information.