Skip to content

Chat

sb chat is the interactive REPL for grounded, tool-using conversations in SecondBrain. It runs multi-turn local-first conversations, resumes prior sessions, uses governed tools under the current permission mode, and combines retrieval, optional web access, and provider-backed reasoning.

When to use chat vs. one-shot commands

Use sb chat when you need approval-gated tool use, multi-turn iteration, or session resumption. Use sb ask for fast citation-first one-shots, and sb pack to assemble a context bundle without an LLM round-trip.

Common launch modes

# Default interactive session
sb chat

# Resume the most recent session
sb chat --resume

# Resume the Nth recent session
sb chat --resume-index 2

# Use a specific agent profile
sb chat --agent-profile execution

# Scope a chat to a project workspace
sb chat --project proj_123

# Force a provider/model pair
sb chat --provider openai --model gpt-5.5

# Restrict available tool families
sb chat --tool-set connectors --tool-set mcp

# Stronger reasoning with periodic reflection
sb chat --think-level medium --reflect-every 3

# Approval-gated local work
sb chat --agent-profile execution --permission-mode ask

# Read-only planning pass before applying changes
sb chat --chat-mode plan

# Export or import a persisted session
sb chat --session my-session --export ./session.jsonl
sb chat --import ./session.jsonl

Use sb chat --help for the full live option set.

Session Model

sb chat persists sessions and can reopen them later.

  • --session uses a specific session id.
  • --project adds the project's instructions and curated knowledge sources to the runtime prompt and links the resulting session back to that project.
  • --resume reopens the most recent session.
  • --resume-index reopens older sessions by recency rank.
  • --export and --import move sessions to and from JSONL.
  • Inside chat, use /rename <title> to label the current thread. That title shows up in /session list and the resume picker.

Related inspection commands:

sb sessions list --json
sb sessions show <session_id> --json

Project Workspaces

Project-scoped chat is SecondBrain's local-first version of a project workspace. A project can carry instructions, curated knowledge sources, member access metadata, and linked chat sessions:

sb projects create "Alpha" --instructions "Answer for the launch team"
sb projects knowledge add <project_id> ./vault/alpha.md --title "Alpha brief"
sb projects members add <project_id> alice@example.com --role can_edit
sb projects context-audit <project_id>
sb chat --project <project_id>

Project instructions are treated as user-authored preferences, below system safety policy. Knowledge entries are scoped context, not executable instructions.

Use sb projects context-audit <project_id> before important project-scoped chat sessions to check the durable context layers: global profile preferences, standing workspace context, project instructions, curated knowledge sources, and recurring review routines. The audit is read-only; it returns concrete recommendations instead of rewriting prompts or project metadata. sb projects brief <project_id> includes the same context-health summary next to continuity, actions, decisions, and linked artifacts.

When a project uses knowledge_mode=retrieval, chat turns retrieve snippets from that project's knowledge sources for the current question instead of dumping every source preview into the prompt. The local serve API also honors project access metadata: can_use members can inspect and chat in shared projects, while can_edit or owner members are required to change instructions, knowledge sources, or membership.

Safety And Tool Access

The important runtime controls are:

  • --chat-mode ask|plan|decide|reflect|execute|brief
  • --permission-mode ask|plan|auto_edit|bypass
  • --approval-mode read_only|safe|full
  • Codex-compatible aliases:
  • --sandbox read-only maps to permission=plan, approval=read_only
  • --sandbox workspace-write maps to supervised permission=ask, approval=safe
  • --ask-for-approval never is accepted only with --sandbox read-only
  • --tool-set to narrow the exposed tool families
  • --web on|off|auto

Practical guidance:

  • use ask when tools may write or reach external systems
  • use --chat-mode plan when you want a read-only planning turn before applying changes
  • use permission plan or approval read_only when you need a hard read-only tool policy
  • use explicit --tool-set flags when you want a tighter tool surface
  • write approvals in the REPL now show a structured preview and can be approved once or saved as reusable rules for agent, person, or global scope

Plan And Apply Mode

sb chat supports a Codex/Claude-style two-phase workflow:

  • --chat-mode plan or /plan switches the session into read-only planning.
  • Plan turns force permission_mode=plan and approval_mode=read_only.
  • For codebase tasks, Plan turns add a deterministic read-only repository context with git state, actual relevant files, validation commands, and Plan/Apply safety checks so the model does not need to guess paths.
  • Plan turns emit a persisted plan_artifact event with plan_id, goal, summary, steps, expected changes, worker hints, verification, risks, and assumptions.
  • /apply [plan_id] executes the latest or selected plan in supervised safe mode.
  • The Serve UI's Ask/Plan/Execute controls use the same backend contract; the Plan button sends conversation_mode=plan, and the Apply action sends conversation_mode=execute plus apply_plan_id.

During apply/execute turns, code work may use the governed superpower worker policy. Codex defaults to read-only suggest; auto-edit remains approval gated. full-auto is not enabled by default.

