AI

BEAM ships with three frontier models configured on every account — Claude (the default), GPT, and Gemini — plus Perplexity for deep research. You can ask one model, convene all of them, or chain research into planning. Every AI response ends with a usage line showing the model, cost, token count, and latency.

Three behaviors apply across every command here:

Anything you type that matches no command is treated as an ask — plain English works. Prefix a provider name to route directly: gpt ask which anecdote opens stronger? or gemini deep carrier pricing.

The AI reads your workspace by actually looking: it searches your docs, tasks, and memories before answering, and says honestly when it finds nothing rather than inventing an answer. It can create and edit docs and tasks on its own; anything destructive — deletes, moves, bulk changes — it refuses to run in conversation and tells you the command to run yourself. Where BEAM does propose actions for approval (plan, triage, action run), the proposal renders as a receipt you confirm with y or decline with n, and confirmations expire after a short window.

Answers you want to keep: add --save to store the response as a doc, or type shelf this after the fact.

ask

Aliases: ai
Purpose: Ask a single model, with access to your workspace.
Syntax:

>ask <question>
>ask --doc "Title" <question>
>ask --just <question>

Flags:

>--doc <title>     ground the answer in a specific doc
>--docs            ground the answer in all project docs
>--just            terse conversational answer, no tools, no memory
>--no-images       ask without attaching any recent image docs
>--save            save the answer as a doc

Examples:

>ask what should the closing five minutes of the talk feel like?
>ask --doc "Talk outline" is the middle section too long?

See also: council, just, deep

Streams the answer as it generates. On questions where a different mode would serve better — contested decisions, research questions — ask offers the upgrade as a one-key choice instead of silently switching.

just

Aliases: none
Purpose: Conversational mode — plain prose, no productivity scaffolding.
Syntax:

>just <anything>

Flags: none
Examples:

>just what's a good warm-up before public speaking?

See also: ask

A prefix, not a separate brain: just strips workspace context and tool access, so the answer is fast and stays out of your data.

council

Aliases: query
Purpose: Put one question to all models independently, side by side.
Syntax:

>council <question>
>council align <claude|gpt|gemini>
>council history
>council search <keyword>

Flags:

>--save    save the responses as a doc

Examples:

>council should the talk open with the demo or the story?
>council align claude

See also: debate, decide

Each model answers without seeing the others — where they agree you have something solid; where they split you have a decision to make. Responses render under their glyphs (◆ Claude, ◇ GPT, ○ Gemini). council align records which model you sided with; after enough decisions in a domain, BEAM notes which model has tended to match your judgment there — while still showing every position in full. history and search browse past council transcripts.

debate

Aliases: none
Purpose: Structured multi-round deliberation between models.
Syntax:

>debate <question>
>debate <blind|lenses|redteam|stakeholders|godin> <question>
>debate help

Flags:

>--save    save the debate as a doc

Examples:

>debate is a live demo worth the risk in a 30-minute slot?
>debate redteam our plan is to skip rehearsal and improvise the Q&A

See also: council, consensus

The classic format runs initial positions, two critique rounds, final positions, then one synthesis. Formats change the shape: blind (independent answers merged, no anchoring), lenses (each model argues from a different worldview), redteam (one proposes, one attacks, one judges), stakeholders (models roleplay the people affected), godin (smallest-viable-audience method). debate help describes each.

consensus

Aliases: sc
Purpose: Sample one model several times and vote for the consistent answer.
Syntax:

>consensus <question> [--samples N]

Flags:

>--samples <N>    number of samples (default 5)

Examples:

>consensus how long should the demo segment run?

See also: council, debate

Useful when you want confidence on a bounded question without a full multi-model session.

deep

Aliases: none
Purpose: Deep research with live web search; saves the result as a doc.
Syntax:

>deep <query>
>deep <task name or #N>
>deep all
>deep <query> --lib ieee s2

Flags:

>--docs               use all project docs as context
>--doc <title>        use specific docs as context
>--list               also create subtasks from the findings
>--no-save            skip the auto-saved doc
>--lib <sources>      search academic libraries (ieee, s2, zotero) instead of the web
>--topic <name>       link the result to an existing research topic
>--topic-new <name>   create a research topic and link the result

