> User Manual

Everything you need to know about installing, configuring, and using Bernard.

1. Getting Started

Installation

Bernard requires Node.js 20.9.0 or later. Install it globally from npm:

$ npm install -g bernard-agent

After installation, the bernard command is available globally in your terminal.

First-Time Setup

On first launch, Bernard runs an interactive setup wizard that walks you through selecting a provider and entering your API key. You can also configure it manually:

# Store an API key
$ bernard add-key anthropic sk-ant-...

# Verify it's configured
$ bernard providers

All configuration is stored in ~/.bernard/:

• keys.json — Stored API keys (file permissions set to 0600)
• preferences.json — Provider, model, theme, and option choices
• .env — Fallback environment variable file

Basic Usage

Launch the REPL by running bernard with no arguments. Type natural-language requests and Bernard will use its tools to help you:

$ bernard
bernard> what git branch am I on?
  ▶ shell: git branch --show-current
  You're on the main branch.

Type /help to see available slash commands, or /exit (or Ctrl+C) to quit.

CLI Flags

Resuming Conversations

Use the -r flag to pick up where you left off. Bernard saves conversation history to disk between sessions and replays it on resume. A session boundary marker is injected so the agent knows prior tasks are considered complete.

$ bernard -r
# Previous conversation is restored

2. Configuration

Environment Variables

.env File Loading

Bernard loads environment variables from .env files in this priority order:

1. Current working directory — ./.env (checked first)
2. Home config — ~/.bernard/.env (fallback)

API keys stored via bernard add-key take precedence over .env values.

API Key Management

# Add a key
$ bernard add-key anthropic sk-ant-...

# Remove a key
$ bernard remove-key anthropic

# Check key status for all providers
$ bernard providers

Keys are stored in ~/.bernard/keys.json with file permissions set to 0600 (owner read/write only).

Options Management

Configurable options can be viewed and changed from the CLI or within the REPL (/options):

# List current option values
$ bernard list-options

# Reset a single option to default
$ bernard reset-option max-tokens

# Reset all options to defaults
$ bernard reset-options

Themes v0.3.0+

Bernard comes with six built-in color themes. Switch at any time using the /theme REPL command. Your choice persists across sessions.

3. Providers

Bernard uses the Vercel AI SDK for unified access to multiple LLM providers. All tools, memory, and capabilities work identically regardless of which provider you choose.

Anthropic

Default provider. Set ANTHROPIC_API_KEY or run bernard add-key anthropic <key>.

Available Models

• claude-sonnet-4-5-20250929 (default)
• claude-opus-4-6
• claude-haiku-4-5-20251001
• claude-opus-4-20250514
• claude-sonnet-4-20250514

OpenAI

Set OPENAI_API_KEY or run bernard add-key openai <key>.

Available Models

• gpt-5.2 (default)
• gpt-5.2-chat-latest
• o3
• o3-mini
• gpt-4o-mini
• gpt-4.1
• gpt-4.1-mini
• gpt-4.1-nano

xAI

Set XAI_API_KEY or run bernard add-key xai <key>.

Available Models

• grok-4-fast-non-reasoning (default)
• grok-4-fast-reasoning
• grok-4-1-fast-non-reasoning
• grok-4-1-fast-reasoning
• grok-4-0709
• grok-code-fast-1
• grok-3
• grok-3-mini

Switching Providers

There are three ways to switch your provider and model:

1. CLI flags — bernard -p openai -m gpt-4o
2. REPL commands — /provider and /model for interactive selection
3. Environment variables — BERNARD_PROVIDER and BERNARD_MODEL

Changes made via /provider and /model are saved to preferences and persist across sessions.

4. REPL Commands

Type slash commands in the REPL to control Bernard. Tab-completion is supported, and live hints appear as you type.

5. Tools & Capabilities

Bernard has access to a set of built-in tools that it uses autonomously based on your requests. You don't call tools directly — Bernard decides when to use them.

Shell

Executes shell commands in your current working directory. Output is captured and returned to the AI. Commands have a configurable timeout (default: 30 seconds) and a 10 MB output buffer.

Dangerous Command Detection

Bernard detects potentially dangerous commands and asks for confirmation before executing them. The following patterns trigger the safety check:

