Getting Started with Crucible

Welcome to Crucible! This guide will help you install, configure, and run your first commands.

What is Crucible?

Crucible is a knowledge-grounded agent runtime — agents that draw from a knowledge graph make better decisions. Your notes, conversations, and wikilinks form a living knowledge graph that grows over time. Agents draw from this graph automatically via Precognition, and everything beyond the knowledge core is extensible via Lua scripting and plugins.

Key Features:

Knowledge-grounded agents — Precognition auto-injects relevant context before each LLM turn
Sessions are notes — every conversation persists as searchable, linkable markdown
Wikilink-based knowledge graph with block-level semantic search
Neovim-like architecture — Lua/Fennel plugins, TUI-first, headless daemon with RPC
Plaintext first — markdown files are your source of truth, no lock-in

Prerequisites

Before installing Crucible, make sure you have:

Rust toolchain (1.75 or newer)
- Install via rustup: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Cargo (comes with Rust)
Git (for cloning the repository)

Installation

1. Clone the Repository

git clone https://github.com/mootikins/crucible.git
cd crucible

2. Build Crucible

cargo build --release

The binary will be at target/release/cru.

3. Add to PATH (Optional)

# Add to your shell profile
export PATH="$PATH:/path/to/crucible/target/release"

# Or create a symlink
sudo ln -s /path/to/crucible/target/release/cru /usr/local/bin/cru

Configuration

Initialize with `cru init`

Crucible stores notes in a kiln — a directory of markdown files that forms your knowledge graph. Projects (code repositories) can bind to one or more kilns.

The fastest way to set up is cru init. It detects what kind of directory you are in and walks you through an interactive setup.

Initializing a kiln

Run cru init inside your notes directory:

cd ~/notes
cru init

Crucible detects whether .crucible/kiln.toml or .crucible/project.toml already exists. If neither is found, it asks what this directory is:

? What is this directory?
> Kiln (knowledge store for notes and sessions)
  Project (code repository with kiln bindings)

For a kiln, it prompts for a name and data classification (public, internal, confidential, restricted), then creates .crucible/kiln.toml and registers the kiln in your global config under [kilns].

Initializing a project

Run cru init inside a code repository:

cd ~/myproject
cru init

Choose “Project” when prompted. Crucible creates .crucible/project.toml and asks which of your registered kilns to bind. The project is registered in your global config under [projects.*].

Non-interactive mode

Use -y to skip prompts and accept defaults (defaults to kiln, uses the directory name as the kiln name):

cru init -y

Use --force to reinitialize an already-configured directory.

First-run setup wizard

If no global config exists yet (~/.config/crucible/config.toml), running bare cru or interactive cru chat (no query, record, or replay arguments) on a terminal launches a first-run wizard that walks you through choosing an LLM provider and model. cru init does not run this wizard — it has its own prompts (directory type, name, data classification) and does not ask about providers or embeddings.

Manual configuration

You can also create the config file by hand. See Configuration for the full reference.

Create ~/.config/crucible/config.toml:

default_kiln = "notes"

[kilns]
notes = "~/notes"

[llm]
default = "local"

[llm.providers.local]
type = "ollama"
endpoint = "http://localhost:11434"
default_model = "llama3.2"

[enrichment.provider]
type = "fastembed"

Without an [enrichment] section the daemon skips embedding generation entirely, so semantic search returns nothing. See embedding for the other providers.

For multiple kilns and project bindings:

default_kiln = "vault"

[kilns]
vault = "~/vault"
docs = "~/crucible/docs"

[projects.crucible]
path = "~/crucible"
kilns = ["docs", "vault"]

See [[Configuration#Migrating from kiln_path to [kilns]]] if you have an existing kiln_path setup.

Your First Commands

1. Check Kiln Statistics

cru stats

You should see:

📊 Kiln Statistics

📁 Total files: 42
📝 Markdown files: 38
🔍 Indexed: 38
💾 Total size: 156 KB
🗂️  Kiln path: /home/user/Documents/my-kiln

✅ Kiln scan completed successfully.

2. Process Your Notes

cru process

This parses all markdown files, extracts metadata, wikilinks, tags, and blocks, generates embeddings, and stores everything in the local database.

Common flags:

--force - Reprocess all files regardless of changes
--watch - Keep watching for changes
--dry-run - Preview without making changes

3. Start Chatting

cru chat

The first time you run cru chat, Crucible automatically starts a background daemon (cru daemon serve) if one isn’t already running. You don’t need to start it manually. The daemon handles session state, file watching, and multi-session support over a Unix socket.

Chat modes (cycle with BackTab):

Normal (default): Full access, agent can read and modify files
Plan: Read-only, agent can search and read but not modify
Auto: Auto-approve tool calls without prompting

Slash commands: /mode, /plan, /auto, /default, /undo, /help (any other /text is sent to the agent as a chat message) REPL commands: :model, :set, :export, :clear, :help

Understanding the Database

Crucible stores processed data under .crucible/ inside the kiln:

Path	Contents
`<kiln_path>/.crucible/crucible-sqlite.db`	Notes, blocks, links, properties, embeddings

The SQLite database contains:

Parsed note metadata (frontmatter, tags)
Extracted blocks (headings, paragraphs, lists)
Wikilink relationships (knowledge graph)
Content hashes for change detection

Important: The database is derived data. Your markdown files are the source of truth. You can safely delete .crucible/ and rebuild with cru process --force.

Next Steps

Your First Kiln - Create a new knowledge base from scratch
Basic Commands - Learn all the essential CLI commands
Wikilinks - Understand Crucible’s linking syntax
Frontmatter - Learn about YAML metadata
Index - Explore different ways to organize your notes

Troubleshooting

”Error: kiln path does not exist”

Check that your kiln is registered under [kilns] in ~/.config/crucible/config.toml and that the path resolves. You can also point Crucible at a kiln directly with $CRUCIBLE_KILN.

Processing is slow

Processing runs inside the daemon, which manages its own parallelism — the --parallel flag is accepted but currently has no effect. The usual cause of slow processing is embedding generation; check your [enrichment] provider.

Chat doesn’t respond

Make sure your LLM provider is running and configured. For Ollama: cru chat --provider ollama. For other providers, check your config.toml settings.

Uninstalling

Stop the daemon

cru daemon stop

Remove the binary

If you built from source, delete the checkout (and any symlink you created in step 3 of Installation). If you used the release installer script, the binary is at ~/.cargo/bin/cru:

rm ~/.cargo/bin/cru

Remove configuration and data (optional)

These directories contain your settings, plugins, session history, and project registry. Only remove them if you want a clean slate:

# Configuration (config.toml, plugins, MCP settings, permission whitelists)
rm -rf ~/.config/crucible/

# Project registry and session data
rm -rf ~/.crucible/

# Runtime socket (auto-cleaned on reboot)
rm -f "${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}/crucible-$(id -u)}/crucible.sock"

Your kilns (note collections) are plain markdown directories and are never modified by uninstalling. They remain wherever you created them.