# Matilda

> Matilda is an AI coding agent and assistant built by Maincode in Melbourne and served from Australian infrastructure. It ships as a CLI (Matilda Code), a desktop app, a mobile chat app, and two TypeScript SDKs over an onshore API.

## The pieces

- **Matilda** — the model. It reads code, reasons about it, and proposes edits and commands. It never acts on a machine by itself.
- **Matilda Code** — the CLI coding agent. It drives the model in a loop against your working tree: read, plan, act, verify.
- **Matilda Desktop** — the same agent in a native window for macOS, Windows, and Linux.
- **Matilda Chat** — the conversational surface, on the web and on iOS and Android.
- **Client SDK** — TypeScript access to chat, conversations, files, feedback, devices, and auth.
- **Agent SDK** — TypeScript agents and runners with client-side tool execution on top of the same API.

## Quick facts

- Install the CLI: `npm install -g @maincode-ai/matilda-code@latest` (Node.js 22 or newer). It installs `matilda` and `matilda-code`, which are the same binary.
- Sign in interactively: `matilda auth login`. The refresh token is written to `~/.matilda/matilda-auth.json`.
- Authenticate a pipeline: set `MATILDA_API_KEY`. Keys are `mc_live_` tokens, created with the `matilda-key` CLI or the client SDK.
- API base URL: `https://matilda.maincode.com/api`.
- Install the SDKs: `npm install @maincode-ai/matilda-client-sdk` or `npm install @maincode-ai/matilda-agent-sdk` (Node.js 20 or newer).
- Run headless: `matilda -p "<prompt>"`, with `-o text|json|stream-json` for the output shape.
- Approval modes, cycled mid-session with Shift+Tab: `plan` → `default` → `auto-edit` → `auto` → `yolo`.
- Project memory: `MATILDA.md` in the repo root is shared with the team, `~/.matilda/MATILDA.md` follows you across projects, `.matilda/MATILDA.local.md` is personal to one project.
- Model and provider selection are not exposed. Matilda core owns routing, safety, server-side tools, and policy.

## Reading this site as an agent

- Any docs page is available as markdown at the same URL with `.md` appended: https://maincode.com/docs/installation.md
- https://maincode.com/llms-full.txt is every docs page concatenated into one file.
- https://maincode.com/sitemap.xml lists every URL on the site.

## Products

