# Introduction
Source: https://docs.randomlabs.ai/en/getting-started/introduction



Slate is the *first* frontier agent in the wild that is built for swarm orchestration.

# What Makes Slate Different?

* Slate works *with* you across long, multi-hour sessions.
* Slate automatically selects the right model for the job. For example with slate you can plan/talk to claude and search with glm and execute with codex and slate handles it.
* Have slate in parallel deeply research your problem
* Parallelize working and orchestration of many tasks at once.

Learn more about orchestration, deep research, and parallel work in [Orchestration & Tracing](/en/using-slate/orchestration).

```
"Slate is the best debugging tool I have." 
- Stealth founder, Fintech, NYC.
```

## Get Started

Ready to try Slate? Follow our quickstart guide to install and run your first commands.

<Card title="Quickstart Guide" icon="rocket" href="/en/getting-started/quickstart">
  Install Slate and complete your first task.
</Card>

## Next Steps

<CardGroup>
  <Card title="Using Slate" icon="book-open" href="/en/using-slate">
    Learn about Slate's capabilities and commands in detail.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.randomlabs.ai/en/getting-started/quickstart

Set up Slate and work on your first task.

# Quickstart Guide

<Warning>
  Slate may not work on Windows. If you are on Windows, we recommend using WSL (Windows Subsystem for Linux).
</Warning>

<Warning>
  Significant flashing and flickering has been observed in the TUI when running Slate inside tmux.
</Warning>

## Installation

Run the following command to install Slate:

```bash theme={null}
npm i -g @randomlabs/slate
```

Once installed, run Slate with:

```bash theme={null}
slate
```

## Your First Task

Let's complete a simple task to get familiar with Slate.

### Step 1: Start Slate in Your Project

Navigate to your project directory and initialize Slate:

```bash theme={null}
cd /path/to/your/project
slate
```

### Step 2: Sign In

On a fresh launch, Slate requires authentication with Random Labs. Press Enter to begin device authorization, then complete the browser flow with the code shown in the terminal.

### Step 3: Complete First-Run Setup

Onboarding asks for your terminal background, multiline input preference, and model source: your ChatGPT/Codex subscription, SuperGrok subscription, or Slate credits. Press Esc to skip onboarding, and run `/onboarding` to restart it later.

<Note>
  What you should see: Slate shows your workspace path and Quick Start hints like `/help` and `/docs`.
</Note>

### Step 4: Try a Simple Task

Ask Slate to help you with a specific task:

```bash theme={null}
Please review the architecture of my entire codebase creating an ARCH.md and then give me ways I can improve it.
```

Slate will search through your files and analyze the entire codebase, and then review the results to understand how to improve it.

## Next Steps

Now that you're up and running, explore Slate's full capabilities:

<CardGroup>
  <Card title="Using Slate" icon="book-open" href="/en/using-slate">
    Learn about all of Slate's features and commands.
  </Card>
</CardGroup>

## Need Help?

If you encounter any issues:

1. Check the [troubleshooting section](/en/using-slate/troubleshooting)
2. Reach out to our [team](mailto:team@randomlabs.ai)


# Configuration
Source: https://docs.randomlabs.ai/en/using-slate/configuration

Customize Slate's behavior with slate.json

<Tip>
  We support `--dangerously-skip-permissions` (alias: `--yolo`) to bypass permission prompts. See **Permissions** at the bottom of this page.
</Tip>

Slate can be configured using a `slate.json` (or `slate.jsonc`) file placed in your project root or global config directory.

```jsonc theme={null}
{
  "$schema": "https://randomlabs.ai/config.json",
  "permission": {
    "*": "allow",
    "bash": "ask"
  }
}
```

## File locations

Configuration files are **merged together**, not replaced. Settings from all sources are combined — later sources override only conflicting keys.

<Steps>
  <Step title="Global config">
    User-wide preferences at `~/.config/slate/slate.json`. Applies to all projects.
  </Step>

  <Step title="Project config">
    `slate.json` in your project root (or any parent up to the git root). Safe to check into git.
  </Step>

  <Step title="Inline override">
    `SLATE_CONFIG_CONTENT` env var as a JSON string. Highest precedence.
  </Step>
</Steps>

<Tip>
  Project config applies only to that project. Global config applies everywhere.
</Tip>

## Options

<Note>
  Keybind syntax supports `ctrl`, `alt` (also `meta`/`option`), `shift`, and `super`, plus `<leader>` combos. Use commas for alternatives (for example, `ctrl+n,down`), `none` to disable a binding, and note leader mode times out after 2s.
</Note>

<Note>
  Theme config supports built-in `dark` and `light`, with `/theme` as the in-app picker. Advanced theme JSON can define `defs` and `theme` with `$ref` values and per-token `dark`/`light` variants.
</Note>