• rm with -r or -f flags
• sudo
• mkfs, dd
• Writing to /dev/sd*
• chmod 777, chown -R
• reboot, shutdown
• systemctl stop/disable/mask
• kill -9, pkill, killall

Memory

Persistent, disk-backed storage at ~/.bernard/memory/. Survives across sessions. The agent can list, read, write, and delete memory entries by key.

Use this for things like project conventions, server addresses, or personal preferences.

bernard> remember that this project uses pnpm
  ▶ memory: write "project-conventions"
  Saved to persistent memory.

Scratch

Session-only scratch notes for tracking complex task progress, intermediate findings, and working plans. Scratch notes survive context compression within a session but are discarded when the session ends. Same actions as memory: list, read, write, delete.

Web Read

Fetches a web page by URL and converts it to markdown. Useful for reading documentation, articles, Stack Overflow answers, or any public URL. Supports an optional CSS selector to extract specific content.

• Strips navigation, footer, scripts, and other non-content elements
• HTML limit: 1 MB, output limit: 20,000 characters
• Fetch timeout: 15 seconds

Sub-Agents

Bernard can delegate tasks to independent sub-agents that run in parallel. Each sub-agent gets its own AI context with access to the base tools (shell, memory, web, cron, MCP tools, etc.) but not the agent tool itself (no recursive sub-agents), and no conversation history.

• Up to 4 concurrent sub-agents
• Each sub-agent gets up to 10 tool steps
• Task descriptions must be self-contained — sub-agents have no prior context
• Sub-agents can access RAG memory and persistent memory for context

bernard> check disk usage and count lines of code in parallel
  ▶ agent: "Check disk usage"
  ▶ agent: "Count lines of code"
  [sub:1] ▶ shell: df -h /
  [sub:2] ▶ shell: find . -name "*.ts" | xargs wc -l
  Disk: 42G used of 256G (16%). Code: 2,847 lines across 23 files.

Tasks v0.6.0+

Tasks are isolated, focused executions that return structured JSON output. Unlike sub-agents (which return free-form text), tasks always produce a {status, output, details?} response — making them ideal for machine-readable results, routine chaining, and conditional branching.

• 5-step budget (vs. 10 for sub-agents) — quick and focused
• Structured JSON output — always returns {status: "success"|"error", output, details?}
• No conversation history — completely isolated from the current session
• Available as both a tool (the agent can call task during routines) and a REPL command (/task)
• Shares the same 4-slot concurrency pool with sub-agents

bernard> /task List all TypeScript files in src
  ┌─ task — List all TypeScript files in src
  ▶ shell: find src -name "*.ts" -type f
  └─ task success: Found 23 .ts files

Date/Time

The datetime tool returns the current date and time information. The time_range tool calculates the duration between two military/24-hour times, and the time_range_total tool calculates the total duration across multiple military time ranges.

Wait

Pauses execution for a specified number of seconds. Useful when a task requires waiting within the current turn (e.g., server restart, build propagation).

• Minimum: 0.1 seconds
• Maximum: 300 seconds (5 minutes)

6. Routines v0.5.0+

Routines are named, persistent multi-step workflows that Bernard can execute on demand. Use them to capture repeatable procedures — deploy scripts, release checklists, onboarding flows, code review steps — as structured instructions that Bernard follows with full tool access.

Creating Routines

There are two ways to create a routine:

Natural language

Ask Bernard to save a routine directly. The agent will use the routine tool to create it:

bernard> save a routine called "deploy-staging" that builds, pushes the docker image, and updates k8s
  ▶ routine: create { id: "deploy-staging", name: "Deploy to Staging", ... }
  ✓ Routine "Deploy to Staging" (/deploy-staging) created.

Guided creation

Use the /create-routine command for a guided, interactive experience. Bernard will ask about your workflow, clarify ambiguities, and draft a well-structured routine using prompt-engineering best practices before saving:

bernard> /create-routine
  What workflow would you like to save as a routine?
  … (interactive Q&A to build the routine)

Task routines

Use /create-task to create a routine whose ID follows a task- prefix convention. Bernard will generate an ID prefixed with task-, letting you organize quick, focused procedures under a consistent /task-{name} namespace:

bernard> /create-task
  What task would you like to save?
  … (interactive Q&A — Bernard will generate an ID prefixed with task-)

bernard> /task-run-tests
  (Bernard follows the saved task procedure)

Invoking Routines

Type /{routine-id} to execute a saved routine. Bernard follows the stored procedure with full access to all tools:

bernard> /deploy-staging
  (Bernard follows the saved deploy steps)

bernard> /deploy-staging to production instead
  (Bernard follows the routine with "to production instead" as additional context)

Routine names appear in the live autocomplete hints when you type /.

Managing Routines

The agent has a routine tool for full lifecycle management. You can also use /routines in the REPL for a quick list.

Storage: one JSON file per routine in ~/.local/share/bernard/routines/. Maximum 100 routines. IDs must be lowercase kebab-case (1–60 characters).

7. Specialists v0.6.0+

Specialists are reusable expert profiles — persistent personas with custom system prompts and behavioral guidelines that shape how a sub-agent approaches work. Unlike routines (which define what steps to follow), specialists define how to work.

Creating Specialists

Ask Bernard to create a specialist. The agent will use the specialist tool with an ID, name, description, system prompt, and optional guidelines:

bernard> create a specialist called "code-reviewer" that reviews code for correctness, style, and security
  ▶ specialist: create { id: "code-reviewer", name: "Code Reviewer", … }
  ✓ Specialist "Code Reviewer" (code-reviewer) created.

Each specialist has a system prompt (the persona and behavioral instructions) and optional guidelines (short behavioral rules appended as bullet points).

Invoking Specialists

Type /{specialist-id} followed by a task description to run a specialist. Bernard delegates the task to a sub-agent that uses the specialist’s system prompt and guidelines as its persona:

bernard> /code-reviewer review the changes in src/agent.ts
┌─ spec:1 [Code Reviewer] — review the changes in src/agent.ts
  ▶ shell: git diff src/agent.ts
└─ spec:1 done

Each specialist run gets its own generateText loop with a 10-step budget and no conversation history. Specialists share the concurrency pool with sub-agents and tasks (4 slots max).

Auto-Dispatch v0.7.0+

Bernard automatically detects when your message matches a saved specialist’s domain using lightweight keyword matching against specialist names and descriptions. For strong matches (score ≥ 0.8), Bernard delegates to the specialist immediately without asking. For partial matches (score 0.4–0.8), Bernard confirms with you before dispatching. This means you don’t need to remember specialist names — just describe what you need and Bernard will route to the right expert.

Managing Specialists

The agent has a specialist tool for full lifecycle management. You can also use /specialists in the REPL for a quick list.

Storage: one JSON file per specialist in ~/.local/share/bernard/specialists/. Maximum 50 specialists. IDs must be lowercase kebab-case (1–60 characters).

Specialist Suggestions v0.6.0+

Bernard automatically detects recurring delegation patterns in your conversations and suggests new specialists. Detection runs in the background when you exit a session or use /clear --save.

When candidates are detected, you’ll see a notification at the start of your next session:

  2 specialist suggestion(s) pending. Use /candidates to review.

Use /candidates to see pending suggestions with their name, description, confidence score, and reasoning. You can then accept or reject candidates conversationally (e.g., “accept the code-review candidate”), and Bernard will create the specialist for you.

8. Cron Jobs

Bernard can schedule recurring tasks that run in the background on a timer. Cron jobs execute an AI prompt through the agent on each run, with access to all tools.

Creating Jobs

Ask Bernard to create a cron job with natural language, or the agent will use the cron_create tool with a name, cron expression, and prompt:

bernard> every hour, check if the API is healthy
  ▶ cron_create: "api-health-check"
  Schedule: 0 * * * * (every hour)
  ✓ Created cron job — runs every hour.

The cron daemon starts automatically when the first job is created.

Managing Jobs

The agent has tools for full cron job lifecycle management:

Daemon Management

The cron daemon is a background process that ticks and executes jobs on schedule. It starts automatically when enabled jobs exist and stops automatically when none remain.

• The daemon runs independently of the REPL — jobs continue after you exit Bernard
• Use /cron in the REPL to check daemon status
• If the daemon misbehaves, restart it with the cron_bounce tool or bernard cron-bounce