Examples:

>deep what do conference audiences remember from technical talks?
>deep #12 --topic-new "audience retention"

See also: research, library, ask

Runs asynchronously — you can keep working; BEAM chimes when the report lands. Point it at a task and it researches the task; deep all batches every active task.

The saved doc always announces itself. Every run ends with a receipt naming the doc, its #N handle, the project it landed in, and the command that undoes it — doc trash #N (and doc restore brings it back). deep all prints one receipt per doc plus a closing count. If a save does not land, the run says so instead of claiming one: nothing is written silently, and --no-save skips the doc entirely.

research

Aliases: none
Purpose: Manage research topics — living collections of docs, tasks, and notes.
Syntax:

>research create <title>
>research list
>research open <topic>
>research note <topic> <text>
>research link doc <name> to <topic>
>research link task #N to <topic>
>research link docs all to <topic>
>research unlink doc <name> from <topic>
>research summary <topic>
>research ask <topic> <question>
>research export <topic>
>research archive <topic>
>research delete <topic>
>research search <query>
>research probe add <topic> <question> => <expected>
>research probe list <topic>
>research probe run <topic>
>research probe rm <topic> <probeId>

Flags: none
Examples:

>research create "audience retention"
>research link doc "Deep Research: retention" to "audience retention"
>research ask "audience retention" what's the strongest finding so far?
>research probe add "audience retention" what is the 30-day retention rate? => 41%

See also: deep, docs

A topic collects everything you learn about one question. summary synthesizes the linked material; ask answers against it. Note the split: research organizes knowledge you have; deep goes and gets more.

Probes are verifiable questions with known answers that measure how well a topic actually answers things. probe run scores every probe on the topic and reports a pass rate you can watch move as the topic fills in — deterministic scoring, no model grading a model. The => separates the question from the expected answer; a numeric-looking answer is scored numerically unless you pass --numeric or --factual explicitly. You can also add probes from the Pool Health panel in a topic's detail view.

library

Aliases: lib
Purpose: Connect and search academic databases.
Syntax:

>library search <query>
>library add <ieee|s2|zotero> <api-key>
>library remove <ieee|s2|zotero>
>library status

Flags: none
Examples:

>library add s2 <your-api-key>
>library search retrieval practice long-term retention

See also: deep

Search hits IEEE Xplore and Semantic Scholar. Keys you add are yours (bring-your-own-key); with encryption set up they're stored encrypted on your device, otherwise they work for the session only. Pair with deep <query> --lib.

plan

Aliases: none
Purpose: Have the AI break a task into concrete proposed actions.
Syntax:

>plan <task>

Flags: none
Examples:

>plan #12

See also: action, triage

action

Aliases: actions
Purpose: Review and run AI-proposed actions on a task.
Syntax:

>action list <task>
>action run <task> <i>
>action cancel <task> <i>
>action permissions
>action permissions <tool> <auto|confirm|manual>
>action permissions reset

Flags: none
Examples:

>action list #12
>action run #12 2

See also: plan, suggestions

action permissions shows each tool's permission tier, action permissions <tool> <auto|confirm|manual> changes one, and action permissions reset drops every change you have made. The same table — with the reason for each tier and the ceremony it costs — is in Settings → Permissions; both surfaces write the same setting. On action run, auto tools run immediately, confirm tools show a y/n receipt, and manual tools show a receipt with a short code you have to type back. Over MCP, where BEAM renders no receipt of its own, confirm and manual tools are refused outright — if an external client reports a BEAM tool "unavailable," this is usually why. An auto tool that WRITES does not run there either on an ordinary account: it becomes a proposal you answer with proposals, at that tool's own confirmation. Reads still run on their own, and administrator accounts keep unattended writes. See MCP & proposals.

You can always make a tool stricter. Making one looser is allowed too — action permissions createProject auto is a supported choice — with two exceptions, and neither can be lowered from either surface. The first is the destructive tools (deleteTask, deleteList, deleteDoc, deleteProject, bulkMutate). The second is any tool on a connected MCP server that WRITES outside BEAM — a file on disk, a calendar event, a document somewhere else. Both ask for a typed code, for the same reason: BEAM's undo is its own event log, and neither an emptied project nor a written file is something that log can put back. Lowering one would drop the typed-code step everywhere at once, including over MCP where nothing asks, so BEAM refuses and says so. A connected server's READ-only tools are unaffected and still cost a plain y/n.

