zeroclaw agent

Start the AI agent loop with interactive chat or single-shot mode

Overview

The zeroclaw agent command launches an interactive chat session with your configured AI provider. It supports both interactive REPL mode and single-shot message execution.

Basic Usage

# Start interactive session
zeroclaw agent

# Single message mode
zeroclaw agent -m "Summarize today's logs"

Command Syntax

zeroclaw agent [OPTIONS]

Options

Core Options

-m, --message · string

Single message mode (don’t enter interactive mode). Send one message and exit.

-p, --provider · string

Provider to use (openrouter, anthropic, openai, openai-codex, gemini, etc.). Overrides config default.

--model · string

Model to use. Overrides config default.

-t, --temperature · float · default: "0.7"

Temperature (0.0 - 2.0). Controls response randomness.

Hardware Options

--peripheral · string[]

Attach a peripheral board. Format: board:path

Example: nucleo-f401re:/dev/ttyACM0

Security & Autonomy

--autonomy-level · enum

Autonomy level for agent execution.

Options:

• read_only - Agent can only read, no modifications
• supervised - Agent requires approval for actions
• full - Agent can execute actions autonomously

--max-actions-per-hour · integer

Maximum shell/tool actions per hour. Rate limiting for safety.

Agent Behavior

--max-tool-iterations · integer

Maximum tool-call iterations per message. Prevents infinite loops.

--max-history-messages · integer

Maximum conversation history messages to retain in context.

--compact-context · boolean

Enable compact context mode (smaller prompts for limited models).

Memory Options

--memory-backend · enum

Memory backend to use.

Options:

• sqlite - SQLite-based persistent memory
• markdown - Markdown file-based memory
• lucid - Advanced vector memory backend
• none - Disable memory

Examples

Interactive Session

# Start with default config
zeroclaw agent

# Use specific provider and model
zeroclaw agent -p anthropic --model claude-sonnet-4-20250514

# With hardware peripheral
zeroclaw agent --peripheral nucleo-f401re:/dev/ttyACM0

Single Message Mode

# Quick one-off task
zeroclaw agent -m "Summarize today's logs"

# With custom settings
zeroclaw agent -m "quick task" --memory-backend none --compact-context

# With specific autonomy settings
zeroclaw agent -m "deploy to prod" --autonomy-level supervised --max-actions-per-hour 100

Advanced Usage

# Full autonomy with rate limits
zeroclaw agent --autonomy-level full --max-actions-per-hour 100

# Limited context for constrained models
zeroclaw agent --compact-context --max-history-messages 10 --max-tool-iterations 5

# Disable memory for ephemeral session
zeroclaw agent --memory-backend none

Interactive Mode

When running without --message, the agent enters interactive mode with these features:

• Persistent conversation history - Context maintained across messages
• Tool execution approval - In supervised mode, prompts before actions
• Multi-turn interactions - Follow-up questions and iterative refinement
• Session memory - Conversation saved to configured memory backend

Interactive Commands

# In interactive mode:
> Your message here

# Exit the session
> exit
> quit
> Ctrl+D

Terminal Output

Interactive Session Example

$ zeroclaw agent
🦀 ZeroClaw Agent v0.1.0
Provider: anthropic
Model: claude-sonnet-4-20250514
Memory: sqlite
Autonomy: supervised

> Summarize the README file

🔧 Reading file: README.md

📝 Summary:
The README introduces ZeroClaw, a high-performance Rust-based
autonomous agent runtime optimized for speed and efficiency...

> exit
Goodbye!

Single Message Example

$ zeroclaw agent -m "What's the current time?"

🤖 The current time is 15:42:30 UTC (Tuesday, March 3, 2026).

$ _

Configuration

The agent respects these configuration settings from config.toml:

[agent]
max_tool_iterations = 10
max_history_messages = 50
compact_context = false

[autonomy]
level = "supervised"
max_actions_per_hour = 100
workspace_only = true

[memory]
backend = "sqlite"
auto_save = true

Command-line flags override config file settings for the current session only.

Exit Codes

• 0 - Success
• 1 - General error
• 2 - Configuration error
• 130 - Interrupted (Ctrl+C)

Related Commands

• zeroclaw config - Manage configuration settings
• zeroclaw gateway - Start webhook gateway for remote access
• zeroclaw daemon - Run full autonomous runtime

See Also

• Agent Configuration Reference
• Provider Reference
• Tool Reference
• Security Best Practices