Alerts & Notifications

Cron jobs can generate alerts (e.g., when a monitored API goes down). Alerts are stored locally and can trigger desktop notifications.

Use the --alert <id> flag to open a Bernard session with alert context pre-loaded, so you can review and act on the alert immediately.

$ bernard --alert abc123
  Alert from cron job: api-health-check
  Message: API returned 503
  Time: 2025-01-15T10:00:00Z

Logs

Cron job execution logs are stored locally. The agent has the following tools to inspect and manage past runs:

• cron_logs_list — List recent execution runs for a specific job
• cron_logs_get — Retrieve a specific log entry by ID
• cron_logs_summary — Aggregate statistics across jobs (run counts, success/error rates)
• cron_logs_cleanup — Rotate and delete old log entries to reclaim space

CLI Commands

Cron jobs can also be managed from the command line without entering the REPL:

9. MCP (Model Context Protocol)

Bernard supports the Model Context Protocol for connecting to external tool servers. MCP servers extend Bernard with additional capabilities like file system access, database queries, API integrations, and more.

Configuration

MCP servers are configured in ~/.bernard/mcp.json. The file uses a mcpServers object where each key is the server name:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "env": {}
    },
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "type": "sse",
      "headers": {
        "Authorization": "Bearer token..."
      }
    }
  }
}

Stdio Servers

Stdio-based MCP servers are spawned as child processes. Specify the command, optional args array, and optional env object:

URL-Based Servers

URL-based servers connect over HTTP using SSE or HTTP transport:

You can also add URL-based servers from within a session using the mcp_add_url tool.

Commands

10. RAG Memory

Bernard automatically builds a long-term knowledge base from your conversations using local embeddings and retrieval-augmented generation (RAG). No data leaves your machine.

How It Works

1. Extraction — When a session ends (and the conversation has 4 or more messages), a background worker extracts durable facts from the conversation. Each domain has a specialized extraction prompt that filters for relevant facts.
2. Embedding — Facts are embedded locally using fastembed — no API calls required. Embeddings and facts are stored in ~/.bernard/rag/memories.json.
3. Retrieval — On each new message, Bernard searches the RAG store using cosine similarity. The top results (up to 3 per domain, 9 total) are injected into the system prompt as recalled context.
4. Deduplication — Near-duplicate facts (similarity > 0.92) are automatically skipped to prevent bloat.

Domains v0.3.0+

Facts are categorized into four domains, each with a specialized extraction prompt:

Managing Facts

Use the CLI or REPL to browse and manage stored facts:

# List all stored facts
$ bernard facts

# Search facts by query
$ bernard facts "deployment workflow"

# Search using a file's contents as query
$ bernard facts ./src/deploy.ts

# Delete ALL facts (requires exact confirmation phrase)
$ bernard clear-facts

Both commands show facts grouped by domain and offer an interactive prompt to select and delete facts by number (e.g., 1,3,5-8).

The clear-facts command deletes all stored facts. It displays a per-domain breakdown and requires you to type the exact phrase yes, delete all facts before proceeding.

Within the REPL:

• /rag — Show total count, per-domain breakdown, and 10 most recent facts
• /facts — Show facts currently in the context window with similarity scores

Auto-Expiration v0.4.0+

RAG memories have a configurable TTL (default: 90 days). Facts that are never accessed decay over time and are eventually pruned. Actively recalled facts have their lastAccessed timestamp refreshed, keeping them alive.

• Max memories: 5,000
• Default TTL: 90 days
• Decay half-life: 90 days (used for capacity-based pruning when memory count exceeds the cap)
• Similarity threshold: 0.35 (minimum for retrieval)
• Disable RAG entirely by setting BERNARD_RAG_ENABLED=false

11. Auto-Updates v0.3.0+

Bernard can check for new versions on npm and install them for you. Update checks are cached for 24 hours.

# Check for updates interactively
$ bernard update

# Or from within the REPL
bernard> /update

# Enable automatic update checks on startup
$ bernard auto-update on

# Disable automatic update checks
$ bernard auto-update off

When auto-update is enabled, Bernard checks for new versions each time you start a session and notifies you if one is available.