For Codex CLI-style automation, sb chat --print --output-format codex-json emits thread.started, turn.started, item.completed, and turn.completed JSONL events. --output-last-message <path> writes the final assistant message to disk. Machine-readable json, stream-json, and codex-json print modes do not emit the interactive startup banner on stdout.

Reasoning And Runtime Options

Useful reasoning controls from the live CLI:

  • --think-level off|low|medium|high
  • --max-steps
  • --timeout-s
  • --reflect-every
  • --failover
  • --subagents
  • --health-policy approval|pause|observe or --quota-policy approval|pause|observe
  • --health-max-runtime-minutes, --health-max-total-tokens, --health-max-cost-usd, and related health budget flags
  • quota aliases for common budgets: --quota-max-session-tokens, --quota-max-cost-usd, and --quota-max-context-pct

These options change how the runtime reasons and which execution features are available, but they do not replace the normal permission model.

--subagents exposes bounded delegation tools in the chat harness. The parent prompt now treats sub-agents as Codex-style child runs rather than a generic swarm: the parent should keep critical-path work local, delegate only independent side work, and pass each child an explicit ownership_scope, deliverable, shared_context, coordination_notes, and verification expectation. Child runs receive the same coordination contract as trusted context, including the rule that they must not overwrite user or sibling-agent changes and should return compact findings with sources and verification status for synthesis.

Workforce Commands

The REPL can inspect and operate local review-first workforces without leaving the chat session:

/workforce list
/workforce show portfolio_scouts
/workforce dashboard --workforce portfolio_scouts
/workforce run portfolio_scouts --dry-run --json
/workforce continue <run_id> --yes

/workforce run and /workforce continue are mutating commands, so they follow the current permission mode. Plan mode blocks them; ask mode prompts unless you pass --yes.

Provider Capability Commands

The REPL exposes the same provider capability contract used by Serve UI and diagnostics:

  • /providers [filter|--json] shows the provider matrix with readiness, streaming, tools, structured output, reasoning, trace, cache, and usage support.
  • /provider shows detail for the active provider; /provider <name> [model] still switches providers after readiness checks.
  • /models [provider] shows discovered or fallback models together with the model source and provider capability context.
  • /status and /settings include the current provider capability summary.

Provider-aware warnings are printed when a runtime control is ineffective for the selected provider, such as reasoning controls on a local echo provider, native tool calls on bridge/local providers, or provider-hosted web search when SecondBrain retrieval is the actual web path.

Operator Health Policy

sb chat now has an enforced local health gate for interactive sessions. The REPL tracks session runtime, token and cost burn, context-window usage, loop warnings, repeated plan/progress events, failed tools, slow tools, and turns without tool or retrieval evidence.

By default, threshold breaches create an approval request and pause further natural-language turns until the operator approves. Use --health-policy pause to auto-pause without creating an approval, or --health-policy observe to keep the health snapshot visible without enforcement.

Inside the REPL:

  • /health shows the current health snapshot, budget usage, recovery hint, and pending approval.
  • /health risks shows active risk flags with threshold values.
  • /health policy shows the effective configured budgets.
  • /health approve approves a pending health-policy gate from the terminal.
  • /health resume resumes once by approving the current risk fingerprint.
  • /health observe disables enforcement for the current session.

Health decisions are written as local session events and checkpoints, so later inspection can connect the policy decision to the session, risk evidence, approval request, and resume point.

Quota accounting uses a shared runtime ledger for token, cache-token, cost, and context pressure. Inspect a persisted session with:

sb quota status --session <session_id> --json

Voice And Streaming

sb chat also exposes voice and streaming controls:

  • --stream
  • --voice-mode push-to-talk|vad|hot-mic|wake-word
  • --vad
  • --stream-speak
  • --barge-in
  • --stt-provider and --tts-provider

Those settings are optional. The default operator path is still text-first chat.

Antahkarana Integration

sb chat runs with Antahkarana enabled by default:

sb chat
sb chat --no-antahkarana

That means each turn can pass through the cognitive loop before the main LLM/tool turn. If you need a plainer runtime for debugging or comparison, disable it explicitly.

See ../components/antahkarana/overview.md.

Operational Tips

  • Prefer sb ingest and sb context index before heavy chat use so retrieval has current material.
  • Prefer --agent-profile execution --permission-mode ask for supervised coding or ops work.
  • Prefer --tool-set narrowing when you want predictable tool exposure.
  • Prefer /health when a session feels stuck, expensive, or repetitive; it shows the current operator gate and recovery hint.
  • Runtime /provider switches validate provider readiness and print setup guidance immediately instead of failing on the next turn.
  • Use /providers when provider behavior is unclear; it shows what the active adapter can stream, trace, meter, cache, and control.
  • If provider behavior looks wrong, run sb providers health and sb doctor.