- [Matilda Code](https://maincode.com/matilda-code): The CLI in your terminal, IDE, and CI: read the repo, run the tests, open the PR.
- [Matilda Desktop](https://maincode.com/matilda-desktop): An agentic workspace in a native window, with downloads for macOS, Windows, and Linux.
- [Matilda Chat](https://maincode.com/matilda-chat): The assistant itself: reasoning you can read, memory that stays in your repo, free on iOS and Android.
- [API platform](https://maincode.com/api-platform): The Matilda API, served onshore from Melbourne.
- [Documentation](https://maincode.com/docs): Install Matilda Code, run it in CI, and ship.

## Matilda Code

- [Install Matilda Code](https://maincode.com/docs/installation.md): Install the CLI, sign in, and open your first session.
- [Core concepts](https://maincode.com/docs/core-concepts.md): The model, the agent, and the action layer.
- [How an agent run works](https://maincode.com/docs/agent-runs.md): Read, plan, act, verify, and the five approval modes.
- [Context and memory](https://maincode.com/docs/retention.md): What Matilda holds in a session, and what carries across them.
- [Headless and CI](https://maincode.com/docs/headless.md): Run Matilda Code from scripts, pipelines, and other automation.
- [CLI reference](https://maincode.com/docs/cli-reference.md): Commands, flags, and settings for the matilda CLI.

## Client SDK

- [Client SDK quickstart](https://maincode.com/docs/client-sdk-overview.md): Install the client SDK, send your first message, and stream a response.
- [Configuration](https://maincode.com/docs/client-sdk-configuration.md): Constructor options, trusted base URLs, and per-instance isolation.
- [Authentication](https://maincode.com/docs/client-sdk-authentication.md): Browser PKCE, device flow, token persistence, and API keys for the client SDK.
- [Chat](https://maincode.com/docs/client-sdk-chat.md): Send messages and get complete responses from the chat API.
- [Streaming](https://maincode.com/docs/client-sdk-streaming.md): Full event streaming from the chat API.
- [Text helpers](https://maincode.com/docs/client-sdk-text-helpers.md): Filter a chat stream down to assistant text, with deduped deltas.
- [Structured output](https://maincode.com/docs/client-sdk-structured-output.md): Constrain a chat response to a zod schema and get a typed object back.
- [Durable streaming](https://maincode.com/docs/client-sdk-durable-streaming.md): Resume an interrupted stream from the last received event.
- [Conversations](https://maincode.com/docs/client-sdk-conversations.md): List, retrieve, rename, and rate the threads behind a conversationId.
- [Multi-turn conversations](https://maincode.com/docs/client-sdk-multi-turn.md): Carry context across turns with conversationId.
- [Files](https://maincode.com/docs/client-sdk-files.md): Upload one file or many, then attach the IDs to a chat request.
- [Feedback and devices](https://maincode.com/docs/client-sdk-feedback-devices.md): Report harmful content and manage push notification devices.
- [Error handling](https://maincode.com/docs/client-sdk-error-handling.md): Typed error classes, chat error codes, and the SSE stall watchdog.
- [Recipes](https://maincode.com/docs/client-sdk-recipes.md): Six runnable examples, from a CLI chatbot to durable stream recovery.
- [Exports](https://maincode.com/docs/client-sdk-exports.md): Every class, interface, and type the client SDK package exports.

## Agent SDK

- [Agent SDK quickstart](https://maincode.com/docs/agent-sdk-overview.md): Install the agent SDK and run your first agent.
- [Configuration](https://maincode.com/docs/agent-sdk-configuration.md): Configure the shared core, or isolate a Runner with its own client and auth.
- [Authentication](https://maincode.com/docs/agent-sdk-authentication.md): AgentAuth on the runner — login, restore, and automatic token refresh.
- [Agent](https://maincode.com/docs/agent-sdk-agent.md): Configure agents with instructions, tools, compaction, and resumable state.
- [Run](https://maincode.com/docs/agent-sdk-run.md): Run a prompt to completion and get the final output.
- [Stream](https://maincode.com/docs/agent-sdk-stream.md): Full event streaming from an agent run.
- [Text helpers](https://maincode.com/docs/agent-sdk-text-helpers.md): Filter a run's stream to assistant text, plus the module-level run and stream helpers.
- [Structured output](https://maincode.com/docs/agent-sdk-structured-output.md): Constrain an agent turn to a zod schema with runObject and streamObject.
- [Client tools](https://maincode.com/docs/agent-sdk-client-tools.md): Tools that execute locally, wired into the agent loop.
- [Session](https://maincode.com/docs/agent-sdk-session.md): Stateful multi-turn conversations with a session object.
- [Stream resume](https://maincode.com/docs/agent-sdk-stream-resume.md): Durable handles and resuming interrupted agent runs.
- [Files](https://maincode.com/docs/agent-sdk-files.md): The runner files resource — upload, retrieve, and attach file IDs to a run.
- [Conversations](https://maincode.com/docs/agent-sdk-conversations.md): Read, rename, and rate conversation threads from the runner.
- [Feedback](https://maincode.com/docs/agent-sdk-feedback.md): File bug reports from your application.
- [Error handling](https://maincode.com/docs/agent-sdk-error-handling.md): Run and stream errors, exponential-backoff retries, and partial results after a failure.
- [Multi-agent patterns](https://maincode.com/docs/agent-sdk-multi-agent.md): Compose, parallelise, and route between agents.
- [Recipes](https://maincode.com/docs/agent-sdk-recipes.md): Six runnable examples, from a device-flow CLI agent to a multi-agent review pipeline.
- [Exports](https://maincode.com/docs/agent-sdk-exports.md): Classes, functions, constants, and types exported by the agent SDK package.

## Optional

- [Research](https://maincode.com/research): Peer-reviewed papers from the Maincode lab: optimisers, safe RL, million-token serving, and vision-language reasoning.
- [Blog](https://maincode.com/blog): Notes from the team building Matilda.
- [About Maincode](https://maincode.com/company): An Australian AI research company: the mission, the principles, and the hardware.
- [Contact](https://maincode.com/contact): Talk to the team in Melbourne.
- [Privacy policy](https://maincode.com/legal/privacy): How Maincode handles your data.
- [Terms of service](https://maincode.com/legal/terms): The terms covering Matilda and Matilda Code.