<AccordionGroup>
  <Accordion title="General">
    | Field     | Type      | Description                                 |
    | --------- | --------- | ------------------------------------------- |
    | `privacy` | `boolean` | Disables telemetry and logging when `true`. |
  </Accordion>

  <Accordion title="Permissions">
    Control which actions require your approval before Slate proceeds.

    ```json theme={null}
    {
      "$schema": "https://randomlabs.ai/config.json",
      "permission": {
        "*": "allow",
        "bash": "ask",
        "read": {
          "*.env": "ask",
          "*": "allow"
        }
      }
    }
    ```

    Each permission key maps to an action (`"allow"`, `"ask"`, or `"deny"`), or a pattern object for fine-grained control.

    | Permission  | Description                               |
    | ----------- | ----------------------------------------- |
    | `*`         | Wildcard — sets the default for all tools |
    | `read`      | Reading files                             |
    | `edit`      | Writing / editing files                   |
    | `bash`      | Running shell commands                    |
    | `grep`      | Searching file contents                   |
    | `webfetch`  | Fetching web pages                        |
    | `websearch` | Web searches                              |
  </Accordion>

  <Accordion title="Models">
    Set preferred default models for each slot with the `/models` dialog or `slate.json` under `models`. Model IDs shown here are examples only and are not stability promises.

    ```json theme={null}
    {
      "$schema": "https://randomlabs.ai/config.json",
      "models": {
        "main": { "default": "anthropic/claude-opus-4.6" },
        "subagent": { "default": "anthropic/claude-sonnet-4.6" },
        "search": { "default": "anthropic/claude-haiku-4.5" },
        "reasoning": { "default": "openai/gpt-5.3-codex" }
      }
    }
    ```

    | Slot               | Config key               | Description                                                                |
    | ------------------ | ------------------------ | -------------------------------------------------------------------------- |
    | Main               | `models.main`            | Primary model for the main agent                                           |
    | Subagent (Execute) | `models.subagent`        | Execution-oriented subagents — edits, commands, task completion            |
    | Subagent (Search)  | `models.search`          | Search-oriented subagents — exploration, retrieval, codebase investigation |
    | Program Search     | `models.program_search`  | Model for program read/search agents                                       |
    | Program Execute    | `models.program_execute` | Model for program execution agents                                         |
    | Reasoning          | `models.reasoning`       | Complex reasoning tasks                                                    |
    | Vision             | `models.vision`          | Vision-enabled multimodal tasks                                            |
    | Image Gen          | `models.image_gen`       | Image generation tasks                                                     |

    ### Model presets (modelSets)

    `modelSets` define named presets that can configure the same model slots used by `models`. Configure presets in `slate.json` and select them from `/models`.

    ```json theme={null}
    {
      "$schema": "https://randomlabs.ai/config.json",
      "modelSets": [
        {
          "id": "fast-review",
          "name": "Fast review",
          "description": "Example preset for quick code review",
          "config": {
            "main": { "model": "anthropic/claude-sonnet-4.6" },
            "program_search": { "model": "anthropic/claude-haiku-4.5" },
            "reasoning": { "model": "openai/gpt-5.3-codex", "variant": "high" }
          }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Providers">
    Use `/providers` to choose a provider and connect using that provider's auth method. Then return to `/models` to pick models backed by the connected provider.

    In `slate.json`, `models.{slot}.default` is still a model ID string. Provider identity is handled by the UI and runtime selections, not by embedding provider credentials in the model slot.

    **Bedrock BYOK:** API-key auth requires `region`. IAM auth requires `region`, `accessKeyId`, `secretAccessKey`, and optional `sessionToken`. Enter credentials in `/providers`, not `slate.json`.
  </Accordion>

  <Accordion title="MCP Servers">
    Connect Model Context Protocol servers for additional tools.

    <CodeGroup>
      ```json Local Server theme={null}
      {
        "$schema": "https://randomlabs.ai/config.json",
        "mcp": {
          "my-tool": {
            "type": "local",
            "command": ["npx", "-y", "@my-org/mcp-server"],
            "environment": { "API_KEY": "{env:MY_API_KEY}" },
            "enabled": true
          }
        }
      }
      ```

      ```json Remote Server theme={null}
      {
        "$schema": "https://randomlabs.ai/config.json",
        "mcp": {
          "my-remote": {
            "type": "remote",
            "url": "https://mcp.example.com/mcp",
            "headers": { "Authorization": "Bearer {env:MY_TOKEN}" },
            "enabled": true
          }
        }
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Custom Commands">
    Define custom `/commands` for repetitive tasks.

    ```jsonc theme={null}
    {
      "$schema": "https://randomlabs.ai/config.json",
      "command": {
        "commit": {
          "description": "Write a commit message for staged changes",
          "template": "Write a concise git commit message for these changes: $ARGUMENTS",
          "agent": "build"
        },
        "review": {
          "description": "Review the code in a file",
          "template": "Review @$ARGUMENTS for correctness, clarity, and edge cases."
        }
      }
    }
    ```

    Invoke with `/commit` or `/review` in the TUI. `$ARGUMENTS` captures text typed after the command name.
  </Accordion>

  <Accordion title="Advanced">
    Additional configuration keys supported in `slate.json`. Some are partially wired and may evolve.

    | Key                  | Type                    | Description                                                        |
    | -------------------- | ----------------------- | ------------------------------------------------------------------ |
    | `terminal`           | `object`                | Terminal/PTY settings (e.g., `maxConcurrent`)                      |
    | `externalWorkspaces` | `string[]`              | Default external workspace paths attached to new sessions          |
    | `experimental`       | `object`                | Experimental toggles and feature flags                             |
    | `dataTier`           | `"normal" \| "privacy"` | Data retention tier                                                |
    | `autoupdate`         | `boolean \| "notify"`   | Auto-update behavior                                               |
    | `server`             | `object`                | Server-mode configuration (forward-compatibility, partially wired) |
    | `modelSets`          | `object[]`              | Named model presets; see **Model presets (modelSets)** in Models   |
    | `skills`             | `object`                | Additional skill folder paths                                      |
    | `watcher`            | `object`                | File watcher ignore patterns                                       |
    | `instructions`       | `string[]`              | Extra instruction files or patterns to include                     |
  </Accordion>
</AccordionGroup>

***

## Environment variables

| Variable                             | Description                                                                                                                                                                                                                                                                                   |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SLATE_API_KEY`                      | Skip the authentication dialog on launch                                                                                                                                                                                                                                                      |
| `SLATE_CONFIG`                       | Path to a custom config file                                                                                                                                                                                                                                                                  |
| `SLATE_CONFIG_DIR`                   | Path to a custom config directory                                                                                                                                                                                                                                                             |
| `SLATE_CONFIG_CONTENT`               | Inline JSON config (highest precedence)                                                                                                                                                                                                                                                       |
| `SLATE_PERMISSION`                   | JSON permission config override                                                                                                                                                                                                                                                               |
| `SLATE_DISABLE_PROJECT_CONFIG`       | Disable project-level `slate.json` discovery                                                                                                                                                                                                                                                  |
| `SLATE_DANGEROUSLY_SKIP_PERMISSIONS` | Set to `1` to bypass all permission checks (hard bypass). Also set automatically by `--dangerously-skip-permissions` / `--yolo`. To restore normal permissions, restart without `--yolo` and set this env var to `0` (or unset it). ⚠️ Skips all safeguards including destructive operations. |

***

## CLI flags

Run `slate --help` to see all available flags.

<AccordionGroup>
  <Accordion title="Models">
    | Flag                       | Description                                  |
    | -------------------------- | -------------------------------------------- |
    | `--model <id>`             | Set the default model for the session.       |
    | `--model-main <id>`        | Set the main agent model.                    |
    | `--model-search <id>`      | Set the search-oriented subagent model.      |
    | `--model-subagent <id>`    | Set the execution-oriented subagent model.   |
    | `--model-reasoning <id>`   | Set the reasoning model.                     |
    | `--model-vision <id>`      | Set the vision model.                        |
    | `--model-image-gen <id>`   | Set the image generation model.              |
    | `--thinking-level <level>` | Set the thinking level for supported models. |

    Program slots (`program_search`, `program_execute`) do not have dedicated CLI flags. Configure them with `/models` or `slate.json` under `models` or `modelSets`.
  </Accordion>

  <Accordion title="Sessions">
    | Flag            | Alias | Description                                                                                             |
    | --------------- | ----- | ------------------------------------------------------------------------------------------------------- |
    | `--continue`    | `-c`  | Resume the most recent session instead of starting a new one. Useful for picking up where you left off. |
    | `--resume <id>` |       | Resume a specific session by its session ID.                                                            |
    | `--recent`      | `-r`  | Open the session picker on launch so you can choose which past session to load.                         |
  </Accordion>

  <Accordion title="Sending a prompt">
    | Flag              | Alias | Description                                                                                        |
    | ----------------- | ----- | -------------------------------------------------------------------------------------------------- |
    | `<prompt>`        |       | Pass a prompt directly as a positional argument. Slate runs the prompt and exits after completion. |
    | `--prompt <text>` | `-p`  | Start interactive mode with an initial prompt.                                                     |
  </Accordion>

  <Accordion title="Queue file">
    | Flag             | Alias | Description                                                                                                                              |
    | ---------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------- |
    | `--queue <file>` | `-q`  | Load a markdown file and queue messages separated by `---` delimiters. Each block between `---` lines becomes a separate queued message. |
  </Accordion>

  <Accordion title="Workspace">
    | Flag                 | Alias | Description                                                                                               |
    | -------------------- | ----- | --------------------------------------------------------------------------------------------------------- |
    | `--workspace <path>` | `-w`  | Add a directory to Slate's workspace. Can be specified multiple times to add several directories at once. |
  </Accordion>

  <Accordion title="Headless / scripting">
    Headless mode lets you use Slate non-interactively — pipe in prompts, pipe out structured results — useful for CI or scripting.

    | Command / Flag                       | Description                                                       |
    | ------------------------------------ | ----------------------------------------------------------------- |
    | `run [prompt]`                       | Run a one-shot prompt non-interactively.                          |
    | `run --output-format <fmt>`          | Set output format: `text`, `json`, or `stream-json`.              |
    | `run --input-format <fmt>`           | Set stdin format: `text` or `stream-json`.                        |
    | `run --workspace <path>`             | Add one or more workspace directories for this run.               |
    | `run --dangerously-skip-permissions` | Bypass permission checks for automation/CI runs. Alias: `--yolo`. |

    Note: use `--output-format stream-json` for JSONL output in this CLI. The standalone `--stream-json` flag is not supported on `run`.

    ```bash theme={null}
    # Run a one-shot prompt and get JSONL output
    slate run "Summarize the changes in the last commit" --output-format stream-json

    # Pipe a prompt in as plain text
    echo "What does this codebase do?" | slate run --output-format json --input-format text

    # Pipe JSONL stdin and interpret it as stream-json input
    printf '{"role":"user","content":"What changed in the last commit?"}\n' | slate run --output-format json --input-format stream-json
    ```
  </Accordion>

  <Accordion title="Server mode">
    Server mode is command-based. Start the server with `serve`, then connect with `attach`.

    Upgrade command: `slate upgrade [target]` (optional target version). Use `--method` / `-m` to choose install method: `curl`, `npm`, `pnpm`, `bun`, `brew`, `choco`, or `scoop`.

    | Command / Flag             | Default   | Description                                                                                       |
    | -------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
    | `serve`                    |           | Start Slate as an HTTP API server instead of launching the TUI.                                   |
    | `serve --port <number>`    | `7777`    | Port to listen on in server mode.                                                                 |
    | `serve --host <string>`    | `0.0.0.0` | Host to bind to in server mode.                                                                   |
    | `attach <url>`             |           | Connect the TUI to an already-running Slate server (for example `http://localhost:7777`).         |
    | `attach --dir <path>`      | local cwd | Set the local working directory while attached to a server.                                       |
    | `attach --session <id>`    |           | Resume a specific session while attached.                                                         |
    | `attach --continue`        |           | Continue the latest session while attached.                                                       |
    | `attach --fork`            | `false`   | Fork the session when continuing. Requires `--continue` or `--session`.                           |
    | `attach --password <text>` | env       | Basic auth password for server attach. Alias: `-p`. Defaults to `SLATE_SERVER_PASSWORD` when set. |

    ```bash theme={null}
    # Terminal 1 — start the server
    slate serve --port 7777

    # Terminal 2 — connect the TUI to it
    slate attach http://localhost:7777 --dir /path/to/workspace
    ```
  </Accordion>

  <Accordion title="Permissions">
    | Flag                             | Default | Description                                                                                                                                                                                                                                                                                                 |
    | -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `--dangerously-skip-permissions` | `false` | Bypass all permission checks including config plan rules. Alias: `--yolo`. Sets `SLATE_DANGEROUSLY_SKIP_PERMISSIONS=1` internally. Intended for CI pipelines and automation where interactive prompts are not possible. ⚠️ Auto-allows all tool calls including destructive shell commands and file writes. |

    Restart without `--yolo` and set `SLATE_DANGEROUSLY_SKIP_PERMISSIONS` to `0` (or unset it) to restore normal permission prompts.

    ```bash theme={null}
    # Run non-interactively with all permissions bypassed
    slate run "Run the test suite and fix any failures" --output-format stream-json --dangerously-skip-permissions
    ```
  </Accordion>
</AccordionGroup>


# Hotkey Reference
Source: https://docs.randomlabs.ai/en/using-slate/hotkey_reference

Complete reference of all commands and keyboard shortcuts available in Slate CLI

<Info>
  This reference covers all available commands and hotkeys in Slate CLI, with interaction commands prioritized for quick access.
</Info>

## Quick Reference

<Tabs>
  <Tab title="Essential Shortcuts">
    <AccordionGroup>
      <Accordion title="Agent Interaction">
        <Steps>
          <Step title="Ctrl+X then E">
            **Open external editor** - Compose long prompts in your preferred editor
          </Step>

          <Step title="Ctrl+X then M">
            **Open model picker** - Switch between available models
          </Step>

          <Step title="Ctrl+X then P">
            **Open providers** - Manage provider connections
          </Step>

          <Step title="Ctrl+B">
            **Toggle session sidebar** - Show or hide the session sidebar
          </Step>

          <Step title="Ctrl+R">
            **Rename session** - Rename the current session
          </Step>

          <Step title="Ctrl+T">
            **Cycle model variant** - Switch to the next model variant
          </Step>

          <Step title="Shift+Tab">
            **Toggle permission mode** - Switch the current session permission mode
          </Step>

          <Step title="Enter">
            **Send / Enter action** - Sends your prompt normally; if the agent is already running, it performs the current Enter mode action
          </Step>

          <Step title="Tab">
            **Queue while busy** - Queues the current message under the `Queued` section when the agent is running
          </Step>

          <Step title="/enter-mode-next">
            **Cycle Enter mode** - Cycles `steer`, `queue`, and `interrupt` for Enter while Slate is working
          </Step>

          <Step title="/steer / /queue / /interrupt">
            **Set Enter mode directly** - Sets the active Enter mode without cycling
          </Step>

          <Step title="Ctrl+- / Super+Z">
            **Undo** - Undo the last input edit (on Windows, Ctrl+Z also works as undo)
          </Step>

          <Step title="Ctrl+L">
            **Focus input** - Move focus back to the input box from dialogs or other UI regions
          </Step>

          <Step title="Ctrl+Shift+S">
            **Show shell output** - Expand the shell output panel
          </Step>

          <Step title="Ctrl+Shift+B">
            **Hide shell output** - Collapse the shell output panel
          </Step>

          <Step title="Ctrl+C">
            **Clear input / Exit** - Clears the composer when it has text; exits the application when the composer is empty
          </Step>

          <Step title="Ctrl+D">
            **Exit** - Exits the application when the composer is empty
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="Shell Mode">
        <Steps>
          <Step title="!">
            **Enter shell mode** - Type `!` to enter bash command mode
          </Step>

          <Step title="↑/↓ arrows">
            **Navigate history** - Browse through previous commands
          </Step>

          <Step title="Tab">
            **Autocomplete** - Complete commands and file paths
          </Step>
        </Steps>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="All Shortcuts">
    <AccordionGroup>
      <Accordion title="Text Editing">
        <CodeGroup>
          ```text Movement theme={null}
          Ctrl+A          Move to beginning of line
          Ctrl+E          Move to end of line
          ←               Move left one character
          →               Move right one character
          Alt+B           Move back one word
          Alt+F           Move forward one word
          ↑               Move up one line
          ↓               Move down one line
          Shift+Arrows    Extend selection
          ```

          ```text Deletion theme={null}
          Ctrl+K          Delete to line end
          Ctrl+U          Delete to line start
          Ctrl+W          Delete word backward
          Alt+D           Delete word forward
          Backspace       Delete character before cursor
          Delete          Delete character under cursor
          ```

          ```text Special theme={null}
          Ctrl+L          Focus input box
          Ctrl+P          Open command list / command palette
          Ctrl+V          Paste
          Ctrl+-          Undo
          Ctrl+.          Redo
          Enter           Submit input; while Slate is working it follows the current Enter mode
          Shift+Return    Insert newline
          Tab             Queue current message while the agent is busy
          Escape          Cancel current operation
          Double Escape   Enter chat reverse search mode
          ```
        </CodeGroup>
      </Accordion>

      <Accordion title="Navigation & UI">
        <CodeGroup>
          ```text Dialog Navigation theme={null}
          ↑/↓             Navigate options in dialogs
          Enter           Select current option
          Escape          Cancel/close dialog
          Ctrl+C          Cancel/close dialog
          ```

          ```text Input Navigation theme={null}
          Tab             Queue current message while busy; otherwise autocomplete commands and file paths when suggestions are open
          Escape          Cancel/clear input or interrupt agent
          Double Escape   Enter chat reverse search mode
          ```

          ```text Leader Chords theme={null}
          Ctrl+X then N   New session
          Ctrl+X then L   Open session list
          Ctrl+X then T   Open themes
          Ctrl+X then P   Open providers
          Ctrl+X then K   Cycle main model
          Ctrl+X then M   Open model list
          Ctrl+X then Y   Copy message
          Ctrl+X then R   Redo message
          Ctrl+X then E   Open external editor
          Ctrl+X then H   Toggle tips
          Ctrl+X then Q   Edit queued messages in external editor
          ```

          ```text Single Keys theme={null}
          Ctrl+B          Toggle session sidebar
          Ctrl+R          Rename session
          Ctrl+T          Cycle model variant
          Shift+Tab       Toggle permission mode
          Ctrl+Shift+S    Show shell output
          Ctrl+Shift+B    Hide shell output
          ```

          ```text Message Scrolling theme={null}
          PageUp          Scroll messages up
          PageDown        Scroll messages down
          Home            Jump to first message
          End             Jump to last message
          ```

          ```text Session Management theme={null}
          /sessions       Switch between sessions
          /enter-mode-next Cycle Enter between steer, queue, and interrupt while Slate is working
          /steer          Set Enter to steer while Slate is working
          /queue          Set Enter to queue while Slate is working
          /interrupt      Set Enter to interrupt and send next while Slate is working
          Alt+Up          Pop the latest queued message back into the composer
          /exit           Exit application
          Ctrl+C          Graceful shutdown
          ```
        </CodeGroup>
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Slash Commands

<Info>
  All commands start with `/` and support autocomplete with Tab
</Info>

<Note>
  Slate includes built-in program commands `/goal` and `/deep-research`; this page only notes their availability, not a full per-command reference.
</Note>

### Core Commands

<Cards>
  <Card title="/help" icon="question">
    Show the manual page with common commands
  </Card>

  <Card title="/sessions" icon="folder">
    Switch to a different session or view available sessions
  </Card>

  <Card title="/models" icon="robot">
    Open the model picker to change the active model
  </Card>

  <Card title="/providers" icon="plug-circle-check">
    Manage provider connections for provider-backed models
  </Card>

  <Card title="/retry" icon="rotate">
    Retry the last message
  </Card>

  <Card title="/subagents" icon="sitemap">
    View subagent sessions for the current parent session, including details, status, trace, and changed-file summaries
  </Card>

  <Card title="/usage" icon="chart-bar">
    Show credit usage (remaining and used)
  </Card>

  <Card title="/billing" icon="credit-card">
    Switch between personal and organization billing contexts
  </Card>

  <Card title="/docs" icon="book">
    Open Slate documentation in your browser
  </Card>

  <Card title="/new" icon="plus">
    Start a new chat session
  </Card>

  <Card title="/mcps" icon="plug">
    Manage MCP servers and tools
  </Card>

  <Card title="/bug-report" icon="bug">
    Submit a bug report
  </Card>

  <Card title="/exit" icon="door-open">
    Exit the application
  </Card>

  <Card title="/enter-mode-next" icon="layer-group">
    Cycle what Enter does while Slate is working: steer, queue, or interrupt
  </Card>

  <Card title="/steer / /queue / /interrupt" icon="sliders">
    Set what Enter does while Slate is working without cycling
  </Card>

  <Card title="/queue-edit" icon="pen-to-square">
    Edit queued messages in external editor as --- separated markdown blocks
  </Card>
</Cards>

### Agent & Session Controls

<AccordionGroup>
  <Accordion title="/rename - Rename the current session">
    Rename the active session.
  </Accordion>

  <Accordion title="/timestamps - Toggle message timestamps">
    Show or hide message timestamps in the current session.
  </Accordion>

  <Accordion title="/permission-mode - Toggle session permission mode">
    Toggle between default permission prompts and session yolo mode.
  </Accordion>

  <Accordion title="/model-next - Cycle the main model">
    Switch to the next configured main model.
  </Accordion>

  <Accordion title="/effort-next - Cycle thinking level">
    Switch to the next available thinking/effort level for the current model.
  </Accordion>

  <Accordion title="/providers - Manage providers">
    Connect provider accounts, then use `/models`, `/model-next`, or `/effort-next` for provider-backed model workflows.
  </Accordion>

  <Accordion title="/editor - Open external editor">
    Open your configured external editor for composing a prompt.
  </Accordion>

  <Accordion title="/config - Open workspace config">
    Open workspace configuration and permissions.
  </Accordion>
</AccordionGroup>

### Workspace Management

<AccordionGroup>
  <Accordion title="/workspace - Manage workspace directories">
    Open the workspace manager to add, remove, and review workspace directories.
  </Accordion>

  <Accordion title="/add-dir - Quick workspace addition">
    Open workspace management with quick-add flow for directories.
  </Accordion>
</AccordionGroup>

### Theme Commands

<Cards>
  <Card title="/theme" icon="palette">
    Open the theme picker and switch themes
  </Card>

  <Card title="/man" icon="wand-magic-sparkles">
    Open the built-in manual page
  </Card>
</Cards>

### System Commands

<AccordionGroup>
  <Accordion title="Authentication & Account">
    <Steps>
      <Step title="/auth">
        Login to your Slate account
      </Step>

      <Step title="/logout">
        Logout from your current account
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Application Management">
    <Steps>
      <Step title="/version">
        Check the current version of Slate CLI
      </Step>

      <Step title="/docs">
        Open Slate documentation in your browser
      </Step>

      <Step title="/config">
        Open workspace configuration and permissions
      </Step>

      <Step title="/man">
        Open the built-in manual page
      </Step>

      <Step title="/usage">
        View credit usage and remaining balance
      </Step>

      <Step title="/billing">
        Switch billing context (personal/organization)
      </Step>

      <Step title="/mcps">
        Manage MCP servers and tools
      </Step>

      <Step title="/workspace">
        Open workspace manager
      </Step>

      <Step title="/add-dir">
        Quick-add a workspace directory
      </Step>

      <Step title="/enter-mode-next">
        Cycle what Enter does while Slate is working
      </Step>

      <Step title="/steer / /queue / /interrupt">
        Set the Enter mode directly
      </Step>

      <Step title="/exit">
        Exit the application gracefully
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Shell Mode

<Info>
  Type `!` at the beginning of a line to enter shell mode for direct command execution
</Info>

### Shell Mode Features

<Columns>
  <div>
    **Command Execution**

    * Run any shell command directly
    * Commands execute in the current workspace
    * Output is captured and displayed
    * Exit codes are reported
  </div>

  <div>
    **History & Completion**

    * Full command history with **↑/↓** arrows
    * **Tab** completion for commands and paths
    * Persistent history across sessions
  </div>
</Columns>

### Common Shell Operations

<CodeGroup>
  ```bash File Operations theme={null}
  !ls -la              # List files in detail
  !pwd                 # Show current directory
  !cd src              # Change directory
  !cat README.md       # Display file contents
  !mkdir new-folder    # Create directory
  ```

  ```bash Git Operations theme={null}
  !git status          # Check git status
  !git diff            # Show changes
  !git add .           # Stage changes
  !git commit -m "msg" # Commit changes
  !git push            # Push to remote
  ```

  ```bash Development theme={null}
  !npm install         # Install dependencies
  !npm test            # Run tests
  !npm run build       # Build project
  !python script.py    # Run Python script
  !cargo build         # Build Rust project
  ```
</CodeGroup>

## Special Key Combinations

<Tabs>
  <Tab title="Dialog Controls">
    | Key        | Action             |
    | ---------- | ------------------ |
    | **Enter**  | Confirm/Select     |
    | **Escape** | Cancel/Close       |
    | **Ctrl+C** | Force close/Cancel |
    | **↑/↓**    | Navigate options   |
    | **Tab**    | Move to next field |
  </Tab>

  <Tab title="Paste Mode">
    <Note>
      Slate automatically detects when you're pasting content and handles it appropriately
    </Note>

    * **Paste detection** is automatic
    * **Multi-line pastes** are preserved
    * **File paths** are automatically referenced when dragged and dropped
    * **Code blocks** maintain formatting
  </Tab>
</Tabs>

## Tips & Tricks

<AccordionGroup>
  <Accordion icon="book-bookmark" title="Efficient Navigation">
    * Press **Tab** after typing `/` to see commands with autocomplete
    * Use the **up arrow** in shell mode to quickly find previous commands
    * Drag and drop files directly into the prompt for automatic path references
  </Accordion>

  <Accordion icon="head-side-gear" title="Productivity Shortcuts">
    * **Ctrl+X then E** opens your system's default editor for composing complex prompts
    * **Ctrl+X then M** opens the model picker to switch models without leaving the chat
    * Use `/workspace` to manage workspace directories, or `/add-dir` to start the quick-add flow
    * Chain shell commands with `!command1 && command2`
  </Accordion>

  <Accordion icon="code" title="Advanced Usage">
    * Use `/subagents` to inspect subagent sessions while they run or after they complete
    * Theme switching persists across sessions
  </Accordion>
</AccordionGroup>

## Exit Codes

<Note>
  Understanding exit codes helps diagnose issues when commands fail
</Note>

| Code    | Description                      |
| ------- | -------------------------------- |
| **0**   | Success                          |
| **1**   | General error or invalid usage   |
| **2**   | Misuse of shell command          |
| **126** | Command found but not executable |
| **127** | Command not found                |
| **128** | Invalid exit argument            |
| **130** | User interrupted (**Ctrl+C**)    |


# The Basics
Source: https://docs.randomlabs.ai/en/using-slate/index

A simple guide to working with Slate

Understanding how Slate works will help you use it more effectively.

To get the most out of Slate, you'll need to set up your environment and know how to prompt it well:

-> [Workspace Setup](/en/using-slate/workspace_setup)

-> [Prompting Guide](/en/using-slate/prompting_guide)

## Frequently Used Features

### Switching Sessions

Use `/sessions` to switch between existing sessions:

<Card title="Session Selection Process">
  1. Type `/sessions` and press **Enter**
  2. Use **↑/↓** arrows to navigate available sessions
</Card>

### Cancellation

<Card title="Esc">
  **Cancels** the current *agent* step, current input or closes dialogs.
</Card>

<Card title="Ctrl+C">
  **Hard interrupt** - Stops the cli.
</Card>

### Message Queue

When Slate is busy:

* Press **Enter** to perform the current **Enter mode** action.
* Press **Tab** to **queue** the current message so it runs after the current turn finishes.

Use `/enter-mode-next` to cycle what **Enter** does while Slate is working:

* **steer**: Enter redirects the current run immediately
* **queue**: Enter queues the message for later
* **interrupt**: Enter aborts the current run and sends your message next

You can also set the mode directly with `/steer`, `/queue`, or `/interrupt`.

**Tab** always queues the current message (regardless of the Enter mode) so it runs after the agent finishes.

**Steering** delivers your message while the agent is still working -- after the current response and any tool calls complete, your message is sent in before the agent continues. Use this to course-correct the agent mid-task.

**Queueing** waits until the agent finishes everything it is doing, then delivers your message as the start of a new run. Use this to stack up follow-up tasks while the agent works.

**Interrupt** aborts the current run entirely and sends your new message next, with any previously pending messages restored behind it.

<Card title="Follow-up messages">
  Queued messages and steering messages appear **above the input box** under separate `Steering` and `Queued` sections. Steering messages deliver while the agent is still running; queued messages drain automatically once the session goes idle.
</Card>

<CardGroup>
  <Card title="⌥ + ↑  (Alt+Up)" icon="arrow-up">
    Pops the **latest queued message** back into the composer so you can edit it before it's sent.
  </Card>

  <Card title="Ctrl+X then Q" icon="pen-to-square">
    Opens all queued messages as `---`-separated markdown blocks in your external editor so you can review and reorder them. Use `/queue-edit` for the same behavior.
  </Card>

  <Card title="Esc on empty input" icon="circle-xmark">
    While the agent is busy, pressing **Esc** on an empty input **aborts the session** and restores all queued messages into the composer.
  </Card>
</CardGroup>

You can also pre-load a queue from the command line with `--queue` (`-q`), passing a markdown file whose messages are separated by a line containing `---`:

```bash theme={null}
slate --queue plan.md
```

<Info>
  The queue persists across navigation — queued messages are stored in draft state and won't be lost if you switch sessions and come back.
</Info>

### Multi-line Messages

Use **Ctrl+L** to focus the input box from elsewhere in the UI.

Use **Ctrl+Enter** or **Option/Alt+Enter** to insert newlines:

```text theme={null}
> Please help me with:
  1. Parsing this JSON file    [Ctrl+Enter]
  2. Validating the schema     [Ctrl+Enter]
  3. Handling errors properly   [Enter to send / busy action]
```

Use **Ctrl+A** or **Ctrl+E** to jump to the beginning or end of the input context.

### Shell Command Input

Execute shell commands directly with `!`:

<CodeGroup>
  ```bash Quick Commands theme={null}
  !ls              # List files
  !pwd             # Show directory
  !git status      # Check git status
  ```

  ```bash Development theme={null}
  !npm test        # Run tests
  !npm run build   # Build project
  !python app.py   # Run Python script
  ```
</CodeGroup>

This will send the command output to Slate directly.

### Context Management

<AccordionGroup>
  <Accordion title="Adding Context">
    Use `@filename` references:

    ```text theme={null}
    > Please review @src/main.ts and suggest improvements
    ```
  </Accordion>

  <Accordion title="Workspace Directories">
    Use `/workspace` to open the workspace manager, where you can review and remove workspace directories. Use `/add-dir` when you want the quick-add flow.

    ```bash theme={null}
    /workspace
    /add-dir
    ```
  </Accordion>

  <Accordion title="Reviewing Context">
    Open the workspace manager before switching tasks to review directories and remove anything you no longer need.

    ```bash theme={null}
    /workspace
    ```
  </Accordion>
</AccordionGroup>

### Long Prompts

Press **Ctrl+X then E** to open your external editor for composing complex prompts:

<Steps>
  <Step title="Press Ctrl+X then E">
    Opens your system's default editor
  </Step>

  <Step title="Write your prompt">
    Compose your detailed message in the editor
  </Step>

  <Step title="Save and close">
    The content automatically returns to Slate
  </Step>
</Steps>

<Danger>
  This will not work if your permissions do not allow access to `tmp` or `var` as this command uses a temp file for your default text editor
</Danger>

<CardGroup>
  <Card title="Hotkey reference" icon="code" href="/en/using-slate/hotkey_reference">
    Explore Slate's complete set of commands.
  </Card>

  <Card title="Orchestration & Tracing" icon="diagram-project" href="/en/using-slate/orchestration">
    Learn how Slate shows parent runs, subagents, background agents, programs, and trace activity.
  </Card>
</CardGroup>


# Orchestration & Tracing
Source: https://docs.randomlabs.ai/en/using-slate/orchestration

Review parent runs, subagents, background agents, programs, and trace activity in Slate

Understanding Slate's orchestration UI will help you follow longer work without losing track of what is happening.

Slate can split work across agents, keep background work running, and show program activity in the TUI. This page covers the user-facing places where that work appears.

## Orchestration in the timeline

When Slate orchestrates a task, it can hand pieces to several agents at once and run them in parallel. Those agents show up as a grid of inline subagent cards, one per agent.

Double-click any card to jump into that agent's session and follow the full conversation.

<AccordionGroup>
  <Accordion title="Subagent cards">
    Subagent cards show the practical state of each child agent:

    * **Status and progress** while the child agent runs
    * **Interruption** if a run is stopped before finishing
    * **Completion** when the child agent finishes
    * **Changed-file summaries** so you can quickly see what the child agent touched
  </Accordion>
</AccordionGroup>

## Subagent sessions and overlay

Subagents have their own child sessions. From the current parent session, open the subagent overlay to review those child sessions without losing the parent context.

In the overlay, you can move through the child sessions for the current parent session, inspect their status and activity, and open a child session when you need more detail.

<CardGroup>
  <Card title="Review child sessions" icon="sitemap">
    Browse the subagent sessions that belong to the current parent session.
  </Card>

  <Card title="Open details" icon="up-right-from-square">
    Open a child session when you need to inspect its work more closely.
  </Card>

  <Card title="Return to parent" icon="arrow-left">
    Use parent-session navigation to get back to the original session afterward.
  </Card>
</CardGroup>

## Background agents

Some work can continue in the background. When background agents are running, Slate shows a running indicator so you know there is active work outside the current foreground turn.

Background agents let Slate hand off work without blocking the main conversation. While one or more agents run in the background, you can keep talking with Slate: plan next steps, queue up additional tasks, or spin up more agents to parallelize work across several tasks at once.

You do not need to track when background agents finish. When one completes, Slate receives a notification, `◉ Background agent notification received`, and surfaces the results in conversation so you can see what happened without leaving your current chat window.

Use the background-agents sidebar to manage that work:

<CardGroup>
  <Card title="Open" icon="up-right-from-square">
    Inspect a running background agent.
  </Card>

  <Card title="Stop" icon="stop">
    Interrupt background work you no longer want to continue.
  </Card>

  <Card title="Open session" icon="folder-open">
    Jump to the session for that background agent.
  </Card>
</CardGroup>

## Built-in programs in the UI

`goal` and `deep-research` are built-in programs. They are user-visible workflows, not something you need to author before using Slate.

Open the Programs sidebar to browse program runs. Program run cards summarize each run, and the program views help you inspect the work at different levels.

<CardGroup>
  <Card title="Run cards" icon="list-check">
    Review the current state and summary for a program run.
  </Card>

  <Card title="Graph view" icon="diagram-project">
    See the workflow shape and dependencies.
  </Card>

  <Card title="Details view" icon="circle-info">
    Inspect more information about a selected run or step.
  </Card>
</CardGroup>

## Trace activity cards

Trace activity cards show a high-level view of what agents did during a run. Read them to follow the major steps and connect visible results back to the work Slate performed.


# Prompting Guide
Source: https://docs.randomlabs.ai/en/using-slate/prompting_guide

Getting the most out of Slate

When prompting Slate, you simply have to type into the input box and press **Enter**.
The input box supports the following:

* `@ mentions` (@path/to/file)
* `Copy+paste`
* `Esc` to clear
* `Ctrl-a` to jump to the beginning
* `Ctrl-e` to jump to the end
* `option/alt+enter` for new lines

What matters more than how you input content into the box is what you input into the box.

Slate performs best when treated more autonomously than other agents.
There are a few principles that will help when prompting:

### Let Slate manage its context

Often times, other coding agents require lots of agent rules and lots of instructions.
Slate functions best when managing the exploration process on its own, and taking higher level direction from the user.
This is because Slate is designed to work for longer periods of time and so can manage its own context better.

**What should you provide Slate with:**

The high level goal of the current session.

Guidance on the order of things to do:

* `"Hey slate, research this section of my codebase @directory and then we are going to write a plan"`
* `"I want you to explore X, update Y to do Z, and then update A following the same pattern"`

Guidance on the general shape of the solution:

* If there are specific files it should stick to
* If there are specific patterns a good solution MUST have
* What the solution should look like ex: "should we refactor or should we just add to the codebase"
* Any specific gotchas that Slate will run into during execution

**Avoid prompts like the following:**
`"Make no mistakes"`
`"You're a really smart engineer"`
`"ALWAYS MAKE SURE TO DO X"`

These prompts will *generally* lead to worse performance out of Slate overall.

### Clarity

The goal when prompting Slate should be to be as clear and descriptive as possible.
Slate is a fairly unopinionated agent and works best when describing the exact process you want it to follow and describing what you want clearly.

Rather than saying:
“Make a new api middleware to handle X”

Say:
“I need a new middleware for X and I need it on the following endpoints...”

### Use agent rules only when necessary

Your agent rules file should ideally be sparse and contain the following information:

* High level overview of the codebase
* Constraints on developing in the codebase
* Useful commands or steps to perform operations in the codebase

### Handling long tasks

One of the key reasons to use Slate is for its ability to keep working through long sessions.
The best way to do this is as follows:

1. Ask Slate to research the problem first and make a plan

```
Hey slate, please research my codebase for <X>,
and then make a plan for implementing <Y>.
Make sure you look at @path/to/important/file
```

When planning with Slate, it is important to make sure that Slate clearly understands. Here, we want to make sure \<Y> has a clear description.
Slate will come back to you with a plan for how to tackle the current task.

2. Ask Slate to iterate on the provided plan

Once Slate has returned with a plan, Slate can ask for your opinions on the plan. Your response should be as clear and complete as possible:

```
No don't do A, make sure you do it the same way B is done.
```

After this, Slate can continue to iterate. Once you're done, approve the plan.

3. Executing the plan

Slate has a `todo` tool for managing its tasks. Once the plan is confirmed, Slate often creates a task list for it to follow.
If you are uncertain about the todos, make sure to ask Slate your questions or tell Slate what your concerns are.
This will help Slate update the plan and the todos in real time to make sure it works through the task with you.

Slate will then work autonomously until a relevant stopping point is reached, likely the conclusion of the task.

<Warning>
  For extra long tasks, sometimes Slate may need a reminder about the goal after working on subsections for a long time.
</Warning>

### Debugging systems with Slate and background jobs

A second big benefit of using Slate is the ability for Slate to work well with background jobs.
The best way to do this is through the following:

1. Understand which pieces of the system need debugging
2. Set up the env so that Slate can work well in it (see [Workspace setup](/en/using-slate/workspace_setup))
3. Prompt Slate to work through the process

For best results, the following information should be present:

* Which systems need debugging
* Relevant stack traces
* Context on where and how the bug occurs
* Any relevant library information
* Any opinions on the solution


# Skills
Source: https://docs.randomlabs.ai/en/using-slate/skills

Give Slate domain-specific knowledge with reusable markdown instruction packages

Skills are markdown instruction packages that give the agent domain-specific knowledge and behavior. When a skill is active, its instructions are injected into the agent's context for the duration of the session.

## File structure

A skill is a directory named after the skill, containing a `SKILL.md` file (uppercase):

```
.slate/skills/
  frontend-design/
    SKILL.md
  bun-expert/
    SKILL.md
```

The `SKILL.md` file uses YAML frontmatter with two required fields — `name` and `description` — followed by the instruction content in markdown:

```md theme={null}
---
name: "frontend-design"
description: "Create distinctive, production-grade frontend interfaces."
---

# Frontend Design

Use Tailwind, avoid generic AI aesthetics...
```

## Where skills are discovered

Slate searches for skills in the following locations, in priority order (highest first):

| Priority | Path                                   | Scope                     |
| -------- | -------------------------------------- | ------------------------- |
| 1        | `.slate/skills/<name>/SKILL.md`        | Project                   |
| 2        | `~/.slate/skills/<name>/SKILL.md`      | Global                    |
| 3        | `.opencode/skills/`, `.agents/skills/` | Compatibility             |
| 4        | `.claude/skills/`                      | Claude Code compatibility |
| 5        | Custom paths via `slate.json`          | Configurable              |

<Note>
  Claude Code compatibility scanning can be disabled by setting the `SLATE_DISABLE_CLAUDE_CODE_SKILLS` environment variable.
</Note>

<Tip>
  **Global vs project-level skills:** Place skills in `~/.slate/skills/` to make them available across all your projects — useful for things like your preferred coding style or a framework you use everywhere. Place skills in `.slate/skills/` (inside your project) for project-specific knowledge like architecture conventions or domain rules. Project-level skills take priority over global ones.
</Tip>

## Custom skill paths

You can add additional skill search paths in your `slate.json`:

```json theme={null}
{
  "skills": {
    "paths": ["./custom-skills", "~/my-skills"]
  }
}
```

See [Configuration](/en/using-slate/configuration) for more on `slate.json`.

## Using skills in the TUI

Open the Skills dialog from the TUI by typing `/skills` in the composer, or browse skills inline with `@` autocomplete.

The dialog has two panels:

* **Left panel** — list of all discovered skills
* **Right panel** — detail pane with syntax-highlighted skill content

**Navigation:**

| Key                    | Action                      |
| ---------------------- | --------------------------- |
| `↑` / `↓` or `j` / `k` | Move through the skill list |
| `Tab` or `←` / `→`     | Switch between panels       |
| `Esc`                  | Close the dialog            |

## How the agent uses skills

The main agent can search, view, activate, and deactivate skills autonomously during a session. When the main agent determines a skill is relevant to the current task, it activates it — and will deactivate it when it's no longer needed.

The main agent also automatically routes relevant skills from the available set into each subagent based on the context of its task.

Active skills are injected into the agent's context and remain active until the agent decides to deactivate them.


# Troubleshooting
Source: https://docs.randomlabs.ai/en/using-slate/troubleshooting

Troubleshooting and reporting issues

This project is early, but quite a few of the edge cases are solved.
The best bet for solving issues while using Slate is by:

* joining our [Discord](https://discord.gg/RBDqGJqkc6) and posting in **#bug-report** or **#support**
* submitting a `/bug-report` in the TUI
* emailing us at `team@randomlabs.ai`
* reaching out to us on X: `@0xrandomlabs`

## Reporting application bugs

When you run into an application related bug, you can submit a report with `/bug-report`, or feel free to reach out to us via email. Someone on the team will respond to you shortly.

Make sure to include the following information:

* Operating system + Version
* Platform (arm mac, intel mac, etc)
* Slate version (run `/version` in the CLI)
* Screenshots of the bug

### Using /bug-report

The `/bug-report` command lets you submit a bug report directly from the TUI. To use it:

1. Type `/bug-report` in the Slate TUI and press **Enter**.
2. You will be prompted to describe the issue — include what you were doing, what you expected to happen, and what actually happened.
3. Slate automatically attaches relevant diagnostic information (OS, version, session context) to your report.
4. The report is sent directly to the Random Labs team, who will follow up via email.

**Tips for a useful bug report:**

* Be as specific as possible about the steps that triggered the bug.
* If the TUI crashed or produced unexpected output, describe what you saw on screen.
* If you have a screenshot or screen recording, attach it when following up by email at `team@randomlabs.ai`.

## Reporting issues where the agent is not working

Slate runs on the latest language models. This means sometimes, it won't be able to do a task.
To report these issues, reach out directly at [team@randomlabs.ai](mailto:team@randomlabs.ai) with a description of the task and what went wrong.


# Workspace Setup
Source: https://docs.randomlabs.ai/en/using-slate/workspace_setup

Setting up your workspace for Slate

This section details setting up your workspace and environment so that Slate can function best.
Slate can just drop into your existing coding agent workflow, but this page contains guidance on how to get the most out of it.

## Environment setup

One of the biggest benefits of using Slate is its ability to use shell tools the same way you do.
In order to do this, Slate can access long running shells etc.
The best way to get Slate to interact with your environment is through the following:

## Agent rules

Slate by default respects agent rules in the following order:

**Project-level** (searched upward from your project directory to the git root — only the first matching filename is loaded):

1. `AGENTS.md`
2. `CLAUDE.md`
3. `CONTEXT.md` (deprecated)

**Global fallback** (checked independently — first existing one wins):

1. `~/.config/slate/AGENTS.md`
2. `~/.claude/CLAUDE.md`

**Additional instructions** can be added via the `instructions` field in `slate.json`.
A good rules file has the following information in it:

* A high level overview of the purpose of the codebase
* An overview of the current structure of the codebase (not the file system, but rather the architecture).
* An overview of any relevant commands, libraries, or gotchas.
* Expected patterns to follow for different sections of the codebase

Slate does not load rules from nested directories. It searches upward from your project directory to the git root and stops at the first matching filename (`AGENTS.md`, `CLAUDE.md`, or `CONTEXT.md`). Global fallbacks are checked independently. For more information visit [https://www.agents.md](https://www.agents.md)

## Build/test processes

Slate does much better when there is a clear way to verify the correctness of the work being done.
This means writing unit tests and integ tests.

**Slate is one of the few agents capable of performing integration tests manually.**
What this means is that Slate can do integration testing on your system manually, and can also verify the integ tests themselves.

<Tip>
  Ask Slate to help set up your testing environment! Make sure to have test cases in mind.
</Tip>

<Tip>
  Ask Slate to create temporary testing scripts when needed but try to keep the testing process clear and consistent.
</Tip>

## Environment variables

For many projects, you'll need a variety of env variables.
Slate does not have awareness of your env files by default.
Slate will need access to environment variables to do certain tasks.
The best way to handle this is to define a `.env.slate` file (or any other name you like).
You can then take this and add it to your `AGENTS.md` file so that Slate knows that this is the env file it should be using.