cast

A role-based terminal agent harness. 20 built-in personas — senior dev, QA, DBA, security reviewer, PM, tech writer, and more — same tools, different judgment. Runs on any OpenAI-compatible model, including the one on your own hardware.

Why cast?

A cast, not a coder. 20 built-in personas swap the agent's role without changing its tools. Senior dev for root-cause fixes, QA for edge cases, DBA for schema design, PM for specs, appsec for threat modeling — same tools, different judgment. Add your own with a single markdown file.

Real tools, real work. It reads files, writes code, runs shell commands, searches your codebase — and does it all in parallel. Delegates sub-tasks to isolated sub-agents. Rules, skills, and MCP servers extend capabilities without touching the codebase.

Runs where your code runs. vLLM, Ollama, your own inference server, or any OpenAI-compatible API. No account, no telemetry, no cloud dependency.

Ink TUI. A proper terminal interface with multiline paste, image attachments, smooth animations.
Web UI. cast web launches a browser-based control room — background agents, token-by-token streaming, diff viewer, all slash commands. Same sessions as the TUI.

Why personas, not just prompts

Point a generic coding agent and a role-specific one at the same file, and they don't just answer differently — they look for different things. Give an appsec persona a schema and it flags the injection surface; give a DBA persona the same schema and it flags missing indexes and normalization. A QA persona treats an untested edge case as unfinished work; a PM persona treats an unwritten spec as unfinished work — same repo, same tools, different definition of "done."

This isn't a skin. Research on role/persona prompting backs the shift on both sides of that gap:

• Assigning an LLM an expert role measurably changes the shape of its output — deeper domain framing at the cost of some plain-language clarity, a real trade-off rather than a free upgrade (Xiao et al., 2026).
• The effect isn't free-floating flavor text: matching the persona to the task helps, mismatching it hurts, and a mismatched persona measurably breaks more answers than a matched one fixes (Kim et al., 2024).
• For tool-using agents specifically, explicit role/behavior rules — not just a persona label — are what fixes "under-acting" (skipping a tool the role should obviously use) and "over-speaking" (chatting instead of calling) (Ruangtanusak et al., 2025).
• The effect isn't universal — persona framing helps most on open-ended, advisory, judgment-heavy tasks, and least on narrow factual lookups, so a persona only pays for itself when it actually matches the task.

cast leans into that instead of working around it: swap /persona and the same tools, the same repo, and the same model produce a different investigation — different priorities, different tool sequencing, different conclusions, different follow-up questions. A security review that reasons like a senior dev misses different things than one that reasons like an appsec engineer, even reading identical code.

Full writeup, with direct quotes and sources: docs/persona-research.md.

Install

macOS / Linux:

curl -fsSL https://aa-blinov.github.io/cast/install | bash

Windows (PowerShell):

irm https://aa-blinov.github.io/cast/install.ps1 | iex

Requires Node.js 22+. Self-contained bundle — no npm packages needed at runtime.

Pin a version: CAST_VERSION=0.1.0 curl ... | bash
Upgrade later: cast upgrade

Quick Start

# Launch — prompts for provider URL + API key on first run, remembers after
cast

# One-shot prompt
cast "explain what this project does"

# Specific model + reasoning
cast -m qwen/qwen3-235b-a22b -r high "refactor this function"

# Resume last session
cast -c

What it can do

Built-in tools

bash read write edit glob grep ls task ssh web_search web_fetch — the agent has full filesystem, shell, SSH remote, and web access. Multiple tools run in parallel. The task tool delegates work to isolated sub-agents (with their own persona and context) and returns only the final result. Image files (jpg/png/gif/webp) are sent directly to vision-capable models. Web tools are off by default — toggle with /web (persists to settings).

Rules

