cru chat

Start an interactive AI chat session with access to your kiln.

Synopsis

cru chat [OPTIONS] [QUERY]

Running cru with no arguments starts chat mode.

Arguments

Argument	Description
`[QUERY]`	Optional one-shot query. If omitted, starts interactive mode.

Description

The chat command connects an AI agent to your knowledge base. The agent can search, read, and explore your notes. In normal mode it has full tool access. Switch to plan mode for read-only exploration, or auto mode to skip tool confirmation prompts.

Options

Agent Selection

`-a, --acp <PROFILE>`

ACP profile to use — an external agent subprocess. Skips the splash screen and connects directly. --agent is the older spelling of this flag and still works.

cru chat --acp claude
cru chat --acp gemini
cru chat --acp codex

Available profiles: claude, gemini, codex, cursor, opencode, hermes, or any custom profile defined in config.toml. The agent must be installed and available in your PATH; cru agents list reports which are.

cru chat does not take an agent card. It resolves its agent client-side, while cards are resolved by the daemon at session create — use cru session create --agent <card> for a card-backed session.

`--provider <PROVIDER>`

LLM provider from your [llm.providers] config section.

cru chat --provider openai
cru chat --provider ollama

Session Management

`-r, --resume <SESSION_ID>`

Resume a previous session by ID. Session IDs follow the format chat-YYYYMMDD-HHMM-xxxx.

cru chat --resume chat-20250102-1430-a1b2

`--record <FILE>`

Record the TUI session to a JSONL file for later replay.

cru chat --record session-recording.jsonl

`--replay <FILE>`

Replay a previously recorded JSONL session.

cru chat --replay session-recording.jsonl

`--replay-speed <N>`

Playback speed multiplier for replay (default: 1.0).

`--replay-auto-exit [<DELAY_MS>]`

Auto-exit after replay completes. Optional delay in milliseconds (default: 2000).

Context & Knowledge Base

`--no-context`

Skip context enrichment. Faster startup, but the agent won’t have knowledge base access.

cru chat --no-context "What's 2+2?"

`--max-context <TOKENS>`

Maximum context window tokens (default: 16384).

`--context-size <N>`

Number of context results to include (default: 5).

Mode & Configuration

`--plan`

Start in plan mode (read-only) instead of normal mode. The agent can search and read notes but can’t execute write operations. Toggle during a session with /plan and /default commands.

cru chat --plan

`--set <KEY[=VALUE]>`

Session configuration overrides using the same syntax as the TUI :set command. Can be repeated.

cru chat --set model=llama3 --set thinkingbudget=high
cru chat --set perm.autoconfirm_session

`-e, --env <KEY=VALUE>`

Environment variables to pass to the ACP agent. Can be repeated.

cru chat --acp claude --env ANTHROPIC_BASE_URL=http://localhost:4000

Runtime

`--standalone`

Run with an in-process daemon instead of connecting to the background server. Useful for single-session use, restricted environments, or testing. Data persists to the kiln’s .crucible/ directory.

cru chat --standalone

Chat Modes

Crucible has three chat modes. Cycle between them with Shift+Tab during a session.

Normal Mode (Default)

Full tool access. The agent can search, read, create, modify, and delete notes. Tool calls prompt for confirmation before executing.

Plan Mode

Read-only. The agent can search and read your notes, but write operations are blocked. Good for exploration and brainstorming without risk of changes.

Toggle with /plan or start directly:

cru chat --plan

Auto Mode

Full tool access with automatic approval. Tool calls execute without confirmation prompts. Useful for trusted workflows where you don’t want to approve every action.

In-Chat Commands

Slash Commands

Command	Description
`/mode`	Cycle through chat modes
`/default`	Switch to normal (ask-for-writes) mode
`/plan`	Switch to plan (read-only) mode
`/auto`	Switch to auto (full access) mode
`/undo [N]`	Undo the last N exchanges (default 1)
`/help [topic]`	Show help (same as `:help`)

Every mode the daemon declares gets its own slash command — a Lua-declared review mode is reachable as /review. Plugin-declared commands also run as slash commands. Anything else typed with a leading / is not an error: it is forwarded to the agent as ordinary chat text.

REPL Commands

Command	Description
`:model`	Open model picker popup
`:model <name>`	Switch to specific model
`:set option=value`	Set runtime config option
`:set thinkingbudget=high`	Enable extended thinking
`:quit` / `:q`	Exit chat

See Commands for complete REPL command reference.

Keyboard Shortcuts

Key	Action
`Ctrl+C`	Cancel / Exit
`Ctrl+T`	Toggle thinking display
`Shift+Tab`	Cycle mode (Normal, Plan, Auto)

Agent Access

In chat mode, the agent has access to these tools:

Read operations:

semantic_search - Find conceptually related notes
grep_notes - Find exact text matches
property_search - Filter by metadata
read_note - Read note contents

Write operations (normal and auto modes):

create_note - Create new notes
update_note - Modify existing notes
delete_note - Remove notes (with confirmation in normal mode)

Examples

Quick Question

cru chat "What do I know about project management?"

Interactive Session

cru

Then ask questions:

You: What are my notes about productivity?

Agent: I found several notes related to productivity...

You: Can you summarize the key techniques?

Agent: Based on your notes, the main techniques are...

Use a Specific ACP Agent

cru chat --acp claude "Summarize my notes on API design"

Resume a Previous Session

cru chat --resume chat-20250102-1430-a1b2

Plan Mode Exploration

cru chat --plan "What patterns do my testing notes share?"

Custom Provider with Overrides

cru chat --provider ollama --set model=llama3.2 --set thinkingbudget=high

Record and Replay

# Record a session
cru chat --record demo.jsonl

# Replay it later
cru chat --replay demo.jsonl --replay-speed 2.0

Model Switching

Change models at runtime without restarting:

:model                      # Opens model picker
:model claude-3-5-sonnet    # Switch directly
:model gpt-4o

Model changes persist for the session and sync to the daemon.

Extended Thinking

For models that support reasoning tokens (Claude with thinking budget, DeepSeek-R1, etc.):

:set thinkingbudget=high    # Enable extended thinking (8192 tokens)
:set thinkingbudget=off     # Disable thinking
:set thinking               # Show thinking in UI
:set nothinking             # Hide thinking display

Toggle thinking display with Ctrl+T.

Presets: off, minimal (512), low (1024), medium (4096), high (8192), max (unlimited)

Session Resume

Sessions auto-save and can be resumed:

cru session list                          # See available sessions
cru chat --resume chat-20250102-1430-a1b2 # Resume specific session
cru session open chat-20250102-1430-a1b2  # Same as chat --resume

Statusline Notifications

The statusline displays notifications when files change in your kiln:

File changes appear dimmed on the right side (e.g., “notes.md modified”)
Multiple changes batch together (e.g., “3 files modified”)
Errors appear in red and stay visible longer

Notification timing:

Info notifications: 2 seconds
Error notifications: 5 seconds

This provides real-time feedback when other tools or editors modify your notes while you’re chatting.

Tips

Effective Prompts

Be specific about what you want:

"Find notes about React hooks and summarize the patterns I use"

"What do I have about React?"

Building Context

The agent remembers conversation history. Build on previous answers:

You: What notes do I have about testing?
Agent: [Lists notes]
You: Focus on the integration testing ones
Agent: [Narrows down]
You: What patterns do they share?

Verification

Ask the agent to cite sources:

"What's my approach to error handling? Cite the specific notes."