Multi-step agent chains cost the same as the steps in them. When BEAM proposes a chain of actions, approving the chain is not approving each tool in it: every step is checked against its own tier as it comes up, so a chain containing a confirm tool stops and shows you that step's receipt, and one containing a manual tool stops and asks for the typed code. A chain of four steps with three confirm tools asks you three times. If you decline a step — or type something else, or let the prompt expire — the rest of the chain does not run, and BEAM tells you where it stopped: "Stopped at step 2 of 4; steps 1-1 ran, 2-4 did not." Steps that already ran are not undone, and BEAM does not pretend otherwise. A chain containing any confirm or manual step cannot run from a piped bin/beam or over MCP, for the same reason a single confirm tool cannot: there is nobody there to answer the receipt. A chain made only of auto tools runs on those surfaces exactly as those tools do individually.

In the ask conversation the tier can only tighten, never widen. Raising a tool to confirm or manual stops ask from running it — the model is told it needs your approval and says so instead of doing it. Lowering a tool to auto does not give ask new abilities: action permissions editDoc auto changes how that edit behaves elsewhere, but it admits no tool the loop does not already run, and ask still will not delete anything. Note that council and deep gather their evidence through the same loop, so restricting a read tool also restricts what they can find.

triage

Aliases: none
Purpose: AI prioritization pass over your inbox.
Syntax:

>triage
>triage dates

Flags: none
Examples:

>triage
>triage dates

See also: brief, queue, plan

Proposes list moves, priorities, and due dates as a numbered receipt. Confirm all of it with y, or a subset with y 1,3,5. Nothing changes until you confirm.

portrait

Aliases: mirror
Purpose: An AI reading of your work patterns, saved as a doc.
Syntax:

>portrait

Flags: none
Examples:

>portrait

See also: memory, brief

resolve

Aliases: none
Purpose: Record what actually happened to a decision you already made.
Syntax:

>resolve #N <held|partial|reversed|0-1> [note]
>resolve <text from the question or choice> <outcome> [note]

Examples:

>resolve #1 held churn stayed flat through Q3
>resolve postgres partial faster, but the migration cost two weeks

See also: decide, decisions

The ledger is append-only, so resolve never edits the record — it amends it. Your original choice, rationale and predicted confidence stay exactly as you wrote them; the outcome sits beside them, which is what makes the pair worth keeping. held scores 1.0, partial 0.5, reversed 0.0, or give a number between 0 and 1 for a graded call. An outcome you genuinely cannot know is refused rather than scored — leaving the record open is honest, and a guessed number would quietly become part of your calibration record. #N is the row number decisions prints; a text reference that matches more than one decision refuses and lists them, because scoring the wrong record cannot be undone. A decision left unresolved past its review date (or fourteen days, if you set none) is flagged in decisions.

model

Aliases: none
Purpose: Show or switch the default AI provider.
Syntax:

>model
>model <claude|gpt|gemini>

Flags: none
Examples:

>model
>model gemini

See also: ask, council

The default provider answers ask and plain-English input. Council and debate always use all configured providers regardless of this setting.

suggestions

Aliases: suggest
Purpose: Show current AI suggestions.
Syntax:

>suggestions

Flags: none
Examples:

>suggestions

See also: accept, dismiss

accept

Aliases: none
Purpose: Accept a numbered suggestion.
Syntax:

>accept <number>

Flags: none
Examples:

>accept 2

See also: suggestions, dismiss

dismiss

Aliases: none
Purpose: Dismiss a numbered suggestion.
Syntax:

>dismiss <number>

Flags: none
Examples:

>dismiss 2

See also: suggestions, accept

workflow

Aliases: flow, wf
Purpose: Composite chain: deep research, then council, then a plan.
Syntax:

>workflow <question>

Flags:

>--skip-council    go straight from research to the plan
>--save-only       save the output without proposing tasks

Examples:

>workflow how should I structure the rehearsal week?

See also: deep, council, plan

Ends in the standard task-creation confirmation — the chain proposes, you approve.