Project-specific instructions in .cast/rules/*.md — Cursor-compatible format with four modes: always (injected every turn), auto (attached when matching files enter context), lazy (model reads on demand), and manual (via @mention or /rule:name). Nested .cast/rules/ directories in subdirectories scope rules to that subtree.

Project Context Files

Drop an AGENTS.md or CLAUDE.md in your repo root — cast picks it up automatically and injects it into the system prompt. Walks every ancestor directory up to /, so org-wide guidelines in a parent folder apply to all projects beneath it. The file in cwd itself is trust-gated; files above load without prompting. No special syntax, no config — just the file.

Skills

Self-contained instruction packages loaded on demand from ~/.cast/skills/ / .cast/skills/, plus skills.sh universal paths (.agents/skills/, ~/.config/agents/skills/). Follows the Agent Skills spec. The agent sees what's available and loads the right one automatically.

MCP Servers

Connect any Model Context Protocol server — local (stdio) or remote (streamable HTTP). Uses the common mcpServers JSON config shape. Their tools appear alongside the built-in ones.

Personas

Swap the agent's role — and optionally which built-in tools that role may use:

Add your own in ~/.cast/personas/ (global) or .cast/personas/ (project).

Plan mode

Think before you build: /plan switches the agent to read-only exploration — it studies the codebase (parallel sub-agents, read-only shell) and writes an execution-spec plan with a - [ ] checklist to ~/.cast/plans/. When the plan is ready you get an approval dialog: implement now, implement in a fresh context, approve for later, or keep refining. In build mode the approved plan rides in the system prompt (surviving compaction and restarts) and the agent checks off steps as it lands them. The agent can also propose planning itself (plan_enter) when a task looks complex. Each phase can run its own model — see /plan-model.

Context compaction

When the conversation gets too long, the agent automatically summarizes older messages — keeps the context window useful without losing important details.

Reasoning levels

Models that support it (OpenRouter metadata) get reasoning controls: off / low / medium / high / max. Set via --reasoning or change mid-session with /reasoning.

Sessions

Every conversation auto-saves. Resume with --continue, pick from a list with --resume, or switch mid-session with /sessions.

Web UI

cast web launches a browser-based control room — same sessions as the TUI, with a diff viewer, background agents, and token-by-token streaming. The TUI is still the default for local interactive use; the Web UI is the answer when you want to share a session, keep one running in the background, or drive cast from a browser/phone.

# Start (default 127.0.0.1:1337)
cast web

# Start on a different port
cast web --port 8080

# Bind 0.0.0.0 so it's reachable from other machines on the network
cast web --public

# Lifecycle
cast web status
cast web stop

On first start, cast auto-generates a password and saves it to webPassword in ~/.cast/settings.json. The login is always cast. HTTP Basic auth protects every API endpoint — the browser prompts for the password on first load. (Browser's own credential prompt, not a custom form.) The password is shown in the terminal on first run so you can copy it; after that, look it up in ~/.cast/settings.json.

The --public flag prints an explicit warning when binding to 0.0.0.0 — the password is the only thing standing between your machine and the rest of the network. Use it on a trusted LAN (or behind a reverse proxy / tunnel) — not on a public address.

Env vars: CAST_WEB_PORT (default 1337), CAST_WEB_HOST (default 127.0.0.1).

Interactive Commands

CLI Options

cast [options] [prompt]
  cast run [options] <message>   Non-interactive mode (stream to stdout, exit)
  cast upgrade [version] [--force]
                                Re-run installer to update

Options:
  -m, --model <model>        Model name
  -r, --reasoning <level>    off / low / medium / high / max
  -p, --persona <name>       Persona to use
  -c, --continue             Resume most recent session
  --resume                   Pick which session to resume (numbered list)
  --resume=<id>              Resume specific session by id
  -s, --session <id>         Resume specific session (alias for --resume=<id>)
  --bypass-permissions       Skip dangerous-command confirmation
  --skill <path>             Load extra skill (repeatable)
  --no-skills                Skip project/agents/global/plugin/builtin skill discovery
  --mcp <path>               Load extra MCP config (repeatable)
  --no-mcp                   Skip global/project MCP server discovery
  -v, --version              Show version
  -h, --help                 Show help

run subcommand:
  --format <default|json>    Output format
  (also accepts: -m, -r, -p, -c, -s, --bypass-permissions, --skill, --mcp)

Provider Setup

On first run, cast asks for your provider URL and API key, then saves both to ~/.cast/settings.json. No .env file needed.

Other environment variables (provider credentials live in the settings file, not env):

Works with anything that speaks the OpenAI API: OpenRouter, OpenAI, Ollama (http://localhost:11434/v1), vLLM, LiteLLM, Azure OpenAI, etc.

Architecture

src/
  core/           Agent logic (no UI dependency)
    loop.ts         Agent loop — streaming, tool dispatch, compaction
    tools.ts        Tool definitions (OpenAI function calling format)
    tools/          Tool executors: bash, files, search, web, task
    llm.ts          LLM interaction, streaming, retry, prompt caching
    session.ts      Session persistence, token estimation, compaction
    mcp.ts          MCP server connection (stdio + streamable HTTP)
    personas.ts     Persona loading (project > global > builtin)
    rules.ts        Cursor-compatible rule system (always/auto/lazy/manual, nested rules, @mentions)
    skills.ts       Agent Skills spec implementation
    config.ts       AppConfig, model validation, onboarding
    project.ts      System prompt assembly, trust gating
    startup.ts      Unified startup orchestration
    runner.ts       Queue management (steering, follow-ups)
    run.ts          Non-interactive runner (cast run)
    vendors.ts      Reasoning metadata, think-block parsing
    upgrade.ts      Self-update via GitHub releases
    ...
  ui/             Ink TUI components
    App.tsx         Top-level layout
    Composer.tsx    Input with autocomplete, image paste
    ChatLog.tsx     Message rendering
    commands.ts     Slash command handlers
    ...
  pickers/        Onboarding pickers (model, persona, reasoning)
  index.ts        CLI entry point

prompts/          System prompts, persona files, compaction templates
test/             Vitest unit tests
scripts/          esbuild bundle step
dist/             Compiled single-file bundle

Development

npm install --ignore-scripts
npm start               # Run from source (tsx)
npm run check           # Type check + lint (tsc + biome)
npm test                # Unit tests (vitest)
npm run build           # Bundle into dist/index.js (esbuild)
npm run format          # Auto-format (biome)
npm run e2e:plan        # Plan-mode e2e smoke via tmux (real provider, costs tokens)

License

MIT