Beast user manual.

01 — Setup

Getting started

Beast ships as a single self-contained Linux binary with no runtime dependencies to install. Download it, put it on your PATH, and run it from the root of your project.

Requirements

Two tools must be available before running Beast: bwrap (bubblewrap), used to sandbox shell commands in a read-only host with a writable workspace, and rg (ripgrep), used for fast project search.

bwrap --version
rg --version

Beast works on Linux x86_64 (glibc ≥ 2.39) and on Windows through the Windows Subsystem for Linux (WSL).

Install the binary

mkdir -p ~/.local/bin
curl -fsSL https://beast-agent.com/beast -o ~/.local/bin/beast
chmod +x ~/.local/bin/beast
export PATH="$HOME/.local/bin:$PATH"

To install system-wide instead, download to /usr/local/bin with sudo. The same command run later replaces the existing binary in place, so updating is a single step.

Run it

cd /path/to/your/project
beast

02 — Setup

Configuration

On first run Beast creates ~/.beast/settings.json with a placeholder template. Configure MODEL and API_KEY, and set BASE_URL when using a custom OpenAI-compatible endpoint.

{
  "API_KEY": "",
  "MODEL": "openai:gpt-4o",
  "BASE_URL": "",
  "REASONING_EFFORT": "high"
}

You can also configure credentials and select a model from inside the application: use /connect to add and activate a provider API key, and /models to pick a model from the interactive catalog with configurable reasoning effort.

03 — Everyday use

Usage basics

Plan and Build modes

Beast runs with two intentional modes, and the available tool surface follows the active mode. Switch between them at any time.

Sessions and context

• Sessions are project-scoped and persisted locally.
• Start a new session with /new; resume a previous one with /sessions.
• Compact the conversation with /compact; compaction also happens automatically at the context limit.
• Live token usage is tracked against the context window, with streaming responses.
• Ctrl+C cancels an in-flight request, or quits when idle.

Project instructions

Beast automatically injects your repo's AGENTS.md into the system prompt. Run /init to generate one — it detects the project's language, build system, and commands and writes a polished agent guide.

04 — Reference

Built-in commands

Type / in the chat input to open the command palette.

05 — Extend the input

Custom commands

Custom commands turn a reusable Markdown prompt into a slash command such as /review or /test. Codify repeatable workflows — code review, test runs, commit-message drafting — and invoke them with a single keystroke. The injected prompt goes through the normal agent loop: tools, active Plan/Build mode, and command approval all still apply.

Where commands live

Local commands override global commands with the same name. Create the commands/ directory if it does not exist; files are picked up the next time you start Beast.

File format

A command file is Markdown with an optional --- frontmatter block followed by the prompt body. The description is shown in the palette.

---
description: Review the current code for bugs and maintainability issues
---

Review the current project.

Focus on:
- correctness
- security
- performance
- maintainability

Do not modify files unless explicitly requested.

If the file has no frontmatter, the whole file is treated as the prompt body. Files with an empty prompt body are ignored.

Naming and precedence

The command name is the file path relative to commands/, without the .md suffix. Nested directories group related commands under a prefix.

.beast/commands/review.md           →  /review
.beast/commands/frontend/review.md  →  /frontend/review
.beast/commands/api/test.md         →  /api/test

Built-in commands are reserved and cannot be shadowed by custom files: exit, compact, sessions, new, connect, models, and init. A custom compact.md is ignored.

Running a command

• Type / in the chat input to open the palette and filter by name.
• Select from the palette (Enter or click) — runs the command with no arguments.
• Type the full command — /review some-args runs it with some-args.
• The transcript shows the raw text you typed; the model receives the expanded prompt body.

Arguments

When arguments are provided but the body contains no placeholder, the raw argument text is appended to the prompt as a final paragraph.

---
description: Draft a commit message for the given changes
---

Write a concise conventional commit message for the following changes.

Files: $ARGUMENTS

Suggest one commit message, and explain the reasoning briefly.

Invoked as /commit src/agent/ui/app.py, $ARGUMENTS becomes src/agent/ui/app.py and $1 becomes the first whitespace-separated token.

Notes

• Commands are loaded once at startup — restart Beast after adding, editing, or removing command files.
• Commands are loaded from ~/.beast/commands/ and .beast/commands/; create the directory if it does not exist yet.
• Keep prompts focused and short so they are useful in any mode.

06 — Reusable workflows

Skills

Skills are reusable instruction + workflow packages that the agent discovers and loads on demand when a task matches them. Write a skill once and the agent follows its workflow whenever the task calls for it — no slash command, no manual trigger.

How skills work

Beast uses progressive disclosure:

1. The system prompt includes a compact [Available skills] index listing each skill as name: description.
2. When the current task matches a skill's description, the agent calls the read-only skill_tool with the skill's name.
3. The full SKILL.md body is loaded into the conversation and the agent follows the workflow.

Only the one-line index is always in context; full bodies load only when needed.

Directory layout

Global skills (all projects):
~/.beast/skills/
  git-commit/
    SKILL.md
  code-review/
    SKILL.md

Local skills (this project only):
<project>/.beast/skills/
  git-commit/
    SKILL.md
  debugging/
    SKILL.md

Each skill is a directory containing a single SKILL.md. Directories without a SKILL.md are ignored, and unreadable or malformed files are skipped silently. A local skill overrides a global one of the same name.

SKILL.md format

A skill file has an optional YAML-style frontmatter block (with name and description) followed by the workflow body.

---
name: git-commit
description: Create a conventional commit for the current changes and push it to GitHub.
---

# Git Commit

When this skill is invoked:

