Quick Start

Set your API key

Heartbit uses Anthropic’s Claude models by default. Export your API key:

export ANTHROPIC_API_KEY=sk-...

Run your first task

Pass a task directly to the CLI. No config file needed:

heartbit "Analyze the Rust ecosystem"

Heartbit runs in standalone mode by default — a single agent with 14 built-in tools (bash, file read/write, search, and more), no infrastructure required.

Interactive chat

Start a multi-turn REPL session:

heartbit chat

Type your messages and the agent responds conversationally, maintaining context across turns. Press Ctrl+C to exit.

Using a config file

For multi-agent setups or custom configuration, create a heartbit.toml:

[provider]
name = "anthropic"
model = "claude-sonnet-4-20250514"

[[agents]]
name = "researcher"
description = "Research specialist"
system_prompt = "You are a research specialist."

[[agents]]
name = "writer"
description = "Writing specialist"
system_prompt = "You are a writing specialist."

Then run with the config:

heartbit run --config heartbit.toml "Write an article about Rust"

The orchestrator automatically delegates subtasks to the appropriate sub-agent.

Environment variables

Variable	Default	Description
ANTHROPIC_API_KEY	—	Anthropic API key (required)
HEARTBIT_MAX_TURNS	50	Maximum agent turns per task
HEARTBIT_TOOL_PROFILE	standard	Tool filtering: conversational, standard, or full
HEARTBIT_SESSION_PRUNE	false	Trim old tool results before LLM calls
HEARTBIT_RECURSIVE_SUMMARIZATION	false	Cluster-then-summarize for long conversations

CLI flags

Flag	Description
--config <path>	Path to heartbit.toml
--approve	Enable human-in-the-loop approval for tool calls
-v, --verbose	Emit agent events as JSON to stderr

Next steps

Ready to embed Heartbit in your own Rust application? Continue to Your First Agent.