1. Inspect the current git status.
2. Review the changed files.
3. Create a conventional commit message.
4. Ask for approval before committing if required.
5. Push the commit to the configured remote.

## Guidelines

- Never commit secrets.
- Never use `git add -A` blindly.
- Review the diff before committing.
- Use conventional commit format.

• The description decides when the skill matches — make it specific about when the skill applies.
• When frontmatter name is present it is the skill's name; otherwise the directory name is used.
• A skill with an empty body is not registered; bodies are truncated at 20,000 characters.

Writing good skills

• Make the description matchable. A vague description may never be used.
• Give concrete, ordered steps. Number the workflow so the agent can follow it end to end.
• Add a Guidelines section stating the constraints that should hold whenever the skill is used.
• Keep the body tight. Long workflows get truncated; the most important rules should be near the top.

Availability

The skill tool is read-only and requires no approval. It is available in both Plan and Build modes and to subagents spawned via task, and the skill index appears in the system prompt for every run.

Troubleshooting

07 — Extend the tools

MCP servers

Beast can connect to Model Context Protocol (MCP) servers and expose their tools to the model alongside the built-in tools — web search, database access, browser automation, issue trackers, and anything else a server provides. Any conforming server works: hosted HTTP servers and local stdio servers launched with npx, uvx, or a plain executable.

• Tools appear like native tools. The model calls them exactly like the built-in tools, and you can ask for one by name.
• Available in both modes — Plan and Build — and to task subagents.
• Failures never stop the turn. A failed tool call returns an error string, so the agent can try another approach.
• Names never clash. Built-in tools win name collisions; between servers, a local config beats a global one, then servers are compared alphabetically by name.
• Zero extra dependencies. The client uses the standard library (JSON-RPC 2.0 over stdio and Streamable HTTP).

Quick start

Exa web search is configured for you on first run in ~/.beast/mcp.json:

{
  "servers": {
    "exa": {
      "enabled": true,
      "transport": "http",
      "url": "https://mcp.exa.ai/mcp",
      "timeout": 30
    }
  }
}

Start Beast and ask naturally: "Search the web for the latest changes to the MCP specification and summarize them." The agent will call web_search_exa (and web_fetch_exa to read a page) and answer from live results. You can also name a tool explicitly: "Use web_fetch_exa to read this page."

Managing servers with /mcp

Type /mcp to open the server manager. It connects to every enabled server and shows a row per server with its scope, transport, and tool count. A green dot means connected, yellow means enabled but failed to connect (the error is shown beneath it), and dim means disabled.

Adding and editing a server

Press a (or Enter on an existing row) to open the editor. The name is the key under servers in mcp.json and is fixed once the server exists. Choose the transport (stdio or http), the scope (global or local), and whether it is enabled.

• stdio — command to launch (npx, uvx, a binary), space-separated args, a JSON object of extra environment variables, and an optional working directory.
• http — the Streamable HTTP endpoint URL and a JSON object of extra request headers (used for auth).

Press Save. Beast writes the file atomically and reconnects.

Configuration files

• A server with the same name in the local file fully replaces the global one (not merged field by field).
• The project root is the directory you launched beast from.
• The global file is created and seeded with the Exa template on first run. Both files are written atomically and are 0600.
• A server entry is only loaded when it has what its transport needs: command for stdio, url for http.
• If a file is not valid JSON it is treated as empty; Beast never fails to start because of a bad config.

Schema

{
  "servers": {
    "<name>": {
      "enabled": true,
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "env": { "KEY": "value" },
      "cwd": "/optional/working/dir",
      "timeout": 30
    },
    "<name-http>": {
      "enabled": true,
      "transport": "http",
      "url": "https://mcp.exa.ai/mcp",
      "headers": { "x-api-key": "..." },
      "timeout": 30
    }
  }
}

Transports

stdio — local servers

Beast launches the process and keeps it alive for the session, exchanging newline-delimited JSON-RPC over its standard input/output. The command must be on PATH (or an absolute path) — npx requires Node, uvx requires uv. If the process dies, Beast reconnects it on the next call. The first npx run may download the package and be slow; raise timeout if the handshake times out.

http — hosted servers

Beast sends JSON-RPC requests to the URL over Streamable HTTP, reusing the server's session id and accepting both plain JSON and SSE responses. Authentication is supplied through headers.

Examples

Filesystem (local, official reference server) — grants the agent access to a directory:

{
  "servers": {
    "filesystem": {
      "enabled": true,
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"]
    }
  }
}

Git (local, via uv):

{
  "servers": {
    "git": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "."]
    }
  }
}

Memory (local, persistent knowledge graph):

{
  "servers": {
    "memory": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

More servers are listed in the MCP Registry and the official servers repository.

Authentication and secrets

• HTTP servers authenticate with headers; stdio servers receive secrets through env.
• Values are stored in plaintext in mcp.json (created with 0600). Treat it like settings.json and never commit it.
• Values are used literally — there is no shell or $VAR expansion.
• Prefer the global file for anything with a secret; a local .beast/mcp.json is easy to commit by accident.

Using MCP tools effectively

• Ask naturally, or name the tool. The model sees each tool's description and can pick the right one.
• Keep the surface small. Every tool definition counts toward the context window — disable servers you are not using.
• Pick the right scope. Repo-specific servers belong in the local file; personal servers in the global file.
• Reconnect after external edits. Open /mcp and press r if you edited mcp.json outside the app.
• Combine with built-ins. MCP tools work alongside task subagents and the file tools, so you can research and then edit in the same turn.

Troubleshooting

08 — Platforms

Compatibility

Beast ships as a single self-contained binary — no Python installation required — and its MCP client is implemented with the standard library, so nothing extra to install beyond bwrap and rg.